PT EN

Ocorrências

URL base: $BUSINESS_API

O objecto

resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional
O objecto
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Listar ocorrências

Registos

GET /incidents

Returns the tenant's network incidents (leaks, bursts, pressure drops, contamination, illegal connections) with severity, status, location and timestamps. Results are cursor-paginated (default 20, maximum 100); the handler also accepts incident_type, severity, status and service_area_id filters. Requires the operations: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.

Devolve

200 Incidents

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

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

Incidents

Comunicar uma ocorrência

Registos

POST /incidents

Records a new incident with status reported and a generated INC-<year>-<suffix> number, and returns it with 201. incident_type and description are required (400 otherwise); severity defaults to medium, and asset, service area and coordinates are optional. Requires the operations:write permission.

Devolve

201 Incident reported

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/incidents" \
  -H "Authorization: Bearer sk_test_..."
Resposta 201

Incident reported

Obter uma ocorrência

Registos

GET /incidents/{id}

Returns one incident with its number, type, severity, status, linked asset and service area, coordinates and reported and resolved times. Returns 404 when it is not in the tenant. Requires the operations:read permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the incident (an inc_ prefixed ID) within the current tenant.

Devolve

200 Incident details

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/incidents/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Incident details

Resolver uma ocorrência

Registos

POST /incidents/{id}/resolve

Sets the incident's status to resolved, stamps resolved_at with the current time and returns the updated incident. The status is not checked first, so resolving an already resolved incident moves resolved_at forward. Returns 404 for an unknown incident. Requires the operations:write permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the incident to resolve within the current tenant.

Devolve

200 Incident resolved

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/incidents/{id}/resolve" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Incident resolved

Obter os metadados de uma ocorrência

Registos

GET /incidents/{id}/metadata

Returns the custom key-value metadata attached to the incident, as an object of string values. The incident must exist in the tenant, otherwise 404. Requires the business:metadata:read permission.

Parâmetros

idstring · caminho · obrigatório

Identifier of the incident whose metadata is read, at most 120 characters.

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/incidents/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Actualizar os metadados de uma ocorrência

Registos

PUT /incidents/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the incident's metadata and returns the full resulting set: keys in the body are added or overwritten, an empty string value deletes that key, and keys not in the body are kept. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and the incident may carry at most 50 keys (400 otherwise). Requires the business:metadata:write permission; 404 when the incident does not exist.

Parâmetros

idstring · caminho · obrigatório

Identifier of the incident whose metadata is merged, at most 120 characters.

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

curl -X PUT "$BUSINESS_API/incidents/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}