PT EN

Topologia: Balanço

URL base: $BUSINESS_API

Calcular o balanço de uma zona de medição

Registos

GET /topology/balance/dma/{id}

Read-only. Inflow comes from the DMA's inflow device, outflow is authorised consumption (billed plus unbilled metered) plus metered export. Check status before trusting the loss figure.

Parâmetros

idstring · caminho · obrigatório

ID of the district metered area (DMA) to balance; it must belong to the caller's tenant, and the window comes from the required from and to parameters (RFC 3339 instants or YYYY-MM-DD dates read as midnight UTC, at most 366 days apart).

fromstring · consulta · obrigatório

RFC 3339 instant or date

tostring · consulta · obrigatório

RFC 3339 instant or date; at most 366 days after from

Devolve

200 Balance

Mostrar atributos
dma_idstring · opcional
dma_codestring · opcional
node_idstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
inflow_volume_litersinteger (int64) · opcional
export_volume_litersinteger (int64) · opcional
outflow_volume_litersinteger (int64) · opcional

Authorised consumption plus export

storage_delta_litersinteger (int64) · opcional
authorised_consumption_litersinteger (int64) · opcional
billed_consumption_litersinteger (int64) · opcional
unbilled_metered_consumption_litersinteger (int64) · opcional
estimated_consumption_litersinteger (int64) · opcional
unaccounted_loss_litersinteger (int64) · opcional
non_revenue_water_litersinteger (int64) · opcional
loss_basis_pointsinteger · opcional · anulável
tolerance_basis_pointsinteger (int64) · opcional
physically_validboolean · opcional
mass_conservedboolean · opcional
statusstring · opcional

um de computed, partial_data, insufficient_data

inflowobject · opcional
Mostrar atributos filhos
sourcestring · opcional

um de measurements, meter_consumption, none

device_idstring · opcional
sample_countinteger · opcional
first_observed_atstring (date-time) · opcional
last_observed_atstring (date-time) · opcional
completeboolean · opcional
exportobject · opcional
Mostrar atributos filhos
sourcestring · opcional

um de measurements, meter_consumption, none

device_idstring · opcional
sample_countinteger · opcional
first_observed_atstring (date-time) · opcional
last_observed_atstring (date-time) · opcional
completeboolean · opcional
storageobject · opcional
Mostrar atributos filhos
sourcestring · opcional

um de measurements, meter_consumption, none

device_idstring · opcional
sample_countinteger · opcional
first_observed_atstring (date-time) · opcional
last_observed_atstring (date-time) · opcional
completeboolean · opcional
consumptionobject · opcional
Mostrar atributos filhos
attributionstring · opcional

um de dma_taps, service_area, none

meter_countinteger · opcional
billed_recordsinteger · opcional
unbilled_recordsinteger · opcional
proratedboolean · opcional
skipped_recordsinteger · opcional
warningsarray of string · opcional

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/balance/dma/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "dma_code": "DMA-2026-000142",
  "node_id": "nod_26enLAulDEgfZ0IlNWY59ugfRs0",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "inflow_volume_liters": 1342,
  "export_volume_liters": 1342,
  "outflow_volume_liters": 1342,
  "storage_delta_liters": 1,
  "authorised_consumption_liters": 1342,
  "billed_consumption_liters": 1342,
  "unbilled_metered_consumption_liters": 1342,
  "estimated_consumption_liters": 1342,
  "unaccounted_loss_liters": 1,
  "non_revenue_water_liters": 1,
  "loss_basis_points": 1,
  "tolerance_basis_points": 1,
  "physically_valid": true,
  "mass_conserved": true,
  "status": "computed",
  "inflow": {
    "source": "measurements",
    "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
    "sample_count": 1,
    "first_observed_at": "2026-11-19T09:30:00Z",
    "last_observed_at": "2026-11-19T09:30:00Z",
    "complete": true
  },
  "export": {
    "source": "measurements",
    "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
    "sample_count": 1,
    "first_observed_at": "2026-11-19T09:30:00Z",
    "last_observed_at": "2026-11-19T09:30:00Z",
    "complete": true
  },
  "storage": {
    "source": "measurements",
    "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
    "sample_count": 1,
    "first_observed_at": "2026-11-19T09:30:00Z",
    "last_observed_at": "2026-11-19T09:30:00Z",
    "complete": true
  },
  "consumption": {
    "attribution": "dma_taps",
    "meter_count": 1,
    "billed_records": 1,
    "unbilled_records": 1,
    "prorated": true,
    "skipped_records": 1
  },
  "warnings": [
    "warning"
  ]
}

Registar o balanço de um período

Registos

POST /topology/balance/dma/{id}/ledger

A changed result is appended as a new revision; an unchanged retry returns the existing row.

Parâmetros

idstring · caminho · obrigatório

ID of the district metered area (DMA) whose balance is computed and written to the ledger; the DMA must have a dma_inlet node to book the entry against, otherwise the request fails with 409.

Corpo application/json

fromstring (date-time) · obrigatório
tostring (date-time) · obrigatório

Devolve

201 Ledger row

Mostrar atributos
idstring · opcional
tenant_idstring · opcional
node_idstring · opcional
dma_idstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
revisioninteger · opcional
inflow_volume_litersinteger (int64) · opcional
outflow_volume_litersinteger (int64) · opcional
storage_delta_litersinteger (int64) · opcional
unaccounted_loss_litersinteger (int64) · opcional
mass_conservedboolean · opcional
tolerance_basis_pointsinteger (int64) · opcional
created_bystring · opcional
created_atstring (date-time) · opcional

Erros 409

Permissões network:write · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/topology/balance/dma/{id}/ledger" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-11-19T09:30:00Z",
  "to": "2026-11-19T09:30:00Z"
}'
Resposta 201
{
  "id": "mas_2wu1XsIbbYSzvquXn8uHx44l3Eo",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "node_id": "nod_26enLAulDEgfZ0IlNWY59ugfRs0",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "revision": 1,
  "inflow_volume_liters": 1342,
  "outflow_volume_liters": 1342,
  "storage_delta_liters": 1,
  "unaccounted_loss_liters": 1,
  "mass_conserved": true,
  "tolerance_basis_points": 1,
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z"
}

Listar balanços registados

Registos

GET /topology/balance/ledger

Returns the immutable mass balance ledger entries recorded for the tenant, newest first, with cursor pagination (limit defaults to 20, maximum 100; pass next_cursor as after). A restated period appears as a new entry with a higher revision, because entries are never changed. Requires network read access.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

node_idstring · consulta · opcional

Returns only entries booked against this topology node ID, normally a DMA's dma_inlet node; an exact match, omitted for all nodes.

dma_idstring · consulta · opcional

Returns only entries recorded for this district metered area ID; an exact match, omitted for all DMAs.

Devolve

200 Ledger rows

Mostrar atributos
dataarray of MassBalanceEntry · opcional
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
node_idstring · opcional
dma_idstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
revisioninteger · opcional
inflow_volume_litersinteger (int64) · opcional
outflow_volume_litersinteger (int64) · opcional
storage_delta_litersinteger (int64) · opcional
unaccounted_loss_litersinteger (int64) · opcional
mass_conservedboolean · opcional
tolerance_basis_pointsinteger (int64) · opcional
created_bystring · opcional
created_atstring (date-time) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/balance/ledger" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "mas_2wu1XsIbbYSzvquXn8uHx44l3Eo",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_id": "nod_26enLAulDEgfZ0IlNWY59ugfRs0",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "period_start": "2026-11-19T09:30:00Z",
      "period_end": "2026-11-19T09:30:00Z",
      "revision": 1,
      "inflow_volume_liters": 1342,
      "outflow_volume_liters": 1342,
      "storage_delta_liters": 1,
      "unaccounted_loss_liters": 1,
      "mass_conserved": true,
      "tolerance_basis_points": 1,
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}