PT EN

Facturas

URL base: $CONSUMER_API

Listar facturas

Registos

GET /invoices

Pages the invoices of accounts linked to the caller, across tenants unless X-Tenant-ID selects one. Filter with account_id (which must be one of the caller's accounts) and status; pagination uses limit and after.

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

Restrict results to one linked consumer account.

Devolve

200 Invoices authorized for this consumer identity

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

Invoices authorized for this consumer identity

Obter uma factura

Registos

GET /invoices/{id}

Returns one invoice, including its lines and balance, when it belongs to an account linked to the caller. Invoices outside the caller's account scope return 404.

Parâmetros

idstring · caminho · obrigatório

Identifier of the invoice to return.

Devolve

200 Invoice in an account linked to the authenticated consumer

Erros 404

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

Invoice in an account linked to the authenticated consumer

Listar notas de uma factura

Registos

GET /invoices/{id}/notes

List the debit and credit notes of an invoice authorized for the authenticated consumer

Notes the server wrote carry reason_code and reason_params so clients word them in the reader's language; reason is the stored fallback.

Parâmetros

idstring · caminho · obrigatório

Identifier of the invoice whose debit and credit notes are listed; it must belong to an account linked to the caller.

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Notes of an invoice in an account linked to the authenticated consumer, oldest first

Erros 404

curl -X GET "$CONSUMER_API/invoices/{id}/notes" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Notes of an invoice in an account linked to the authenticated consumer, oldest first

Descarregar uma factura em PDF

Registos

GET /invoices/{id}/pdf

Renders the invoice as a PDF, with the tenant's payment instructions, when it belongs to an account linked to the caller. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Returns 404 when the invoice is missing or outside the caller's scope.

Parâmetros

idstring · caminho · obrigatório

Invoice id

layoutstring · consulta · opcional · predefinição a4

Page format. mobile is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.

um de a4, mobile

Devolve

200 PDF document

Erros 403 · 404

curl -X GET "$CONSUMER_API/invoices/{id}/pdf" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

PDF document

Contestar uma factura

Registos

POST /invoices/{id}/dispute

Records a required reason, and optionally the line item or charge code being contested, and returns the invoice with its dispute details. While the dispute is open the account is left out of cutoff and late-penalty runs until the utility resolves it. Disputing again replaces the earlier dispute details. The invoice must be on an account where the caller holds the invoice.read account permission, found across the caller's tenants unless X-Tenant-ID narrows the search; any other invoice returns 404. Disputing also needs the ticket.create permission on the invoice's account (a personal API key needs the ticket.create scope); without it the call returns 403. A blank reason, a void invoice, a line_item_id that is not on the invoice or an unknown body field returns 400.

Parâmetros

idstring · caminho · obrigatório

ID of the invoice to dispute; it must be on one of the caller's accounts.

X-Tenant-IDstring · cabeçalho · opcional

Narrow the invoice lookup to one of the caller's tenants.

Corpo application/json

reasonstring · obrigatório

Why the caller contests the invoice; blank or whitespace-only is refused.

line_item_idstring · opcional

Optional line item being contested; it must be on the invoice.

charge_codestring · opcional

Optional charge code being contested; defaults to the line item's charge code when line_item_id is given.

Devolve

200 Invoice marked as disputed

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. 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.

meter_idstring · opcional
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.

billing_run_idstring · opcional
consumption_idstring · opcional
from_reading_idstring · opcional
to_reading_idstring · opcional
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
consumption_m3number · opcional
tariff_version_idstring · opcional
subtotal_centsinteger · opcional
sanitation_centsinteger · opcional
tax_centsinteger · opcional
total_centsinteger · obrigatório
balance_centsinteger · obrigatório
reconciliation_centsinteger · opcional
arrears_centsinteger · opcional
amount_due_centsinteger · obrigatório
estimatedboolean · opcional
estimate_reconciled_atstring (date-time) · opcional
currencystring · obrigatório
statusstring · obrigatório

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

Invoice lines. A line the server words carries description_code (invoice_line.fixed_fee, invoice_line.volumetric_tier, invoice_line.minimum_top_up, invoice_line.sanitation, invoice_line.vat, invoice_line.reconciliation) and description_params (tier, from, to; percent); clients word the code and fall back to description. Lines named after a tariff's own charges have no code.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404

curl -X POST "$CONSUMER_API/invoices/{id}/dispute" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "The meter reading on this invoice is higher than the meter shows.",
  "line_item_id": "lin_2UK5t48jnSYdLq0vr4Mh9kkthmC",
  "charge_code": "CHA-2026-000142"
}'
Resposta 200
{
  "id": "bil_2ddw83puA9dkmtvSYPhUgT7iqrb",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "invoice_number": "INV-2026-000142",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "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",
  "billing_run_id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "consumption_id": "con_2nR0I9tA6XXk4bxUyjPqmvxi8nN",
  "from_reading_id": "fro_2zXkivBGsXvOyvPqMFry433gEp5",
  "to_reading_id": "tor_2YMhF6MrDmIFLAyjLcYXv4YbHMe",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "consumption_m3": 13.42,
  "tariff_version_id": "tar_2TzCwDDsMdpa2HfkINTSsLvKunb",
  "subtotal_cents": 125000,
  "sanitation_cents": 1,
  "tax_cents": 1,
  "total_cents": 125000,
  "balance_cents": 125000,
  "reconciliation_cents": 1,
  "arrears_cents": 1,
  "amount_due_cents": 125000,
  "estimated": true,
  "estimate_reconciled_at": "2026-11-19T09:30:00Z",
  "currency": "MZN",
  "status": "draft",
  "due_date": "2026-11-19T09:30:00Z",
  "issued_at": "2026-11-19T09:30:00Z",
  "paid_at": "2026-11-19T09:30:00Z",
  "voided_at": "2026-11-19T09:30:00Z",
  "void_reason": "void reason",
  "disputed_at": "2026-11-19T09:30:00Z",
  "dispute_reason": "dispute reason",
  "written_off_at": "2026-11-19T09:30:00Z",
  "written_off_cents": 1,
  "write_off_reason": "write off reason",
  "line_items": [
    {}
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}