PT EN

Leituras

URL base: $BUSINESS_API

O objecto

meter_serialstring · opcional

The meter's serial number; present on consumer reading listings

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

previous_valuestring · opcional
raw_consumptionstring · opcional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · opcional
has_rolloverboolean · opcional
sourcestring · opcional

um de mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · opcional

um de passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · opcional
is_billedboolean · opcional
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

route_idstring · opcional
cycle_idstring · opcional
assignment_idstring · opcional
valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
received_atstring (date-time) · obrigatório
methodstring · obrigatório

um de manual, consumer, remote, imported, estimated

submitted_bystring · obrigatório
source_idstring · opcional
external_idstring · opcional
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
statusstring · obrigatório

um de submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · opcional
estimate_reasonstring · opcional
review_reasonstring · opcional
review_reason_codestring · opcional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · opcional
reviewed_bystring · opcional
reviewed_atstring · opcional · anulável
supersedes_idstring · opcional
superseded_by_idstring · opcional
correction_reasonstring · opcional
created_atstring (date-time) · obrigatório
O objecto
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Listar leituras por validar

Registos

GET /readings/plausibility-review

Readings awaiting plausibility review with three-month context

Returns the review queue: readings in review_required status that the plausibility check flagged as high, negative or zero consumption, a page at a time (limit default 20, maximum 100, and after). Each item adds up to 12 accepted readings of the same meter from the previous three months, their average consumption and the high-consumption threshold derived from it. Requires business:readings:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Flagged readings with average, threshold and recent accepted readings

Permissões business:readings:read · Funções: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/readings/plausibility-review" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Flagged readings with average, threshold and recent accepted readings

Listar leituras

Registos

GET /readings

Returns a cursor-paginated page of meter readings in the tenant, with value, unit, method, status, plausibility result and the route, cycle and assignment they came from. Filters combine, and limit (default 20, maximum 100) and after page the results. Requires business:readings:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

meter_idstring · consulta · opcional

Returns only readings taken on this meter ID.

account_idstring · consulta · opcional

Returns only readings recorded for this account ID.

route_idstring · consulta · opcional

Returns only readings taken while working this reading route ID.

cycle_idstring · consulta · opcional

Returns only readings that belong to this reading cycle ID.

statusstring · consulta · opcional

Returns only readings in this status: submitted, validating, accepted, review_required, rejected or superseded; any other value returns 400.

um de submitted, validating, accepted, review_required, rejected, superseded

methodstring · consulta · opcional

Returns only readings captured this way: manual, consumer, remote, imported or estimated; any other value returns 400.

um de manual, consumer, remote, imported, estimated

measured_fromstring (date-time) · consulta · opcional

RFC 3339 timestamp; returns only readings measured at or after this instant, and it must not be later than measured_to (400 otherwise).

measured_tostring (date-time) · consulta · opcional

RFC 3339 timestamp; returns only readings measured at or before this instant.

Devolve

200 Readings in the authenticated utility tenant

Permissões business:readings:read · Funções: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/readings" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Readings in the authenticated utility tenant

Submeter uma leitura manual

Registos

POST /readings

Records a reading taken by staff and returns 202 with the reading, whose status is submitted or review_required depending on the plausibility check; a manual reading also logs a field visit. meter_id, client_reading_id, idempotency_key, measured_at, value and the meter's unit are required, the meter must be active, and measured_at cannot be before installation or more than 5 minutes in the future. Retrying with the same idempotency_key and identical data returns the original reading, while different data returns 409. Sending a readings array instead records up to 500 readings and returns 207 with a per-item result.

Corpo application/json

meter_idstring · obrigatório
assignment_idstring · opcional

Optional in-progress assignment that authorizes this field reading and supplies route/cycle provenance.

valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
evidence_idsarray of string · opcional
estimate_reasonstring · opcional

Devolve

202 Reading recorded for validation or review

Mostrar atributos
meter_serialstring · opcional

The meter's serial number; present on consumer reading listings

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

previous_valuestring · opcional
raw_consumptionstring · opcional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · opcional
has_rolloverboolean · opcional
sourcestring · opcional

um de mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · opcional

um de passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · opcional
is_billedboolean · opcional
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

route_idstring · opcional
cycle_idstring · opcional
assignment_idstring · opcional
valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
received_atstring (date-time) · obrigatório
methodstring · obrigatório

um de manual, consumer, remote, imported, estimated

submitted_bystring · obrigatório
source_idstring · opcional
external_idstring · opcional
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
statusstring · obrigatório

um de submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · opcional
estimate_reasonstring · opcional
review_reasonstring · opcional
review_reason_codestring · opcional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · opcional
reviewed_bystring · opcional
reviewed_atstring · opcional · anulável
supersedes_idstring · opcional
superseded_by_idstring · opcional
correction_reasonstring · opcional
created_atstring (date-time) · obrigatório

Permissões business:readings:create · Funções: admin, field_reader, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason"
}'
Resposta 202
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Obter uma leitura

Registos

GET /readings/{id}

Returns one meter reading with its value, unit, method, status, plausibility result, evidence and review details. A reading that does not exist in the tenant returns 404. Requires business:readings:read.

Parâmetros

idstring · caminho · obrigatório

ID of the meter reading to return.

Devolve

200 Reading details

Mostrar atributos
meter_serialstring · opcional

The meter's serial number; present on consumer reading listings

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

previous_valuestring · opcional
raw_consumptionstring · opcional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · opcional
has_rolloverboolean · opcional
sourcestring · opcional

um de mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · opcional

um de passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · opcional
is_billedboolean · opcional
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

route_idstring · opcional
cycle_idstring · opcional
assignment_idstring · opcional
valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
received_atstring (date-time) · obrigatório
methodstring · obrigatório

um de manual, consumer, remote, imported, estimated

submitted_bystring · obrigatório
source_idstring · opcional
external_idstring · opcional
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
statusstring · obrigatório

um de submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · opcional
estimate_reasonstring · opcional
review_reasonstring · opcional
review_reason_codestring · opcional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · opcional
reviewed_bystring · opcional
reviewed_atstring · opcional · anulável
supersedes_idstring · opcional
superseded_by_idstring · opcional
correction_reasonstring · opcional
created_atstring (date-time) · obrigatório

Permissões business:readings:read · Funções: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/readings/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Aceitar uma leitura

Registos

POST /readings/{id}/accept

Accepts a reading so it can be used for consumption and billing, records the reviewer and the status change, and returns the updated reading. Only readings in submitted or review_required status can be accepted; any other status returns 409. Requires business:readings:review.

Parâmetros

idstring · caminho · obrigatório

ID of the meter reading to accept.

Devolve

200 Accepted reading

Mostrar atributos
meter_serialstring · opcional

The meter's serial number; present on consumer reading listings

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

previous_valuestring · opcional
raw_consumptionstring · opcional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · opcional
has_rolloverboolean · opcional
sourcestring · opcional

um de mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · opcional

um de passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · opcional
is_billedboolean · opcional
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

route_idstring · opcional
cycle_idstring · opcional
assignment_idstring · opcional
valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
received_atstring (date-time) · obrigatório
methodstring · obrigatório

um de manual, consumer, remote, imported, estimated

submitted_bystring · obrigatório
source_idstring · opcional
external_idstring · opcional
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
statusstring · obrigatório

um de submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · opcional
estimate_reasonstring · opcional
review_reasonstring · opcional
review_reason_codestring · opcional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · opcional
reviewed_bystring · opcional
reviewed_atstring · opcional · anulável
supersedes_idstring · opcional
superseded_by_idstring · opcional
correction_reasonstring · opcional
created_atstring (date-time) · obrigatório

Permissões business:readings:review · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings/{id}/accept" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Rejeitar uma leitura

Registos

POST /readings/{id}/reject

Rejects a reading so it is not used for consumption or billing, records the reviewer, the reason and the status change, and returns the updated reading. A reason of 1 to 500 characters is required (400 otherwise). Only readings in submitted or review_required status can be rejected; any other status returns 409. Requires business:readings:review.

Parâmetros

idstring · caminho · obrigatório

ID of the meter reading to reject.

Corpo application/json

reasonstring · obrigatório

Devolve

200 Rejected reading

Mostrar atributos
meter_serialstring · opcional

The meter's serial number; present on consumer reading listings

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

previous_valuestring · opcional
raw_consumptionstring · opcional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · opcional
has_rolloverboolean · opcional
sourcestring · opcional

um de mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · opcional

um de passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · opcional
is_billedboolean · opcional
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

route_idstring · opcional
cycle_idstring · opcional
assignment_idstring · opcional
valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
received_atstring (date-time) · obrigatório
methodstring · obrigatório

um de manual, consumer, remote, imported, estimated

submitted_bystring · obrigatório
source_idstring · opcional
external_idstring · opcional
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
statusstring · obrigatório

um de submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · opcional
estimate_reasonstring · opcional
review_reasonstring · opcional
review_reason_codestring · opcional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · opcional
reviewed_bystring · opcional
reviewed_atstring · opcional · anulável
supersedes_idstring · opcional
superseded_by_idstring · opcional
correction_reasonstring · opcional
created_atstring (date-time) · obrigatório

Permissões business:readings:review · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Resposta 200
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Corrigir uma leitura aceite

Registos

POST /readings/{id}/corrections

Create an immutable correction that supersedes an accepted reading

The accepted source observation remains preserved as a superseded record; the correction requires a reason and idempotency key.

Parâmetros

idstring · caminho · obrigatório

ID of the accepted meter reading to correct; the correction is created as a new reading that supersedes it.

Corpo application/json

valuestring · obrigatório
reasonstring · obrigatório
idempotency_keystring · obrigatório

Devolve

201 Corrected reading created

Mostrar atributos
meter_serialstring · opcional

The meter's serial number; present on consumer reading listings

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

previous_valuestring · opcional
raw_consumptionstring · opcional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · opcional
has_rolloverboolean · opcional
sourcestring · opcional

um de mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · opcional

um de passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · opcional
is_billedboolean · opcional
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

route_idstring · opcional
cycle_idstring · opcional
assignment_idstring · opcional
valuestring · obrigatório
unitstring · obrigatório
measured_atstring (date-time) · obrigatório
received_atstring (date-time) · obrigatório
methodstring · obrigatório

um de manual, consumer, remote, imported, estimated

submitted_bystring · obrigatório
source_idstring · opcional
external_idstring · opcional
client_reading_idstring · obrigatório
idempotency_keystring · obrigatório
statusstring · obrigatório

um de submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · opcional
estimate_reasonstring · opcional
review_reasonstring · opcional
review_reason_codestring · opcional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · opcional
reviewed_bystring · opcional
reviewed_atstring · opcional · anulável
supersedes_idstring · opcional
superseded_by_idstring · opcional
correction_reasonstring · opcional
created_atstring (date-time) · obrigatório

Permissões business:readings:correct · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings/{id}/corrections" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "value": "value",
  "reason": "Leitura confirmada no local.",
  "idempotency_key": "idempotency key"
}'
Resposta 201
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}