PT EN

Zonas de medição

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
service_area_idstring · obrigatório
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar zonas de medição

Registos

GET /dmas

Returns the tenant's district metered areas (DMAs), newest first, with their code, name, service area, inflow and outflow meters and target pressure. Results are cursor-paginated (default 20, maximum 100); the handler also accepts service_area_id and a q search that matches name or code. Requires the network:read permission.

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 DMAs

Mostrar atributos
dataarray of DistrictMeteredArea · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
service_area_idstring · obrigatório
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional
total_countinteger · opcional

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

curl -X GET "$BUSINESS_API/dmas" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
      "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
      "target_pressure_bar": 1,
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Registar uma zona de medição

Registos

POST /dmas

Creates a district metered area in the tenant and returns it with 201. code, name and service_area_id are required (400 when missing); inflow_meter_id, outflow_meter_id and target_pressure_bar are optional, and the inflow meter is what night-flow analysis reads. A duplicate DMA code returns 409. Requires the network:write permission.

Corpo application/json

codestring · obrigatório
namestring · obrigatório
service_area_idstring · obrigatório
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional

Devolve

201 DMA registered

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
service_area_idstring · obrigatório
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

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

curl -X POST "$BUSINESS_API/dmas" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1
}'
Resposta 201
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter uma zona de medição

Registos

GET /dmas/{id}

Returns one district metered area of the tenant, including its code, service area, inflow and outflow meter references and target pressure. Returns 404 when the DMA does not exist in the tenant. Requires the network:read permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the district metered area (a dma_ prefixed ID) within the current tenant.

Devolve

200 District Metered Area details

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
service_area_idstring · obrigatório
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

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

curl -X GET "$BUSINESS_API/dmas/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Actualizar uma zona de medição

Registos

PUT /dmas/{id}

Update a DMA's name, service area, inflow and outflow meters or target pressure

Changes only the fields present in the body (name, service_area_id, inflow_meter_id, outflow_meter_id, target_pressure_bar) and returns the updated DMA; the code cannot be changed. name and service_area_id may not be set to an empty string (400), while the meter references can be cleared with an empty string. Returns 404 for an unknown DMA. Requires the network:write permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the district metered area to update within the current tenant.

Corpo application/json

namestring · opcional
service_area_idstring · opcional
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional

Devolve

200 Updated DMA

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
service_area_idstring · obrigatório
inflow_meter_idstring · opcional
outflow_meter_idstring · opcional
target_pressure_barnumber · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

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

curl -X PUT "$BUSINESS_API/dmas/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1
}'
Resposta 200
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter o balanço hídrico de uma zona

Registos

GET /dmas/{id}/water-balance

Computes an IWA-style water balance for one DMA over the window: system input volume, billed and unbilled authorised consumption, water losses and non-revenue water in litres, with non-revenue water as basis points of system input. Losses are split into apparent and real only when apparent_loss_bp is given, otherwise the split is reported as insufficient data; a status and warnings say when data is partial or missing. The window must be at most 366 days with to after from (400 otherwise); 404 for an unknown DMA. Requires the network:read permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the district metered area to balance.

fromstring · consulta · obrigatório

Required start of the balance period as an RFC 3339 timestamp.

tostring · consulta · obrigatório

Required end of the balance period as an RFC 3339 timestamp; it must be after from and no more than 366 days later.

apparent_loss_bpinteger · consulta · opcional

Optional assumed apparent loss (meter under-registration and unauthorised use) as basis points of authorised consumption, an integer from 0 to 10000; when it exceeds total losses it is capped with a warning.

Devolve

200 OK

Mostrar atributos
scopestring · opcional

um de system, dma

dma_idstring · opcional
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
statusstring · opcional

um de computed, partial_data, insufficient_data

system_input_litersinteger · opcional
billed_authorized_litersinteger · opcional
unbilled_authorized_litersinteger · opcional
authorized_consumption_litersinteger · opcional
water_losses_litersinteger · opcional
apparent_losses_litersinteger · opcional · anulável
real_losses_litersinteger · opcional · anulável
loss_splitstring · opcional

um de computed_from_assumption, insufficient_data

apparent_loss_assumption_bpinteger · opcional
non_revenue_water_litersinteger · opcional
non_revenue_water_bpinteger · opcional
dmas_totalinteger · opcional
dmas_computedinteger · opcional
dmasarray of IWAWaterBalance · opcional
warningsarray of string · opcional

Erros 400 · 403 · 404

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

curl -X GET "$BUSINESS_API/dmas/{id}/water-balance" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "scope": "system",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "status": "computed",
  "system_input_liters": 1,
  "billed_authorized_liters": 1,
  "unbilled_authorized_liters": 1,
  "authorized_consumption_liters": 1342,
  "water_losses_liters": 1,
  "apparent_losses_liters": 1,
  "real_losses_liters": 1,
  "loss_split": "computed_from_assumption",
  "apparent_loss_assumption_bp": 1,
  "non_revenue_water_liters": 1,
  "non_revenue_water_bp": 1,
  "dmas_total": 125000,
  "dmas_computed": 1,
  "dmas": [],
  "warnings": [
    "warning"
  ]
}

Obter o caudal mínimo nocturno de uma zona

Registos

GET /dmas/{id}/night-flow

Minimum night flow 02:00-04:00 per local night with burst suspicion

Reads the DMA's inflow device measurements and reports, for each local night in the window, the mean flow in litres per second between 02:00 and 04:00, compared with the median of up to seven preceding nights (at least three are needed for a baseline). A night whose excess over the baseline is above threshold_percent is flagged burst_suspected; nights with fewer than two samples are insufficient_data. When the DMA has no inflow meter the report is returned with a warning and no values. The window must be at most 366 days with to after from (400 otherwise); 404 for an unknown DMA.

Parâmetros

idstring · caminho · obrigatório

Identifier of the district metered area whose inflow device is analysed.

fromstring · consulta · obrigatório

Required start of the window as an RFC 3339 timestamp; the first reported night is the local calendar day containing it.

tostring · consulta · obrigatório

Required end of the window as an RFC 3339 timestamp; it must be after from and no more than 366 days later.

timezonestring · consulta · opcional

IANA time zone name (for example Africa/Maputo) used to place the 02:00-04:00 window and night dates; defaults to UTC, and an unknown zone returns 400.

threshold_percentnumber · consulta · opcional

Positive percentage above the baseline at which a night is flagged as burst suspected; defaults to 30, and zero, negative or non-numeric values return 400.

Devolve

200 OK

Mostrar atributos
dma_idstring · opcional
device_idstring · opcional
timezonestring · opcional
threshold_percentnumber · opcional
nightsarray of object · opcional
Mostrar atributos filhos
datestring (date) · opcional
mean_flow_lpsnumber · opcional · anulável
sample_countinteger · opcional
baseline_lpsnumber · opcional
excess_percentnumber · opcional
burst_suspectedboolean · opcional
statusstring · opcional

um de ok, burst_suspected, insufficient_data

warningsarray of string · opcional

Erros 400 · 403 · 404

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

curl -X GET "$BUSINESS_API/dmas/{id}/night-flow" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "timezone": "Africa/Maputo",
  "threshold_percent": 1,
  "nights": [
    {
      "date": "2026-11-19",
      "mean_flow_lps": 1,
      "sample_count": 1,
      "baseline_lps": 1,
      "excess_percent": 1,
      "burst_suspected": true,
      "status": "ok"
    }
  ],
  "warnings": [
    "warning"
  ]
}