PT EN

Consumos

URL base: $BUSINESS_API

Listar consumos aceites

Registos

GET /consumptions

List immutable consumption records selected from accepted readings

Returns the tenant's stored consumption records, one cursor page at a time. Each record covers one meter and billing cycle, references the accepted readings it was computed from, and states whether it is actual or estimated. Requires business:consumptions:read; an unknown method value or an invalid cursor returns 400.

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

Return only consumptions computed for this meter ID.

account_idstring · consulta · opcional

Return only consumptions belonging to this account ID (the account the meter was assigned to when the consumption was recorded).

cycle_idstring · consulta · opcional

Return only consumptions recorded for this billing cycle identifier.

methodstring · consulta · opcional

Return only consumptions of this kind: actual when both readings were actual, estimated when either reading was estimated; empty returns both.

um de actual, estimated

Devolve

200 Consumption records with selected reading IDs preserved

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

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

Consumption records with selected reading IDs preserved

Registar um consumo aceite

Registos

POST /consumptions

Select accepted readings and persist immutable meter consumption

Computes consumption for one meter between period_start and period_end and stores it as an immutable record for the given cycle_id. The baseline is the latest accepted reading at or before the period start (or the meter's installation time if it was installed inside the period) and the end is the latest accepted reading at or before period_end; meter resets and rollovers in between are accounted for. The result is marked estimated when either reading was estimated. Requires business:consumptions:create; missing fields or period_end not after period_start return 400, an unknown meter returns 404, and 409 is returned when no usable pair of accepted readings exists or a consumption already exists for that meter and cycle.

Corpo application/json

meter_idstring · obrigatório
cycle_idstring · obrigatório
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório

Devolve

201 Consumption selected and recorded for billing

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
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.

meter_idstring · obrigatório
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

cycle_idstring · obrigatório
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
from_reading_idstring · obrigatório
to_reading_idstring · obrigatório
valuestring · obrigatório
unitstring · obrigatório
methodstring · obrigatório

um de actual, estimated

created_atstring (date-time) · obrigatório

Permissões business:consumptions:create · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/consumptions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z"
}'
Resposta 201
{
  "id": "con_2nR0I9tA6XXk4bxUyjPqmvxi8nN",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "from_reading_id": "fro_2zXkivBGsXvOyvPqMFry433gEp5",
  "to_reading_id": "tor_2YMhF6MrDmIFLAyjLcYXv4YbHMe",
  "value": "value",
  "unit": "unit",
  "method": "actual",
  "created_at": "2026-11-19T09:30:00Z"
}