PT EN

Abatimentos por fuga

URL base: $BUSINESS_API

O objecto

idstring · opcional
tenant_idstring · opcional
account_idstring · opcional
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.

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

invoice_idstring · opcional
invoice_numberstring · opcional
statusstring · opcional
O objecto
{
  "id": "lea_2VFECVjsORr40pfwS7Vg6Tp6Ezn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "invoice_number": "INV-2026-000142",
  "status": "active"
}

Avaliar um abatimento por fuga

Registos

POST /leak-allowances/assess

Runs the policy against the invoice named by invoice_id and returns the outcome without saving anything. When the invoice is eligible, the result holds the consumption, historic average, excess volume and value, and the proposed credit. Otherwise it gives a reason_code: policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold or no_credit_value. It also says whether proof of repair will be required. Needs the business:leak-allowances:read scope.

Devolve

200 OK

Mostrar atributos
invoice_idstring · obrigatório
eligibleboolean · obrigatório
reason_codestring · opcional

Stable refusal code for an ineligible invoice; clients translate the value.

um de policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold, no_credit_value

consumption_m3number · obrigatório
historic_avg_m3number · opcional
excess_m3number · opcional
excess_value_centsinteger (int64) · opcional
proposed_credit_centsinteger (int64) · opcional
currencystring · opcional
require_proofboolean · obrigatório

Erros 400

Permissões business:leak-allowances:read · Funções: admin, analyst, customer_service, finance, operations, owner, viewer

curl -X POST "$BUSINESS_API/leak-allowances/assess" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Resposta 200
{
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "eligible": true,
  "reason_code": "policy_disabled",
  "consumption_m3": 13.42,
  "historic_avg_m3": 1,
  "excess_m3": 1,
  "excess_value_cents": 1342,
  "proposed_credit_cents": 1,
  "currency": "MZN",
  "require_proof": true
}

Listar abatimentos por fuga

Registos

GET /leak-allowances

Pages the tenant's leak allowance applications with limit (default 20, max 100) and the after cursor. Filter by status (submitted, inspection_scheduled, inspected, credited or rejected) and account_id. Needs the business:leak-allowances:read scope.

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 OK

Mostrar atributos
dataarray of LeakAllowanceApplication · obrigatório
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
account_idstring · opcional
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.

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

invoice_idstring · opcional
invoice_numberstring · opcional
statusstring · opcional
has_moreboolean · obrigatório
next_cursorstring · opcional

Permissões business:leak-allowances:read · Funções: admin, analyst, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/leak-allowances" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "lea_2VFECVjsORr40pfwS7Vg6Tp6Ezn",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
      "invoice_number": "INV-2026-000142",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Pedir um abatimento por fuga

Registos

POST /leak-allowances

Apply on behalf of a customer (multipart: invoice_id, description, proof)

Checks the invoice against the policy and, when it is eligible, creates an application in status submitted with the proposed credit, returned with status 201. Send a multipart form of up to 6 MB with invoice_id, an optional description and a proof file: a PDF, JPEG or PNG of at most 5 MB, required when the policy demands proof. An invoice that already has an open application returns 409, and an ineligible one returns 400 LEAK_ALLOWANCE_INELIGIBLE. Needs the business:leak-allowances:write scope, and the application is recorded in the audit trail.

Devolve

200 OK

Permissões business:leak-allowances:read, invoices:read · Funções: admin, analyst, customer_service, finance, owner, viewer

curl -X POST "$BUSINESS_API/leak-allowances" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

OK

Obter um abatimento por fuga

Registos

GET /leak-allowances/{id}

Returns one application of the caller's tenant with its account and invoice, its status, the consumption figures and proposed credit, the inspection work order and findings, and the decision with any credit note issued. Returns 404 when the application does not exist in this tenant. Needs the business:leak-allowances:read scope.

Devolve

200 OK

Permissões business:leak-allowances:read · Funções: admin, analyst, customer_service, finance, operations, owner, viewer

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

OK

Descarregar o comprovativo de reparação

Registos

GET /leak-allowances/{id}/proof

Streams the proof of repair uploaded with the application as an attachment, using the original file name and a content type taken from its extension (PDF, JPEG or PNG). Returns 404 when the application is not in the caller's tenant, has no proof, or the file cannot be opened. Needs the business:leak-allowances:read scope.

Devolve

200 OK

Permissões business:leak-allowances:read · Funções: admin, analyst, customer_service, finance, operations, owner, viewer

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

OK

Agendar a vistoria de uma fuga

Registos

POST /leak-allowances/{id}/inspection

Creates an inspection work order on the application's account and moves the application from submitted to inspection_scheduled, storing the work order ID. Optional notes are appended to the work order's description. Any status other than submitted returns 409. Needs the business:leak-allowances:write scope, and the action is recorded in the audit trail.

Devolve

200 OK

Permissões business:leak-allowances:write · Funções: admin, customer_service, operations, owner

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

OK

Registar o resultado da vistoria

Registos

POST /leak-allowances/{id}/inspection-result

Stores what the field visit found (leak_confirmed and the required notes), along with the inspector and time, and moves the application to inspected. The application must be in inspection_scheduled (409 otherwise), and empty notes return 400. Only an inspection that confirms a leak can lead to approval. Needs the business:leak-allowances:write scope, and the result is recorded in the audit trail.

Devolve

200 OK

Permissões business:leak-allowances:write · Funções: admin, customer_service, operations, owner

curl -X POST "$BUSINESS_API/leak-allowances/{id}/inspection-result" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Resposta 200

OK

Aprovar um abatimento por fuga

Registos

POST /leak-allowances/{id}/approve

Approve and issue the credit note; the requester cannot approve

Issues a credit note for the proposed credit on the application's invoice, records the optional reason and the adjustment ID, and moves the application to credited. Only an inspected application can be approved (409 otherwise). The inspection must have confirmed a leak, and the policy cooldown is checked again at decision time; either failure returns 400 LEAK_ALLOWANCE_INELIGIBLE. The person who requested the application cannot approve it (403). Needs the business:leak-allowances:approve scope, and the decision is recorded in the audit trail.

Devolve

200 OK

Permissões business:leak-allowances:approve · Funções: admin, finance, owner

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

OK

Rejeitar um abatimento por fuga

Registos

POST /leak-allowances/{id}/reject

Closes an application that is not yet decided, storing the required reason, the decider and the time, and moving it to rejected. It can be called at any stage before a decision. An application that is already credited or rejected returns 409, and an empty reason returns 400. Needs the business:leak-allowances:approve scope, and the rejection is recorded in the audit trail.

Devolve

200 OK

Permissões business:leak-allowances:approve · Funções: admin, finance, owner

curl -X POST "$BUSINESS_API/leak-allowances/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Resposta 200

OK