# API JSON — `classifica-automatiza`

Recebe dados de classificação e demais campos necessários para o ticket de pesagem. Actualiza ou cria linha em `TICKETGER` com base em `integr_erp_conceitto_log` e, quando aplicável, insere linhas em `CLASSIFICA`.

Este passo é **obrigatório** em ambas as pesagens (entrada e saída), mesmo sem linhas de classificação — nesse caso envie `descontos` como array vazio `[]`.

Contrato alinhado ao exemplo REST do PDF (`POST /api/vehicles/classify`); neste repositório o path é `**POST /classifica-automatiza`**.

Regras de negócio e tabelas descritas no contrato SOAP: [docs/servidor-castrolanda-soap-api.md](servidor-castrolanda-soap-api.md) (secção 4.3 `classifica`).

---

## Endpoint


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


### URL (desenvolvimento)

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

---

## Corpo da requisição (JSON)

### Campos obrigatórios


| Campo         | Tipo             | Descrição                                  |
| ------------- | ---------------- | ------------------------------------------ |
| `nrOrdem`     | int ≥ 1          | Ordem de pesagem (`ORDEM_PESAGEM` no log)  |
| `numMoega`    | int              | Número da moega                            |
| `numNota`     | string ou número | Número da nota                             |
| `numTicket`   | int              | Número do ticket                           |
| `pesoSeco`    | int              | Peso seco (`PESOSECO` no update do ticket) |
| `pesoLiquido` | int              | Peso líquido (`PLIQUIDO`)                  |


### `descontos`


| Campo       | Tipo  | Descrição                                                                                                                                    |
| ----------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `descontos` | array | Lista de objetos `{ "descricao": string, "valor": string }`. Pode ser `**[]**` se não houver classificação. Se omitido, é tratado como `[]`. |


Cada item com `descricao` não vazia (após trim) gera um `INSERT` em `CLASSIFICA` (`NUMORDEM` = `nrOrdem`).

### Campos opcionais (strings; omissão = `""`)

`origem`, `destino`, `produto`, `usuarioPesagem`, `usuarioPesagem2`, `transportador`, `motorista`, `cidade`, `uf`, `tpAcondicionamento`, `dsObservacao`

### Exemplo (com classificação)

```json
{
  "nrOrdem": 10,
  "numMoega": 8,
  "numNota": "12345",
  "numTicket": 300,
  "pesoSeco": 14500,
  "pesoLiquido": 15001,
  "descontos": [
    { "descricao": "UMIDADE", "valor": "12.5%" },
    { "descricao": "QUEBRADOS", "valor": "5%" },
    { "descricao": "IMPUREZA", "valor": "1%" }
  ]
}
```

### Exemplo (sem classificação, fluxo obrigatório)

```json
{
  "nrOrdem": 10,
  "numMoega": 8,
  "numNota": "?",
  "numTicket": 300,
  "pesoSeco": 14500,
  "pesoLiquido": 15001,
  "descontos": []
}
```

---

## Resposta de sucesso

**HTTP 200**

```json
{
  "message": "Dados de classificação recebidos com sucesso"
}
```

---

## 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`   | Campos obrigatórios em falta ou tipos inválidos            |
| 404  | `not_found`          | Nenhuma linha em `integr_erp_conceitto_log` para `nrOrdem` |
| 500  | `database_error`     | Falha PDO / Oracle                                         |
| 500  | `server_error`       | Outros erros (ex.: datas inválidas no log)                 |


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

---

## Base de dados

Variáveis `ORACLE_*` no `.env` na raiz do repositório ([README.md](../README.md), [docs/oracle-php-windows.md](oracle-php-windows.md)).

---

## Auditoria opcional

`API_AUDIT_LOG_PATH`: após validação JSON, pode registar-se uma linha com `action` = `classifica` e `resource` = `nr_ordem=<n>`. Não versionar o ficheiro de log.

---

## Como testar com Insomnia

1. **POST** `http://localhost:8000/classifica-automatiza`
2. Header `Content-Type: application/json`
3. Corpo JSON de exemplo; `nrOrdem` tem de existir em `integr_erp_conceitto_log` no Oracle de teste.

---

## Ficheiros relacionados


| Ficheiro                                                                      | Função                 |
| ----------------------------------------------------------------------------- | ---------------------- |
| [endpoints/classifica-automatiza.php](../endpoints/classifica-automatiza.php) | Handler HTTP           |
| [lib/classifica.php](../lib/classifica.php)                                   | Lógica de persistência |
| [lib/json_classifica_mapper.php](../lib/json_classifica_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/classifica_automatiza_mapper_test.php
```