# API JSON — `precad_automatiza`

Equivalente operacional ao método SOAP `precad_automatiza` do legado (`legado/server/servidor.php`), com entrada/saída em JSON. A lógica de base de dados replica `precad()` (INSERT `integr_erp_conceitto` + `UPDATE tagbal`).

---

## Endpoint


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


### URLs (escolher uma conforme o servidor)

1. **Servidor embutido PHP com router** (recomendado para desenvolvimento):
  Na pasta `public/` do repositório:
   URL: `http://localhost:8080/precad-automatiza`
2. **Script dedicado** (sem router):
  Com docroot `public/`:
   URL: `http://localhost:8080/precad-automatiza.php`
3. **Apache / IIS / nginx**
  Apontar o document root para `public/` e, se necessário, reescrever `/precad-automatiza` para `index.php` ou servir `precad-automatiza.php`.

---

## Corpo da requisição (JSON)

### Campos obrigatórios


| Campo         | Tipo             | Descrição                                                                                             |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `tag`         | número ou string | Tag do veículo (ligação ao `tagbal`)                                                                  |
| `placaCavalo` | string           | Placa cavalo                                                                                          |
| `dataOrdem`   | string           | Data/hora da ordem; aceita os formatos do legado e **ISO 8601** com `Z` (ex.: `2024-10-30T08:00:00Z`) |


### Campos opcionais (omissão = string vazia, como no SOAP)


| Campo           | Tipo             | Mapa interno (legado) |
| --------------- | ---------------- | --------------------- |
| `placaCarreta`  | string           | `placa_carreta`       |
| `transportador` | string           | `transportador`       |
| `motorista`     | string           | `motorista`           |
| `razaoSocial`   | string           | `razaosocial`         |
| `cnpj`          | string           | `cpfcnpj`             |
| `ie`            | string           | `ie`                  |
| `endereco`      | string           | `endereco`            |
| `municipio`     | string           | `municipio`           |
| `uf`            | string           | `uf`                  |
| `produto`       | string           | `produto`             |
| `nrOrdem`       | número ou string | `ordem_pesagem`       |
| `tpPesagem`     | string           | `tp_pesagem`          |


### Exemplo

```json
{
  "tag": 10000010,
  "placaCavalo": "ABC1234",
  "placaCarreta": "ABC1010",
  "transportador": "EMPRESA TRANSPORTES",
  "motorista": "PEDRO DA SILVA",
  "razaoSocial": "FAZENDA EXEMPLO 01",
  "endereco": "ENDEREÇO CLIENTE OU ORIGEM",
  "municipio": "MUNICIPIO CLIENTE OU ORIGEM",
  "produto": "S",
  "dataOrdem": "2024-10-30T08:00:00Z",
  "nrOrdem": 10
}
```

---

## Resposta de sucesso

**HTTP 200**

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

O `status` corresponde ao retorno inteiro de `precad` no legado (sucesso = `1`).

---

## 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`   | Falta `tag`, `placaCavalo` ou `dataOrdem`; ou `data_ordem` inválida após normalização |
| 500  | `database_error`     | Falha PDO / Oracle                                                                    |
| 500  | `server_error`       | Outros erros de execução                                                              |

Com `APP_DEBUG=1` no `.env`, a resposta `500` com `database_error` pode incluir `details` (mensagem técnica PDO/Oracle) e opcionalmente `pdo_code` — **apenas em desenvolvimento**; desative em produção.

Exemplo 422:

```json
{
  "error": "validation_error",
  "message": "tag é obrigatório",
  "details": ["tag é obrigatório"]
}
```

---

## Variáveis de ambiente (`.env`)

Copiar `.env.example` para `.env` na **raiz do repositório** e preencher (nunca commitar `.env`).


| Variável          | Descrição                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `ORACLE_USER`     | Utilizador Oracle (obrigatório)                                                                                                    |
| `ORACLE_PASSWORD` | Palavra-passe                                                                                                                      |
| `ORACLE_HOST`     | Host (ex.: `192.168.104.101`)                                                                                                      |
| `ORACLE_PORT`     | Porta (padrão `1521`)                                                                                                              |
| `ORACLE_SID`      | SID (padrão `xe`, igual ao legado)                                                                                                 |
| `INSERT_LOG_PATH` | Opcional; ficheiro de log de debug do `precad`. Por omissão: `C:\TMP\insert_log.txt` (comportamento alinhado ao legado em Windows) |
| `APP_DEBUG`       | Opcional; `1` / `true` / `yes` para incluir `details` (mensagem PDO/Oracle) em erros `database_error` — só em desenvolvimento        |


TNS construído como no legado: `(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=...)(PORT=...)))(CONNECT_DATA=(SID=...)))`.

---

## Requisitos PHP / Oracle

1. Extensão **PDO_OCI** (e Oracle Instant Client instalado e no `PATH` / `LD_LIBRARY_PATH`).
2. PHP 8.0+ recomendado (`declare(strict_types=1)` nos módulos novos).

Verificar:

```bash
php -m | findstr oci
```

(Em Linux: `php -m | grep -i oci`)

---

## Equivalência com o SOAP legado


| SOAP `precad_automatiza`                      | API JSON                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------ |
| Parâmetros snake_case                         | camelCase no JSON (mapeamento na camada HTTP)                            |
| Retorno `"{placa_cavalo},{status}"`           | `{ "tag", "status" }`                                                    |
| Mesmo INSERT / UPDATE / normalização de datas | `lib/precad.php` + pré-processamento ISO em `lib/json_precad_mapper.php` |


---

## Como testar com Insomnia

1. Criar **New Request** → método **POST**.
2. URL: `http://localhost:8080/precad-automatiza` (se usar `php -S ... router.php` na pasta `public`) **ou** `http://localhost:8080/precad-automatiza.php` (com `-t public`).
3. Separador **Header**: adicionar `Content-Type` = `application/json`.
4. Separador **Body** → **JSON**: colar o exemplo de corpo acima; ajustar `tag` e credenciais Oracle no `.env` para o teu ambiente.
5. **Send**: esperar **200** e corpo `{"tag":...,"status":1}`.

Se aparecer **500** `database_error`, confirmar Instant Client, extensão `pdo_oci`, rede até ao host Oracle e utilizador/schema corretos.

---

## Ficheiros relacionados


| Ficheiro                                                              | Função                                      |
| --------------------------------------------------------------------- | ------------------------------------------- |
| [endpoints/precad-automatiza.php](../endpoints/precad-automatiza.php) | Handler HTTP + validação JSON               |
| [lib/precad.php](../lib/precad.php)                                   | Lógica espelhada do `precad` legado         |
| [lib/json_precad_mapper.php](../lib/json_precad_mapper.php)           | Validação obrigatórios, camelCase, ISO 8601 |
| [config/database.php](../config/database.php)                         | `.env` + PDO Oracle                         |
| [public/router.php](../public/router.php)                             | Router servidor embutido                    |
| [public/index.php](../public/index.php)                               | Despacho `/precad-automatiza`               |


---

## Testes automatizados

Ver `tests/precad_automatiza_mapper_test.php` (execução com `php tests/precad_automatiza_mapper_test.php`).