PT EN

Contadores: Acções

URL base: $BUSINESS_API

Listar instalações de um contador

Registos

GET /meters/{id}/installations

Returns every installation of this meter, past and current, with the connection, account, installation time, initial reading and seal number, using cursor pagination. Requires the business:meters:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter whose installation history is listed.

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Installations, newest first

Mostrar atributos
dataarray of MeterInstallation · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
connection_idstring · obrigatório
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. 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.

account_idstring · opcional
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.

installed_atstring (date-time) · obrigatório
initial_readingstring · obrigatório
removed_atstring · opcional · anulável
final_readingstring · opcional
exchange_reasonstring · opcional
installed_bystring · obrigatório
security_seal_numberstring · opcional
replaced_installation_idstring · opcional
idempotency_keystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 403

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

curl -X GET "$BUSINESS_API/meters/{id}/installations" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "met_2yk9v6SNluyXngonlgs1hccPdGU",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
      "connection_holder_name": "Ana Matsinhe",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "installed_at": "2026-11-19T09:30:00Z",
      "initial_reading": "initial reading",
      "removed_at": "2026-11-19T09:30:00Z",
      "final_reading": "final reading",
      "exchange_reason": "exchange reason",
      "installed_by": "installed by",
      "security_seal_number": "SEC-2026-000142",
      "replaced_installation_id": "rep_2rLgATXYm9pMiLbYyNLwCPHAGTv",
      "idempotency_key": "idempotency key",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Obter o balanço de um contador geral

Registos

GET /meters/{id}/balance

Compute water balance for a master meter against its sub-meters

Sums the consumption recorded for the master meter and for each of its sub-meters over the period (litres are converted to cubic metres) and returns the unaccounted loss, the loss percentage and a negative_balance flag when the sub-meters add up to more than the master. Returns 400 when the meter is not a master meter or the period ends before it starts. Requires the business:meters:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of a meter whose role is master.

fromstring (date-time) · consulta · opcional

RFC 3339 start of the period, matched against the end of each consumption period; defaults to the first day of the current month in UTC.

tostring (date-time) · consulta · opcional

RFC 3339 end of the period; defaults to the first day of next month in UTC and must not be before from.

Devolve

200 Master meter water balance

Mostrar atributos
master_meter_idstring · opcional
serial_numberstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
master_consumption_m3number · opcional
submeters_consumption_m3number · opcional
unaccounted_loss_m3number · opcional
loss_percentnumber · opcional
negative_balanceboolean · opcional
submeter_countinteger · opcional
submetersarray of SubmeterBalanceEntry · opcional
Mostrar atributos filhos
meter_idstring · opcional
serial_numberstring · opcional
account_idstring · opcional
consumption_m3number · opcional

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

curl -X GET "$BUSINESS_API/meters/{id}/balance" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "master_meter_id": "mas_2Uq5JwONfeqHfCIDxsqZNqUJNOY",
  "serial_number": "SER-2026-000142",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "master_consumption_m3": 13.42,
  "submeters_consumption_m3": 13.42,
  "unaccounted_loss_m3": 1,
  "loss_percent": 1,
  "negative_balance": true,
  "submeter_count": 1,
  "submeters": [
    {
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "serial_number": "SER-2026-000142",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "consumption_m3": 13.42
    }
  ]
}

Alterar o estado de um contador

Registos

PATCH /meters/{id}/status

Sets the meter's status to active, inactive or retired and returns 204 with no body; setting the status it already has changes nothing. Retiring a meter records its removal time and marks the device as scrapped. Returns 400 for any other status and 404 when the meter does not exist. Requires the business:meters:manage permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter in the caller's tenant.

Corpo application/json

statusstring · obrigatório

um de active, inactive, retired

Devolve

204 Meter status updated

Erros 400 · 403 · 404

Permissões business:meters:manage · Funções: admin, operations, owner

curl -X PATCH "$BUSINESS_API/meters/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Resposta 204

Meter status updated

Listar reposições de um contador

Registos

GET /meters/{id}/resets

Returns the resets recorded for the meter, each with the prior and new reading values, reason, reset time and the user who authorized it, using cursor pagination. Requires the business:meters:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter whose resets are listed.

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Meter resets recorded for this meter

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

reset_atstring (date-time) · obrigatório
prior_reading_valuestring · obrigatório
reset_reading_valuestring · obrigatório
reasonstring · obrigatório
authorized_bystring · obrigatório
idempotency_keystring · obrigatório
created_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 403

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

curl -X GET "$BUSINESS_API/meters/{id}/resets" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "met_21FsuzPQGN5aoRn4qbXm4zhaCTz",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "reset_at": "2026-11-19T09:30:00Z",
      "prior_reading_value": "prior reading value",
      "reset_reading_value": "reset reading value",
      "reason": "Leitura confirmada no local.",
      "authorized_by": "authorized by",
      "idempotency_key": "idempotency key",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Registar a reposição de um contador

Registos

POST /meters/{id}/reset

Records a reset of the meter's register: reset_reading_value becomes the new baseline and prior_reading_value (defaulting to the last accepted reading at or before reset_at) is kept for audit; reset_at defaults to now and must fall between installation and now. reason and idempotency_key are required; repeating the key with identical values returns the existing reset, and with different values returns 409. Returns 409 when the meter is not active. Requires the business:meters:manage permission.

Parâmetros

idstring · caminho · obrigatório

ID of the active meter being reset.

Corpo application/json

reset_atstring (date-time) · opcional
prior_reading_valuestring · opcional
reset_reading_valuestring · obrigatório
reasonstring · obrigatório
idempotency_keystring · obrigatório

Devolve

201 Meter reset recorded

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

reset_atstring (date-time) · obrigatório
prior_reading_valuestring · obrigatório
reset_reading_valuestring · obrigatório
reasonstring · obrigatório
authorized_bystring · obrigatório
idempotency_keystring · obrigatório
created_atstring (date-time) · obrigatório

Erros 400 · 403 · 404 · 409

Permissões business:meters:manage · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/{id}/reset" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reset_at": "2026-11-19T09:30:00Z",
  "prior_reading_value": "prior reading value",
  "reset_reading_value": "reset reading value",
  "reason": "Leitura confirmada no local.",
  "idempotency_key": "idempotency key"
}'
Resposta 201
{
  "id": "met_21FsuzPQGN5aoRn4qbXm4zhaCTz",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "reset_at": "2026-11-19T09:30:00Z",
  "prior_reading_value": "prior reading value",
  "reset_reading_value": "reset reading value",
  "reason": "Leitura confirmada no local.",
  "authorized_by": "authorized by",
  "idempotency_key": "idempotency key",
  "created_at": "2026-11-19T09:30:00Z"
}

Obter os metadados de um contador

Registos

GET /meters/{id}/metadata

Returns the key-value metadata stored on the meter, or an empty map when none is set. Returns 404 when the meter does not exist in the caller's tenant. Requires the business:metadata:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter in the caller's tenant, at most 120 characters.

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/meters/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Actualizar os metadados de um contador

Registos

PUT /meters/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the meter's existing metadata and returns the full result; keys not sent are kept, and sending a key with an empty string removes it. Keys must be 1 to 40 characters with no square brackets or control characters, values at most 500 characters, and a meter can hold at most 50 keys; violations return 400 listing each invalid field. Requires the business:metadata:write permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter in the caller's tenant, at most 120 characters.

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

curl -X PUT "$BUSINESS_API/meters/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Listar comandos de um contador

Registos

GET /meters/{id}/commands

Returns the commands queued for the meter with their status, type, assigned collector and timestamps, using cursor pagination. Requires the business:meter-commands:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter whose commands are listed.

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Meter commands

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

collector_idstring · obrigatório
typestring · obrigatório

um de read, inspect, synchronize, reset-alarm, disconnect, reconnect

statusstring · obrigatório

um de queued, leased, succeeded, failed, cancelled

requested_bystring · obrigatório
idempotency_keystring · obrigatório
reading_idstring · opcional
failure_reasonstring · opcional
attempt_countinteger · obrigatório
max_attemptsinteger · obrigatório
lease_expires_atstring (date-time) · opcional
not_beforestring (date-time) · obrigatório
expires_atstring (date-time) · opcional
completed_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 403

Permissões business:meter-commands:read · Funções: admin, operations, owner

curl -X GET "$BUSINESS_API/meters/{id}/commands" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "met_2bnQGDJiSNNWkZDKO3j04p3KOX7",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt",
      "type": "read",
      "status": "queued",
      "requested_by": "requested by",
      "idempotency_key": "idempotency key",
      "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
      "failure_reason": "failure reason",
      "attempt_count": 1,
      "max_attempts": 1,
      "lease_expires_at": "2026-11-19T09:30:00Z",
      "not_before": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "completed_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Enviar um comando a um contador

Registos

POST /meters/{id}/commands

Queue a command against a meter. read and inspect need business:meter-commands:create, synchronize and reset-alarm need supervise, disconnect and reconnect need actuate and are audited.

Queues the command for the collector assigned to the meter and returns it with 201 in queued status; it expires after 24 hours and is tried at most 5 times. An idempotency_key repeated for the same meter and type returns the existing command, and for a different meter or type returns 409. Returns 409 with code METER_NO_COLLECTOR when no collector is assigned, 404 when the meter is not in the tenant, and 400 for an unknown type or parameters larger than 8 KB.

Parâmetros

idstring · caminho · obrigatório

ID of the meter in the caller's tenant that the command is sent to.

Corpo application/json

typestring · obrigatório

um de read, inspect, synchronize, reset-alarm, disconnect, reconnect

idempotency_keystring · opcional
parametersobject · opcional

Devolve

201 Command queued

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

collector_idstring · obrigatório
typestring · obrigatório

um de read, inspect, synchronize, reset-alarm, disconnect, reconnect

statusstring · obrigatório

um de queued, leased, succeeded, failed, cancelled

requested_bystring · obrigatório
idempotency_keystring · obrigatório
reading_idstring · opcional
failure_reasonstring · opcional
attempt_countinteger · obrigatório
max_attemptsinteger · obrigatório
lease_expires_atstring (date-time) · opcional
not_beforestring (date-time) · obrigatório
expires_atstring (date-time) · opcional
completed_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 403 · 404 · 409

Permissões business:meter-commands:create · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/{id}/commands" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "read",
  "idempotency_key": "idempotency key",
  "parameters": {}
}'
Resposta 201
{
  "id": "met_2bnQGDJiSNNWkZDKO3j04p3KOX7",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt",
  "type": "read",
  "status": "queued",
  "requested_by": "requested by",
  "idempotency_key": "idempotency key",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "failure_reason": "failure reason",
  "attempt_count": 1,
  "max_attempts": 1,
  "lease_expires_at": "2026-11-19T09:30:00Z",
  "not_before": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Verificar se um contador aceita comandos

Registos

GET /meters/{id}/commands/capability

A meter without an active collector assignment cannot receive commands; creating one then answers 409 with code METER_NO_COLLECTOR.

Parâmetros

idstring · caminho · obrigatório

ID of the meter to check; the response says whether a collector is assigned to it and which one.

Devolve

200 Command capability

Mostrar atributos
has_collectorboolean · obrigatório
collector_idstring · opcional

Erros 403

Permissões business:meter-commands:read · Funções: admin, operations, owner

curl -X GET "$BUSINESS_API/meters/{id}/commands/capability" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "has_collector": true,
  "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt"
}

Obter um comando de um contador

Registos

GET /meters/{id}/commands/{command_id}

Returns one command with its type, status, parameters, assigned collector and timing. Returns 404 when the command does not exist in the tenant or belongs to a different meter than the one in the path. Requires the business:meter-commands:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the meter the command was sent to.

command_idstring · caminho · obrigatório

ID of the command; it must belong to the meter given in id.

Devolve

200 Meter command

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

collector_idstring · obrigatório
typestring · obrigatório

um de read, inspect, synchronize, reset-alarm, disconnect, reconnect

statusstring · obrigatório

um de queued, leased, succeeded, failed, cancelled

requested_bystring · obrigatório
idempotency_keystring · obrigatório
reading_idstring · opcional
failure_reasonstring · opcional
attempt_countinteger · obrigatório
max_attemptsinteger · obrigatório
lease_expires_atstring (date-time) · opcional
not_beforestring (date-time) · obrigatório
expires_atstring (date-time) · opcional
completed_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 403 · 404

Permissões business:meter-commands:read · Funções: admin, operations, owner

curl -X GET "$BUSINESS_API/meters/{id}/commands/{command_id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "met_2bnQGDJiSNNWkZDKO3j04p3KOX7",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "collector_id": "col_2vl2gTdyaxHyundGyxvIM7fsUtt",
  "type": "read",
  "status": "queued",
  "requested_by": "requested by",
  "idempotency_key": "idempotency key",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "failure_reason": "failure reason",
  "attempt_count": 1,
  "max_attempts": 1,
  "lease_expires_at": "2026-11-19T09:30:00Z",
  "not_before": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Mover um contador sem ligação

Registos

POST /meters/{id}/device-status

Move a meter that is not on a connection: testing, back to a warehouse, or scrap

The meter module stays the owner of the meter; inventory moves its serial in the same transaction and refuses the change when the serial is not where the action claims. Installed meters leave their connection through an exchange.

Parâmetros

idstring · caminho · obrigatório

Meter ID (mtr_)

Corpo application/json

statusstring · obrigatório

um de in_warehouse, in_testing, scrapped

location_idstring · opcional

Destination warehouse or van of a meter returned in_warehouse (the default warehouse when empty)

reasonstring · obrigatório

Devolve

200 Meter with its new device status

Erros 400 · 401 · 403 · 404 · 409

Permissões business:meters:manage · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/{id}/device-status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "in_warehouse",
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local."
}'
Resposta 200

Meter with its new device status