PT EN

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"

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"

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"
}

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"

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#