# Registar leituras de contadores

Envie leituras pela API sem duplicados em caso de nova tentativa, interprete o resultado da verificação de plausibilidade e aceite ou rejeite a leitura antes da facturação.


## O que vai construir

Uma integração que lê os valores de um sistema externo (um terminal de campo, uma folha exportada, um sistema de telemetria) e os entrega como leituras de contador. Cada leitura passa por uma verificação de plausibilidade à chegada e fica `submitted` ou `review_required`; só depois de `accepted` entra no cálculo de consumos e na facturação. No fim terá enviado uma leitura, repetido o envio sem criar um duplicado e aceite a leitura pela API.

## Pré-requisitos

- Uma sandbox com os dados de exemplo (contadores instalados e leituras anteriores).
- Uma chave de API de teste com `business:meters:read` e `business:readings:read` para consultar, `business:readings:create` para enviar e `business:readings:review` para aceitar ou rejeitar.

## 1. Escolher um contador activo

Só se aceitam leituras de contadores com estado `active`.

```bash
curl -sS "$BUSINESS_API/meters?status=active&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].id` começa por `mtr_`; anote também `unit` (`m3` nos contadores de água deste exemplo) e `precision`, o número de casas decimais que o valor pode ter.

## 2. Ver a última leitura aceite

O valor seguinte deve ser igual ou superior a este, salvo uma volta do mostrador.

```bash
curl -sS "$BUSINESS_API/readings?meter_id=mtr_3aIlrbKkunoeedv9MrqJIL2rdzh&status=accepted&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].value` é um texto decimal, por exemplo `"1231.870"`, e `data[0].measured_at` indica quando foi lido.

## 3. Enviar a leitura

`value` vai como texto, para não perder casas decimais. `client_reading_id` identifica a leitura no seu sistema (até 120 caracteres) e `idempotency_key` (até 160) protege contra envios repetidos. `measured_at` não pode ser anterior à instalação do contador nem estar mais de 5 minutos no futuro, e `unit` tem de coincidir com a do contador.

```bash
curl -sS -X POST "$BUSINESS_API/readings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"meter_id":"mtr_3aIlrbKkunoeedv9MrqJIL2rdzh","value":"1245.320","unit":"m3","measured_at":"2026-11-19T08:40:00Z","client_reading_id":"rota-07-2026-11-0153","idempotency_key":"rota-07-2026-11-0153"}'
```

Resposta `202 Accepted`, resumida:

```json
{
  "id": "rdg_3ocbvsab7pwoXJTg5ThlDX47TVc",
  "tenant_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
  "meter_id": "mtr_3aIlrbKkunoeedv9MrqJIL2rdzh",
  "account_id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
  "value": "1245.320",
  "previous_value": "1231.870",
  "raw_consumption": "13.450",
  "unit": "m3",
  "method": "manual",
  "status": "submitted",
  "plausibility_status": "passed",
  "measured_at": "2026-11-19T08:40:00Z",
  "received_at": "2026-11-19T08:41:07Z",
  "client_reading_id": "rota-07-2026-11-0153",
  "idempotency_key": "rota-07-2026-11-0153",
  "submitted_by": "key_3f5kSeI9SXDLwgbb5hilkGVvprT",
  "created_at": "2026-11-19T08:41:07Z"
}
```

✓ Checkpoint: `status` é `submitted`. Se a verificação desconfiar do valor, vem `review_required`, com `review_reason_code` a explicar porquê (por exemplo `reading_review.earlier_or_lower` para um valor abaixo do anterior ou `reading_review.above_three_month_average` para um consumo acima do triplo da média dos últimos três meses).

Volte a enviar exactamente o mesmo pedido: recebe a mesma leitura, com o mesmo `id`. Com a mesma `idempotency_key` e dados diferentes a resposta é `409` com `error_code` `request.idempotency_conflict`. Para enviar até 500 leituras de uma vez, mande um objecto com a lista `readings`, em que cada elemento tem os campos acima; a resposta `207` traz `results`, com `status` e `error` de cada `client_reading_id`.

## 4. Aceitar ou rejeitar

```bash
curl -sS -X POST "$BUSINESS_API/readings/rdg_3ocbvsab7pwoXJTg5ThlDX47TVc/accept" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: a leitura volta com `"status": "accepted"`, `reviewed_by` e `reviewed_at` preenchidos. Para recusar, use `POST /readings/{id}/reject` com `{"reason":"Fotografia ilegível"}` (1 a 500 caracteres). Ambas só funcionam em leituras `submitted` ou `review_required`; noutro estado a resposta é `409`. Uma leitura já aceite corrige-se com `POST /readings/{id}/corrections`, que cria uma nova leitura e marca a original como `superseded`.

## Testar

No painel, a leitura aparece na página **Leituras**; as que ficaram em `review_required` aparecem também em **Revisão de leituras**, onde um revisor as pode aceitar ou rejeitar. Com `gotactl webhooks listen --forward-to http://localhost:3000/hook --events reading.accepted,reading.flagged` vê chegar `reading.accepted` quando aceita e `reading.flagged` quando a verificação de plausibilidade assinala um valor. Para consultar sem curl, `gotactl readings list --meter-id mtr_3aIlrbKkunoeedv9MrqJIL2rdzh` lista as leituras do contador.

## Próximos passos

- [Emitir facturas a partir das leituras aceites](/docs/guides/issue-invoices)
- [Ouvir os eventos reading.accepted e reading.flagged](/docs/guides/listen-webhooks)
- [Idempotência: o cabeçalho Idempotency-Key nos restantes POST](/docs/getting-started/idempotency)
- [Erros: ler error_code e invalid_params](/docs/getting-started/errors)

