# API — consulta por balança (`consulta-automatiza`)

Consulta o estado associado a uma balança. Resposta em JSON (camelCase), alinhada ao modelo REST do PDF de especificação (`scaleId`, `tag`, `placaVeiculo`, `peso1`, `peso2`, `status`, `nrOrdem`).

---

## Endpoint

| Item   | Valor |
| ------ | ----- |
| Método | `GET` |

### URLs

1. **Servidor embutido PHP com router** (recomendado): na pasta `public/`, por exemplo  
   `http://localhost:8000/consulta-automatiza?scaleId=1`
2. **Apache / IIS / nginx**: document root `public/` e reescrita para o front controller, como em [README.md](../README.md).

---

## Parâmetros de query

| Parâmetro | Obrigatório | Descrição |
| --------- | ----------- | --------- |
| `scaleId` | um dos dois | Número da balança (inteiro ≥ 1) |
| `bal`     | um dos dois | Alias com o mesmo significado que `scaleId` |

Se enviar **ambos**, têm de ser **iguais**; caso contrário a API responde **422**.

Valores como string só com dígitos são aceites (ex.: `?scaleId=1`).

### Exemplos

```http
GET /consulta-automatiza?scaleId=1
GET /consulta-automatiza?bal=2
```

---

## Resposta com dados

**HTTP 200**

```json
{
  "scaleId": 1,
  "tag": 10000010,
  "placaVeiculo": "ABC-1234",
  "peso1": 12500,
  "peso2": 0,
  "status": 3,
  "nrOrdem": 10
}
```

---

## Resposta sem dados

Quando não existir informação na cadeia `supervisao` / `integr_erp_conceitto` para a balança indicada, a API responde **sempre HTTP 200** com o **mesmo conjunto de campos**, com valores vazios:

```json
{
  "scaleId": 1,
  "tag": null,
  "placaVeiculo": "",
  "peso1": null,
  "peso2": null,
  "status": null,
  "nrOrdem": null
}
```

O campo `scaleId` repete o valor pedido na query.

---

## Erros (JSON)

| HTTP | `error`              | Quando                                      |
| ---- | -------------------- | ------------------------------------------- |
| 405  | `method_not_allowed` | Método diferente de GET                     |
| 422  | `validation_error`   | Falta `scaleId`/`bal`, valor inválido, ou `scaleId` ≠ `bal` |
| 500  | `database_error`     | Falha PDO / Oracle                          |
| 500  | `server_error`       | Outros erros de execução (ex.: prepare)     |

Com `APP_DEBUG=1` no `.env`, a resposta `500` com `database_error` pode incluir `details` e opcionalmente `pdo_code` — **apenas em desenvolvimento**.

---

## Base de dados

1. `supervisao` (`tag_atu`, `peso`) filtrado por `id` = número da balança  
2. `integr_erp_conceitto` (`tag`, `placa_cavalo`, `qt_peso1`, `qt_peso2`, `fg_status`, `ORDEM_PESAGEM`) filtrado por `tag`

Credenciais e TNS: copiar `.env.example` para `.env` na raiz e preencher `ORACLE_*` (ver [README.md](../README.md) e [docs/oracle-php-windows.md](oracle-php-windows.md)).

---

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

| Variável             | Descrição |
| -------------------- | --------- |
| `API_AUDIT_LOG_PATH` | Opcional. Ficheiro (caminho absoluto): cada pedido com parâmetros válidos acrescenta **uma linha JSON** com `timestamp` (UTC ISO), `action` = `consulta_automatiza`, `resource` = `scale_id=<n>`, `user` = `anonymous`. Não versionar este ficheiro no Git. Se estiver vazio, não se escreve ficheiro. |

---

## Como testar com Insomnia

1. Novo pedido → método **GET**.
2. URL: `http://localhost:8000/consulta-automatiza?scaleId=1` (com `php -S 0.0.0.0:8000 router.php` na pasta `public/`).
3. **Send:** com Oracle acessível, esperar **200** com dados ou com campos vazios conforme acima.

4. (Opcional) Definir `API_AUDIT_LOG_PATH` no `.env` e confirmar uma linha por pedido válido.

---

## Ficheiros relacionados

| Ficheiro | Função |
| -------- | ------ |
| [endpoints/consulta-automatiza.php](../endpoints/consulta-automatiza.php) | Handler HTTP + auditoria opcional |
| [lib/pesagem.php](../lib/pesagem.php) | Consulta à base |
| [lib/json_consulta_mapper.php](../lib/json_consulta_mapper.php) | Validação de parâmetros e payloads de resposta |
| [config/database.php](../config/database.php) | `.env` + PDO Oracle |
| [public/index.php](../public/index.php) | Despacho `/consulta-automatiza` |

---

## Testes automatizados

```powershell
php tests/consulta_automatiza_mapper_test.php
```