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:readebusiness:readings:readpara consultar,business:readings:createpara enviar ebusiness:readings:reviewpara aceitar ou rejeitar.
1. Escolher um contador activo#
Só se aceitam leituras de contadores com estado active.
curl -sS "$BUSINESS_API/meters?status=active&limit=1" \
-H "Authorization: Bearer $API_KEY"
2. Ver a última leitura aceite#
O valor seguinte deve ser igual ou superior a este, salvo uma volta do mostrador.
curl -sS "$BUSINESS_API/readings?meter_id=mtr_3aIlrbKkunoeedv9MrqJIL2rdzh&status=accepted&limit=1" \
-H "Authorization: Bearer $API_KEY"
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.
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:
{
"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"
}
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#
curl -sS -X POST "$BUSINESS_API/readings/rdg_3ocbvsab7pwoXJTg5ThlDX47TVc/accept" \
-H "Authorization: Bearer $API_KEY"
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.