# API JSON — `gera-ticket-automatiza`

Comanda a emissão ou reimpressão do ticket de pesagem, actualizando `TICKETGER.STATUS` para **0** na linha cujo `PEDIDO` coincide com a ordem indicada.

Contrato alinhado ao exemplo REST do PDF (`POST /api/vehicles/ticket/{nrOrdem}` com corpo `{ "status": 1 }`). Neste repositório usa-se **`POST /gera-ticket-automatiza`** com `nrOrdem` e `status` no JSON.

Comportamento do serviço SOAP: [docs/servidor-castrolanda-soap-api.md](servidor-castrolanda-soap-api.md) (secção 4.2 `gera_ticket`).

---

## Endpoint

| Item         | Valor |
| ------------ | ----- |
| Método       | `POST` |
| Path         | `/gera-ticket-automatiza` |
| Content-Type | `application/json` |

### URL (desenvolvimento)

`http://localhost:8000/gera-ticket-automatiza` com `php -S 0.0.0.0:8000 router.php` na pasta `public/` ([README.md](../README.md)).

---

## Corpo da requisição (JSON)

| Campo    | Obrigatório | Descrição |
| -------- | ----------- | --------- |
| `nrOrdem` | sim        | Inteiro ≥ 1 — número da ordem de pesagem (`TICKETGER.PEDIDO`). |
| `status`  | sim        | Inteiro. **No serviço original este valor não é usado no SQL**; o `UPDATE` fixa sempre `STATUS = 0`. O campo mantém-se no JSON por compatibilidade com o contrato REST / SOAP. |

### Exemplo

```json
{
  "nrOrdem": 10,
  "status": 1
}
```

---

## Resposta de sucesso

**HTTP 200**

```json
{
  "message": "Ticket enviado para impressão"
}
```

Se não existir linha em `TICKETGER` para essa ordem, o `UPDATE` pode afectar **0 linhas**; o comportamento do legado continua a ser **sucesso** (sem erro) desde que o `execute` não falhe.

---

## Erros (JSON)

| HTTP | `error`              | Quando |
| ---- | -------------------- | ------ |
| 400  | `invalid_json`       | Corpo vazio ou JSON inválido |
| 405  | `method_not_allowed` | Método diferente de POST |
| 422  | `validation_error`   | `nrOrdem` ou `status` em falta ou inválidos |
| 500  | `database_error`     | Falha PDO / Oracle |
| 500  | `server_error`       | Falha ao preparar ou executar o `UPDATE` |

Com `APP_DEBUG=1` no `.env`, `database_error` pode incluir `details` / `pdo_code` — apenas em desenvolvimento.

---

## Base de dados

Credenciais Oracle: `.env` na raiz (`ORACLE_*`) — [README.md](../README.md), [docs/oracle-php-windows.md](oracle-php-windows.md).

---

## Auditoria opcional

`API_AUDIT_LOG_PATH`: após validação, pode registar-se uma linha com `action` = `gera_ticket` e `resource` = `nr_ordem=<n>`.

---

## Como testar com Insomnia

1. **POST** `http://localhost:8000/gera-ticket-automatiza`
2. Header `Content-Type: application/json`
3. Body: `{ "nrOrdem": 10, "status": 1 }` (ajustar `nrOrdem` ao ambiente).

---

## Ficheiros relacionados

| Ficheiro | Função |
| -------- | ------ |
| [endpoints/gera-ticket-automatiza.php](../endpoints/gera-ticket-automatiza.php) | Handler HTTP |
| [lib/gera_ticket.php](../lib/gera_ticket.php) | `UPDATE TICKETGER` |
| [lib/json_gera_ticket_mapper.php](../lib/json_gera_ticket_mapper.php) | Validação e mapeamento |
| [config/database.php](../config/database.php) | PDO Oracle |
| [public/index.php](../public/index.php) | Despacho da rota |

---

## Testes automatizados

```powershell
php tests/gera_ticket_automatiza_mapper_test.php
```