PT EN

Atribuições de leitura

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
round_idstring · obrigatório
reader_idstring · obrigatório
meter_idsarray of string · obrigatório
statusstring · obrigatório

um de assigned, in_progress, completed, cancelled

assigned_bystring · obrigatório
assigned_atstring (date-time) · obrigatório
due_atstring · opcional · anulável
started_atstring · opcional · anulável
completed_atstring · opcional · anulável
cancelled_atstring · opcional · anulável
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "id": "rea_2EipDoOH7eqBZSWv5EopbOSVrAi",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "status": "assigned",
  "assigned_by": "assigned by",
  "assigned_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar atribuições de leitura

Registos

GET /reading-assignments

Returns a cursor-paginated page of reading assignments, each giving the reader, the round and the meters that reader must read. Use limit (default 20, maximum 100) and after to page. Requires the business:reading-assignments: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.

round_idstring · consulta · opcional

Returns only assignments that belong to this reading round ID.

reader_idstring · consulta · opcional

Returns only assignments given to this reader (the user ID of the meter reader).

statusstring · consulta · opcional

Returns only assignments in this status: assigned, in_progress, completed or cancelled; any other value returns 400.

um de assigned, in_progress, completed, cancelled

Devolve

200 Filtered reader assignments with meter stops

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

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

Filtered reader assignments with meter stops

Atribuir leituras a um leitor

Registos

POST /reading-assignments

If meter_ids is omitted, all route meters not already assigned in this round are assigned.

Corpo application/json

round_idstring · obrigatório
reader_idstring · obrigatório
meter_idsarray of string · opcional
due_atstring (date-time) · opcional

Devolve

201 Reading assignment created

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
round_idstring · obrigatório
reader_idstring · obrigatório
meter_idsarray of string · obrigatório
statusstring · obrigatório

um de assigned, in_progress, completed, cancelled

assigned_bystring · obrigatório
assigned_atstring (date-time) · obrigatório
due_atstring · opcional · anulável
started_atstring · opcional · anulável
completed_atstring · opcional · anulável
cancelled_atstring · opcional · anulável
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões business:reading-assignments:create · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/reading-assignments" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "due_at": "2026-11-19T09:30:00Z"
}'
Resposta 201
{
  "id": "rea_2EipDoOH7eqBZSWv5EopbOSVrAi",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "status": "assigned",
  "assigned_by": "assigned by",
  "assigned_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter uma atribuição de leitura

Registos

GET /reading-assignments/{id}

Returns one reading assignment with its reader, round, meter IDs, due date and the timestamps of each status change. An assignment that does not exist in the tenant returns 404. Requires the business:reading-assignments:read permission.

Parâmetros

idstring · caminho · obrigatório

ID of the reading assignment to return.

Devolve

200 Assignment with its assigned meter stops

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
round_idstring · obrigatório
reader_idstring · obrigatório
meter_idsarray of string · obrigatório
statusstring · obrigatório

um de assigned, in_progress, completed, cancelled

assigned_bystring · obrigatório
assigned_atstring (date-time) · obrigatório
due_atstring · opcional · anulável
started_atstring · opcional · anulável
completed_atstring · opcional · anulável
cancelled_atstring · opcional · anulável
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

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

curl -X GET "$BUSINESS_API/reading-assignments/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "rea_2EipDoOH7eqBZSWv5EopbOSVrAi",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "status": "assigned",
  "assigned_by": "assigned by",
  "assigned_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Alterar o estado de uma atribuição

Registos

PATCH /reading-assignments/{id}/status

Moves a reading assignment to a new status and returns 204 with no body. Allowed moves are assigned to in_progress or cancelled, and in_progress to completed or cancelled; starting work requires the round to be open or in_progress, and completing requires the round to be in_progress. Any other move returns 409, an unknown status value returns 400, and sending the current status again is a no-op. Requires business:reading-assignments:manage.

Parâmetros

idstring · caminho · obrigatório

ID of the reading assignment whose status to change.

Corpo application/json

statusstring · obrigatório

um de assigned, in_progress, completed, cancelled

Devolve

204 Assignment status changed

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

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

Assignment status changed