PT EN

Pedidos de vistoria

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

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.

identity_idstring · obrigatório
requester_namestring · opcional

Who filed it, which can differ from the account holder.

reasonstring · obrigatório
idempotency_keystring · opcional
kindstring · opcional

um de consumer, field_reread

reading_idstring · opcional
statusstring · obrigatório

um de open, scheduled, completed, cancelled

scheduled_atstring · opcional · anulável
resolutionstring · opcional
resolved_bystring · opcional
resolved_atstring · opcional · anulável
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "id": "met_22OXlyuNjQGrXkQbdCkn18WvtcE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "requester_name": "Ana Matsinhe",
  "reason": "Leitura confirmada no local.",
  "idempotency_key": "idempotency key",
  "kind": "consumer",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "status": "open",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "resolution": "resolution",
  "resolved_by": "resolved by",
  "resolved_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar pedidos de vistoria

Registos

GET /meter-inspection-requests

Returns inspection requests for the tenant's meters, both those raised by consumers and the field re-reads raised by staff, with cursor pagination. Filters combine with AND; an unknown status returns 400. Requires the business:inspection-requests: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.

account_idstring · consulta · opcional

Returns only requests raised for this customer account.

meter_idstring · consulta · opcional

Returns only requests for this meter.

statusstring · consulta · opcional

Request state: open, scheduled, completed or cancelled; any other value returns 400.

um de open, scheduled, completed, cancelled

kindstring · consulta · opcional

Who raised the request: consumer for a request from the account holder, or field_reread for a re-read raised by staff.

um de consumer, field_reread

Devolve

200 Tenant-scoped inspection requests

Mostrar atributos
dataarray of MeterInspectionRequest · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
account_idstring · obrigatório
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

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.

identity_idstring · obrigatório
requester_namestring · opcional

Who filed it, which can differ from the account holder.

reasonstring · obrigatório
idempotency_keystring · opcional
kindstring · opcional

um de consumer, field_reread

reading_idstring · opcional
statusstring · obrigatório

um de open, scheduled, completed, cancelled

scheduled_atstring · opcional · anulável
resolutionstring · opcional
resolved_bystring · opcional
resolved_atstring · opcional · anulável
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 403

Permissões business:inspection-requests:read · Funções: admin, analyst, customer_service, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/meter-inspection-requests" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "met_22OXlyuNjQGrXkQbdCkn18WvtcE",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
      "requester_name": "Ana Matsinhe",
      "reason": "Leitura confirmada no local.",
      "idempotency_key": "idempotency key",
      "kind": "consumer",
      "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
      "status": "open",
      "scheduled_at": "2026-11-19T09:30:00Z",
      "resolution": "resolution",
      "resolved_by": "resolved by",
      "resolved_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Actualizar um pedido de vistoria

Registos

PATCH /meter-inspection-requests/{id}/status

Moves an inspection request to a new status and returns 204 with no body. An open request can be scheduled (scheduled_at is required and must be in the future) or cancelled; only a scheduled request can be completed; completing or cancelling requires a non-empty resolution text. Returns 409 when the request's current status does not allow the change and 400 for a missing or invalid field. Requires the business:inspection-requests:manage permission.

Parâmetros

idstring · caminho · obrigatório

ID of the inspection request in the caller's tenant.

Corpo application/json

statusstring · obrigatório

um de scheduled, completed, cancelled

scheduled_atstring (date-time) · opcional
resolutionstring · opcional

Devolve

204 Inspection request state updated

Erros 400 · 403 · 404 · 409

Permissões business:inspection-requests:manage · Funções: admin, field_supervisor, operations, owner

curl -X PATCH "$BUSINESS_API/meter-inspection-requests/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "scheduled",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "resolution": "resolution"
}'
Resposta 204

Inspection request state updated