PT EN

Agendamentos de leitura

URL base: $BUSINESS_API

Listar agendamentos de leitura

Registos

GET /reading-schedules

Returns a cursor-paginated page of recurring remote reading schedules, each with its meter, integration, interval, next run time and last request time. Use limit (default 20, maximum 100) and after to page. Requires business:reading-schedules:read.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

meter_idstring · consulta · opcional

Returns only schedules for this meter ID.

source_idstring · consulta · opcional

Returns only schedules that use this integration ID as the remote reading source.

statusstring · consulta · opcional

Returns only schedules in this status, active or paused; any other value returns 400.

um de active, paused

Devolve

200 Utility reading schedules

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

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

Utility reading schedules

Agendar leituras remotas

Registos

POST /reading-schedules

Creates an active schedule that turns into a remote reading request for the meter every interval_seconds (between 60 and 31,536,000). meter_id and source_id are required; next_run_at defaults to now plus one interval and must fall within the next 365 days. The meter must be active (409 otherwise) and the integration must exist and be active (404 or 403). Schedules only produce requests when they are materialized.

Corpo application/json

meter_idstring · obrigatório
source_idstring · obrigatório
interval_secondsinteger · obrigatório
next_run_atstring (date-time) · opcional

Devolve

201 Reading schedule created

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

source_idstring · obrigatório
interval_secondsinteger · obrigatório
next_run_atstring (date-time) · obrigatório
statusstring · obrigatório

um de active, paused

last_requested_atstring · opcional · anulável
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

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

curl -X POST "$BUSINESS_API/reading-schedules" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "interval_seconds": 60,
  "next_run_at": "2026-11-19T09:30:00Z"
}'
Resposta 201
{
  "id": "rea_2WybNoeX7iixvo8x1GYvNoKH54S",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "interval_seconds": 60,
  "next_run_at": "2026-11-19T09:30:00Z",
  "status": "active",
  "last_requested_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Pausar ou retomar um agendamento

Registos

PATCH /reading-schedules/{id}/status

Pauses or resumes a reading schedule and returns 204 with no body. The status must be active or paused (400 otherwise), and an unknown schedule returns 404. A paused schedule is ignored when due schedules are materialized. Requires business:reading-schedules:manage.

Parâmetros

idstring · caminho · obrigatório

ID of the reading schedule to pause or resume.

Corpo application/json

statusstring · obrigatório

um de active, paused

Devolve

204 Schedule status changed

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

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

Schedule status changed

Gerar os pedidos de leitura devidos

Registos

POST /reading-schedules/materialize

Turns every active schedule whose next run time has passed into a reading request due in 10 minutes, advances each schedule by one interval, and returns 201 with the requests in data. The body's limit (1 to 100, required) caps how many due schedules are processed, oldest first. Schedules whose integration is no longer active are skipped, and each schedule run has a fixed idempotency key, so calling again does not duplicate a request already created. Requires business:reading-schedules:run.

Corpo application/json

limitinteger · obrigatório

Devolve

201 Due scheduled requests created

Permissões business:reading-schedules:run · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/reading-schedules/materialize" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 25
}'
Resposta 201

Due scheduled requests created