PT EN

Rondas de leitura

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
route_idstring · obrigatório
cycle_idstring · obrigatório
scheduled_atstring (date-time) · obrigatório
statusstring · obrigatório

um de planned, open, in_progress, completed, cancelled

opened_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_2PpyaTHmkbFAofB8UXpw8xhESFx",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "status": "planned",
  "opened_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 rondas de leitura

Registos

GET /reading-rounds

Returns a cursor-paginated page of reading rounds, each being one scheduled pass over a route for a cycle, with its status and the times it was opened, completed or cancelled. Use limit (default 20, maximum 100) and after to page. Requires business:reading-rounds:read.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

route_idstring · consulta · opcional

Returns only rounds that walk this reading route ID.

cycle_idstring · consulta · opcional

Returns only rounds that belong to this reading cycle ID.

statusstring · consulta · opcional

Returns only rounds in this status: planned, open, in_progress, completed or cancelled; any other value returns 400.

um de planned, open, in_progress, completed, cancelled

Devolve

200 Filtered reading rounds

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

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

Filtered reading rounds

Agendar uma ronda de leitura

Registos

POST /reading-rounds

Plans a round of readings over a route for a cycle and returns it with status planned. route_id, cycle_id and scheduled_at are required (400 otherwise); the route must exist (404) and be active, or the call returns 409. Readers are then given meters through reading assignments while the round is planned or open.

Corpo application/json

route_idstring · obrigatório
cycle_idstring · obrigatório
scheduled_atstring (date-time) · obrigatório

Devolve

201 Reading round created

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
route_idstring · obrigatório
cycle_idstring · obrigatório
scheduled_atstring (date-time) · obrigatório
statusstring · obrigatório

um de planned, open, in_progress, completed, cancelled

opened_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-rounds:create · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/reading-rounds" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z"
}'
Resposta 201
{
  "id": "rea_2PpyaTHmkbFAofB8UXpw8xhESFx",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "status": "planned",
  "opened_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 ronda de leitura

Registos

GET /reading-rounds/{id}

Returns one reading round with its route, cycle, scheduled time, status and the opened, completed and cancelled timestamps. A round that does not exist in the tenant returns 404. Requires business:reading-rounds:read.

Parâmetros

idstring · caminho · obrigatório

ID of the reading round to return.

Devolve

200 Reading round details

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
route_idstring · obrigatório
cycle_idstring · obrigatório
scheduled_atstring (date-time) · obrigatório
statusstring · obrigatório

um de planned, open, in_progress, completed, cancelled

opened_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-rounds:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-rounds/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "rea_2PpyaTHmkbFAofB8UXpw8xhESFx",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "status": "planned",
  "opened_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 ronda

Registos

PATCH /reading-rounds/{id}/status

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

Parâmetros

idstring · caminho · obrigatório

ID of the reading round whose status to change.

Corpo application/json

statusstring · obrigatório

um de planned, open, in_progress, completed, cancelled

Devolve

204 Reading round status changed

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

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

Reading round status changed