# API JSON — `trocastatus-automatiza`

Actualiza `fg_status`, mensagens de display (`mensagem_1` … `mensagem_3`), opcionalmente `peso_ordem_pesagem` e `observacao` na tabela `integr_erp_conceitto` para uma dada `tag`.

O contrato de corpo e resposta alinha-se ao exemplo REST do PDF (`status`, array `messages`, resposta com `tag` e `status`). Neste repositório o endpoint exposto é **`POST /trocastatus-automatiza`** com JSON (padrão dos outros serviços HTTP aqui).

Tabela de códigos de status e regras de negócio descritas no contrato SOAP: [docs/servidor-castrolanda-soap-api.md](servidor-castrolanda-soap-api.md) (secção `trocastatus`).

---

## Endpoint

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

### URL (desenvolvimento)

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

---

## Corpo da requisição (JSON)

| Campo        | Obrigatório | Descrição |
| ------------ | ----------- | --------- |
| `tag`        | sim         | Identificador da tag (inteiro ≥ 1) |
| `status`     | sim         | Código de status. **`0`**: não altera `fg_status`; apenas mensagens (e opcionalmente `peso_ordem_pesagem`). **≠ 0**: actualiza `fg_status` e o restante conforme preenchido. |
| `messages`   | não         | Array de strings para o display; as **primeiras 3** posições correspondem a `mensagem_1`, `mensagem_2`, `mensagem_3`. Omisso ou `[]` → três strings vazias. |
| `pesoOrdem`  | não         | Se preenchido (após trim, valor numérico), o `UPDATE` inclui `peso_ordem_pesagem`. Vazio ou omissão → ramo sem essa coluna no `SET`. |
| `observacao` | não         | Texto gravado em `observacao`. Omisso → string vazia. |

### Exemplo (equivalente conceptual ao PDF)

```json
{
  "tag": 10000010,
  "status": 7,
  "messages": [
    "Pesagem Finalizada ",
    "Peso 32000 kg",
    "Saída Liberada"
  ]
}
```

Com `pesoOrdem` e `observacao`:

```json
{
  "tag": 10000010,
  "status": 7,
  "messages": ["Linha 1", "Linha 2", "Linha 3"],
  "pesoOrdem": 32000,
  "observacao": "nota interna"
}
```

---

## Resposta de sucesso

**HTTP 200**

```json
{
  "tag": 10000010,
  "status": 7
}
```

O `status` devolvido é o valor efectivo retornado pela camada de serviço após o `UPDATE` bem-sucedido (em condições normais coincide com o `status` enviado).

---

## 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`   | `tag` / `status` em falta ou inválidos; `messages` não é array; elemento de `messages` não escalar; `pesoOrdem` não numérico quando preenchido |
| 500  | `database_error`     | Falha PDO / Oracle |
| 500  | `server_error`       | Outros erros (ex.: falha ao preparar `UPDATE`) |

Com `APP_DEBUG=1` no `.env`, respostas `500` com `database_error` podem incluir `details` / `pdo_code` — apenas em desenvolvimento.

---

## Base de dados

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

---

## Auditoria opcional

Variável `API_AUDIT_LOG_PATH`: cada pedido com JSON válido (após validação) pode acrescentar uma linha JSON com `action` = `trocastatus_automatiza` e `resource` = `tag=<n>`. Não versionar o ficheiro de log.

---

## Como testar com Insomnia

1. **POST** `http://localhost:8000/trocastatus-automatiza`
2. Header `Content-Type: application/json`
3. Body JSON de exemplo acima; ajustar `tag` e `status` ao ambiente Oracle.

---

## Ficheiros relacionados

| Ficheiro | Função |
| -------- | ------ |
| [endpoints/trocastatus-automatiza.php](../endpoints/trocastatus-automatiza.php) | Handler HTTP |
| [lib/trocastatus.php](../lib/trocastatus.php) | `UPDATE` com quatro ramos e binds PDO |
| [lib/json_trocastatus_mapper.php](../lib/json_trocastatus_mapper.php) | Validação e mapeamento do JSON |
| [config/database.php](../config/database.php) | PDO Oracle |
| [public/index.php](../public/index.php) | Despacho da rota |

---

## Testes automatizados

```powershell
php tests/trocastatus_automatiza_mapper_test.php
```