PT EN

Roteiros de leitura

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · obrigatório
namestring · obrigatório
statusstring · obrigatório

um de active, disabled

meter_idsarray of string · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "id": "rea_2GM1rUURLIKrxQSpxeaTlkgrngO",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "name": "Ana Matsinhe",
  "status": "active",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Planear um roteiro de leitura

Registos

PATCH /reading-routes/{id}/plan

Changes a route's plan and returns the updated route: the assigned reader, the cycle and the walk order. Only the fields present are changed; an empty string clears the reader or the cycle, and a cycle that does not exist returns 404. points resequences the route and must list exactly the route's current meters with unique sequence_order values of 1 or more, so the meter set itself cannot change here (400 otherwise). Requires business:reading-routes:manage.

Parâmetros

idstring · caminho · obrigatório

ID of the reading route whose plan to change.

Corpo application/json

assigned_reader_idstring · opcional
cycle_idstring · opcional
pointsarray of object · opcional
Mostrar atributos filhos
meter_idstring · obrigatório
sequence_orderinteger · obrigatório
walking_notesstring · opcional

Devolve

200 Route with its plan

Permissões business:reading-routes:manage · Funções: admin, operations, owner

curl -X PATCH "$BUSINESS_API/reading-routes/{id}/plan" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "assigned_reader_id": "ass_2EG5HuITXuIxvU6Z3AELH6ihZOG",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "points": [
    {
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "sequence_order": 1,
      "walking_notes": "walking notes"
    }
  ]
}'
Resposta 200

Route with its plan

Listar roteiros de leitura

Registos

GET /reading-routes

Returns a cursor-paginated page of the tenant's reading routes, each with its ordered meter stops, assigned reader and cycle. You can also filter by assigned_reader_id and cycle_id, search with q, and page with limit (default 20, maximum 100) and after. Requires business:reading-routes:read.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

service_area_idstring · consulta · opcional

Returns only routes in this service area ID.

statusstring · consulta · opcional

Returns only routes in this status, active or disabled; any other value returns 400.

um de active, disabled

qstring · consulta · opcional

Resource-specific text search.

Devolve

200 Service-area routes and ordered meter stops

Permissões business:reading-routes:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner

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

Service-area routes and ordered meter stops

Criar um roteiro de leitura

Registos

POST /reading-routes

Creates an active reading route in an active service area, listing the meters a reader visits in walk order. Send either meter_ids (sequenced in the order given) or points with explicit sequence_order and optional walking_notes (at most 500 characters); up to 500 distinct meters, all of which must be active. name (at most 255 characters) and service_area_id are required; assigned_reader_id and cycle_id are optional, and an unknown cycle or service area returns 404.

Corpo application/json

service_area_idstring · obrigatório
namestring · obrigatório
meter_idsarray of string · obrigatório

Devolve

201 Reading route created

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · obrigatório
namestring · obrigatório
statusstring · obrigatório

um de active, disabled

meter_idsarray of string · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões business:reading-routes:create, business:service-areas:read · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/reading-routes" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "name": "Ana Matsinhe",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ]
}'
Resposta 201
{
  "id": "rea_2GM1rUURLIKrxQSpxeaTlkgrngO",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "name": "Ana Matsinhe",
  "status": "active",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter um roteiro de leitura

Registos

GET /reading-routes/{id}

Returns one reading route with its service area, status, meter IDs, ordered points with walking notes, assigned reader and cycle. A route that does not exist in the tenant returns 404. Requires business:reading-routes:read.

Parâmetros

idstring · caminho · obrigatório

ID of the reading route to return.

Devolve

200 Reading route details

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · obrigatório
namestring · obrigatório
statusstring · obrigatório

um de active, disabled

meter_idsarray of string · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões business:reading-routes:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-routes/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "rea_2GM1rUURLIKrxQSpxeaTlkgrngO",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "name": "Ana Matsinhe",
  "status": "active",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Activar ou desactivar um roteiro

Registos

PATCH /reading-routes/{id}/status

Enables or disables a reading route and returns 204 with no body. The status must be active or disabled (400 otherwise), and an unknown route returns 404. A disabled route cannot get new reading rounds until it is made active again. Requires business:reading-routes:manage.

Parâmetros

idstring · caminho · obrigatório

ID of the reading route whose status to change.

Corpo application/json

statusstring · obrigatório

um de active, disabled

Devolve

204 Reading route status changed

Permissões business:reading-routes:manage · Funções: admin, operations, owner

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

Reading route status changed

Obter os metadados de um roteiro

Registos

GET /reading-routes/{id}/metadata

Returns the free-form key-value metadata attached to a reading route, as a map of string keys to string values together with the resource type and ID. The route must exist in the caller's tenant, otherwise the call returns 404. Requires the business:metadata:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the reading route whose metadata to read; 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/reading-routes/{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 roteiro

Registos

PUT /reading-routes/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the metadata object in the body into the route's existing metadata and returns the full resulting map. A key with a non-empty value is created or overwritten, a key sent with an empty string is deleted, and keys you do not send are kept. Keys must be non-blank, at most 40 characters and free of square brackets and control characters, values at most 500 characters, and a resource may hold at most 50 keys after the merge; violations return 400. The route must exist in the caller's tenant (404 otherwise) and the caller needs business:metadata:write.

Parâmetros

idstring · caminho · obrigatório

ID of the reading route whose metadata to change; 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/reading-routes/{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"
  }
}