PT EN

Visitas de campo

URL base: $BUSINESS_API

O objecto

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.

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.

assignment_idstring · opcional
route_idstring · opcional
cycle_idstring · opcional
reader_idstring · obrigatório
visited_atstring (date-time) · obrigatório
outcomestring · obrigatório

um de read, inaccessible, damaged, not_found

reading_idstring · opcional
latitudenumber · opcional
longitudenumber · opcional
evidence_idsarray of string · opcional
notesstring · opcional
revisit_requiredboolean · obrigatório
revisit_reasonstring · opcional
revisit_scheduled_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório
O objecto
{
  "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Listar visitas de campo

Registos

GET /field-visits

Returns field visit records of the tenant with outcome, reader, location, evidence and revisit details. Filters combine, the handler also accepts route_id and cycle_id, and results are cursor-paginated (default 20, maximum 100). An unknown outcome value returns 400. Requires the business:field-visits: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.

meter_idstring · consulta · opcional

Return only visits to this meter.

account_idstring · consulta · opcional

Return only visits to meters of this service account.

reader_idstring · consulta · opcional

Return only visits recorded by this staff member (the identity that submitted the visit).

outcomestring · consulta · opcional

Return only visits with this outcome: read, inaccessible, damaged or not_found; any other value returns 400.

um de read, inaccessible, damaged, not_found

revisit_requiredboolean · consulta · opcional

When true or 1, return only visits that need a revisit; any other value returns only visits that do not; omit to include both.

Devolve

200 Field visits list

Mostrar atributos
dataarray of FieldVisit · obrigatório
Mostrar atributos filhos
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.

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.

assignment_idstring · opcional
route_idstring · opcional
cycle_idstring · opcional
reader_idstring · obrigatório
visited_atstring (date-time) · obrigatório
outcomestring · obrigatório

um de read, inaccessible, damaged, not_found

reading_idstring · opcional
latitudenumber · opcional
longitudenumber · opcional
evidence_idsarray of string · opcional
notesstring · opcional
revisit_requiredboolean · obrigatório
revisit_reasonstring · opcional
revisit_scheduled_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório
has_moreboolean · opcional
next_cursorstring · opcional

Erros 403

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

curl -X GET "$BUSINESS_API/field-visits" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
      "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
      "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
      "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
      "visited_at": "2026-11-19T09:30:00Z",
      "outcome": "read",
      "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
      "latitude": -25.9653,
      "longitude": 32.5892,
      "evidence_ids": [
        "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
      ],
      "notes": "Leitura confirmada no local.",
      "revisit_required": true,
      "revisit_reason": "revisit reason",
      "revisit_scheduled_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Registar uma visita de campo

Registos

POST /field-visits

Records a visit by the calling staff member to an active meter and returns it with 201; the account is taken from the meter. With assignment_id, the assignment must belong to the caller, be in progress, include the meter and sit in an in-progress reading round, and the visit then carries its route and cycle. visited_at defaults to now and must lie between the meter's installation and five minutes in the future, and revisit_scheduled_at may not be in the past (400). An inactive meter or a round that is not in progress returns 409; an unknown meter or assignment returns 404.

Corpo application/json

meter_idstring · obrigatório
assignment_idstring · opcional
visited_atstring (date-time) · opcional
outcomestring · obrigatório

um de read, inaccessible, damaged, not_found

reading_idstring · opcional
latitudenumber · opcional
longitudenumber · opcional
evidence_idsarray of string · opcional
notesstring · opcional
revisit_requiredboolean · opcional
revisit_reasonstring · opcional
revisit_scheduled_atstring (date-time) · opcional

Devolve

201 Field visit recorded

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.

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.

assignment_idstring · opcional
route_idstring · opcional
cycle_idstring · opcional
reader_idstring · obrigatório
visited_atstring (date-time) · obrigatório
outcomestring · obrigatório

um de read, inaccessible, damaged, not_found

reading_idstring · opcional
latitudenumber · opcional
longitudenumber · opcional
evidence_idsarray of string · opcional
notesstring · opcional
revisit_requiredboolean · obrigatório
revisit_reasonstring · opcional
revisit_scheduled_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório

Erros 400 · 403 · 404

Permissões business:field-visits:create · Funções: admin, field_reader, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/field-visits" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z"
}'
Resposta 201
{
  "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Obter uma visita de campo

Registos

GET /field-visits/{id}

Returns one field visit with its outcome, reader, linked reading, coordinates, evidence IDs, notes and revisit details. Returns 404 when the visit is not in the tenant. Requires the business:field-visits:read permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the field visit (an fvs_ prefixed ID) within the current tenant.

Devolve

200 Field visit details

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.

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.

assignment_idstring · opcional
route_idstring · opcional
cycle_idstring · opcional
reader_idstring · obrigatório
visited_atstring (date-time) · obrigatório
outcomestring · obrigatório

um de read, inaccessible, damaged, not_found

reading_idstring · opcional
latitudenumber · opcional
longitudenumber · opcional
evidence_idsarray of string · opcional
notesstring · opcional
revisit_requiredboolean · obrigatório
revisit_reasonstring · opcional
revisit_scheduled_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório

Erros 403 · 404

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

curl -X GET "$BUSINESS_API/field-visits/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}