PT EN

Ciclos de facturação

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · opcional
schedule_idstring · opcional
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
total_invoicesinteger · obrigatório
total_amount_centsinteger · obrigatório
statusstring · obrigatório

um de pending, running, completed, failed

issued_invoicesinteger · obrigatório

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · obrigatório

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · obrigatório
estimated_invoicesinteger · obrigatório
exception_countinteger · obrigatório
error_messagestring · opcional
created_atstring (date-time) · obrigatório
completed_atstring (date-time) · opcional
O objecto
{
  "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "total_invoices": 125000,
  "total_amount_cents": 125000,
  "status": "pending",
  "issued_invoices": 1,
  "issued_amount_cents": 125000,
  "skipped_accounts": 1,
  "estimated_invoices": 1,
  "exception_count": 1,
  "error_message": "error message",
  "created_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z"
}

Listar ciclos de facturação

Registos

GET /billing-runs

Returns the tenant's billing runs with cursor pagination (limit defaults to 20, at most 100), optionally filtered by status. Each run shows its period, service area, status, issued, skipped and estimated invoice counts, total amount and exception count. Requires billing_runs:read.

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 Billing runs

Mostrar atributos
dataarray of BillingRun · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · opcional
schedule_idstring · opcional
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
total_invoicesinteger · obrigatório
total_amount_centsinteger · obrigatório
statusstring · obrigatório

um de pending, running, completed, failed

issued_invoicesinteger · obrigatório

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · obrigatório

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · obrigatório
estimated_invoicesinteger · obrigatório
exception_countinteger · obrigatório
error_messagestring · opcional
created_atstring (date-time) · obrigatório
completed_atstring (date-time) · opcional
has_moreboolean · obrigatório
next_cursorstring · opcional
total_countinteger · opcional

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
      "period_start": "2026-11-19T09:30:00Z",
      "period_end": "2026-11-19T09:30:00Z",
      "total_invoices": 125000,
      "total_amount_cents": 125000,
      "status": "pending",
      "issued_invoices": 1,
      "issued_amount_cents": 125000,
      "skipped_accounts": 1,
      "estimated_invoices": 1,
      "exception_count": 1,
      "error_message": "error message",
      "created_at": "2026-11-19T09:30:00Z",
      "completed_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Iniciar um ciclo de facturação

Registos

POST /billing-runs

Issues one invoice per account for the period from accepted consumptions; period_start must be before period_end and due_date, when given, must not fall before period_end. A period is billed by one run: calling again for the same period and service area reuses that run and skips accounts already invoiced, so retrying after a partial failure is safe. When the job queue is enabled and the period is large, the run is queued and returned in running status for you to poll. Records billing_run.started and then billing_run.posted or billing_run.failed events, plus exception events for skipped accounts; requires billing_runs:write and the billing capability, and returns 201.

Corpo application/json

period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
due_datestring (date-time) · opcional
service_area_idstring · opcional
auto_consumptionboolean · opcional
estimate_missingboolean · opcional

Devolve

201 Billing run started

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · opcional
schedule_idstring · opcional
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
total_invoicesinteger · obrigatório
total_amount_centsinteger · obrigatório
statusstring · obrigatório

um de pending, running, completed, failed

issued_invoicesinteger · obrigatório

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · obrigatório

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · obrigatório
estimated_invoicesinteger · obrigatório
exception_countinteger · obrigatório
error_messagestring · opcional
created_atstring (date-time) · obrigatório
completed_atstring (date-time) · opcional

Erros 403

Permissões billing_runs:write · Funções: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "due_date": "2026-11-19T09:30:00Z",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "auto_consumption": true,
  "estimate_missing": true
}'
Resposta 201
{
  "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "total_invoices": 125000,
  "total_amount_cents": 125000,
  "status": "pending",
  "issued_invoices": 1,
  "issued_amount_cents": 125000,
  "skipped_accounts": 1,
  "estimated_invoices": 1,
  "exception_count": 1,
  "error_message": "error message",
  "created_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z"
}

Obter um ciclo de facturação

Registos

GET /billing-runs/{id}

Returns one billing run with its period, service area, schedule, status, invoice counts, total amount, exception count, error message and completion time. Poll it after a queued run to see when it completes. Answers 404 when the run is not in the caller's tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run (prefix brn_).

Devolve

200 Billing run

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
service_area_idstring · opcional
schedule_idstring · opcional
period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
total_invoicesinteger · obrigatório
total_amount_centsinteger · obrigatório
statusstring · obrigatório

um de pending, running, completed, failed

issued_invoicesinteger · obrigatório

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · obrigatório

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · obrigatório
estimated_invoicesinteger · obrigatório
exception_countinteger · obrigatório
error_messagestring · opcional
created_atstring (date-time) · obrigatório
completed_atstring (date-time) · opcional

Erros 404

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "total_invoices": 125000,
  "total_amount_cents": 125000,
  "status": "pending",
  "issued_invoices": 1,
  "issued_amount_cents": 125000,
  "skipped_accounts": 1,
  "estimated_invoices": 1,
  "exception_count": 1,
  "error_message": "error message",
  "created_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z"
}

Pré-visualizar um ciclo de facturação

Registos

POST /billing-runs/preview

Report what a billing run would issue, with no side effects

Takes the same body as executeBillingRun and returns, per account, the invoice that would be issued (consumption, line items, charges, tax, reconciliation, arrears, due date and payment instructions) plus the exceptions that would be raised and the totals. Nothing is stored or issued and no event is recorded. capability_active reports whether the billing capability is on, so a run would actually be allowed. Requires billing_runs:read.

Corpo application/json

period_startstring (date-time) · obrigatório
period_endstring (date-time) · obrigatório
due_datestring (date-time) · opcional
service_area_idstring · opcional
auto_consumptionboolean · opcional
estimate_missingboolean · opcional

Devolve

200 Invoices that would be issued and accounts that would be skipped, with capability_active

Mostrar atributos
period_startstring (date-time) · opcional
period_endstring (date-time) · opcional
service_area_idstring · opcional
capability_activeboolean · opcional
invoice_countinteger · opcional
estimated_countinteger · opcional
total_amount_centsinteger · opcional
exception_countinteger · opcional
invoicesarray of object · opcional
exceptionsarray of object · opcional

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X POST "$BUSINESS_API/billing-runs/preview" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "due_date": "2026-11-19T09:30:00Z",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "auto_consumption": true,
  "estimate_missing": true
}'
Resposta 200
{
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "capability_active": true,
  "invoice_count": 1,
  "estimated_count": 1,
  "total_amount_cents": 125000,
  "exception_count": 1,
  "invoices": [
    {}
  ],
  "exceptions": [
    {}
  ]
}

Repetir um ciclo de facturação

Registos

POST /billing-runs/{id}/retry

Executes the run's period again: accounts already invoiced are skipped, accounts that failed or were not billable before are attempted again, and the run's counts and exceptions are replaced with the new outcome. Exceptions that were dismissed before are dismissed again with the same note when they recur. Estimates are used again only if the original run issued estimated invoices. Requires billing_runs:write and returns the updated run.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run to retry (prefix brn_).

Devolve

200 Updated billing run

Permissões billing_runs:write · Funções: admin, finance, owner

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

Updated billing run

Resolver uma excepção de um ciclo

Registos

POST /billing-runs/{id}/exceptions/{exceptionId}/resolve

Sets the exception's review status to resolved (the default) or dismissed, and records who did it, when, and an optional resolution note. Any other status answers 400, and an exception that does not belong to the run in the path answers 404. Dismissals are carried over when the run is retried. Requires billing_runs:write.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run the exception belongs to (prefix brn_).

exceptionIdstring · caminho · obrigatório

Identifier of the exception to resolve or dismiss (prefix rex_).

Corpo application/json

statusstring · opcional

um de resolved, dismissed

resolution_notestring · opcional

Devolve

200 Updated exception

Permissões billing_runs:write · Funções: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs/{id}/exceptions/{exceptionId}/resolve" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "resolved",
  "resolution_note": "resolution note"
}'
Resposta 200

Updated exception

Listar excepções de um ciclo

Registos

GET /billing-runs/{id}/exceptions

Returns the accounts the run skipped or failed to bill, each with the reason, detail and review status, with cursor pagination (limit defaults to 20, at most 100). Filter by reason or by status (open, resolved or dismissed). Answers 404 when the run is not in the tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run whose exceptions to list (prefix brn_).

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

reasonstring · consulta · opcional

Return only exceptions with this reason: already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed or reconciliation_credit_exceeds_bill.

um de already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed, reconciliation_credit_exceeds_bill

Devolve

200 Exceptions

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

reasonstring · obrigatório

um de already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed, reconciliation_credit_exceeds_bill

detailstring · opcional
created_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional
total_countinteger · opcional

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}/exceptions" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "run_21N6eP9iEDLkipnkOBnWWxpc4XP",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "run_id": "run_2VvMAN1CyVnimXb8yn1Qon7gqrJ",
      "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",
      "reason": "already_billed",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Descarregar o arquivo de facturas em PDF

Registos

GET /billing-runs/{id}/invoice-pdfs

Streams the ZIP archive prepared by enqueueInvoicePdfBatch, as an attachment whose file name depends on the negotiated document language. Answers 404 while no archive exists for the run, so check the status endpoint first.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run whose archive to download (prefix brn_).

Devolve

200 ZIP archive

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

ZIP archive

Gerar o arquivo de facturas em PDF

Registos

POST /billing-runs/{id}/invoice-pdfs

Queue a PDF archive of every invoice of a billing run (job queue enabled)

Queues a background job that renders the PDF of every invoice issued by the run into one ZIP archive, and answers 202 with job_id and status. Repeating the call for the same run reuses the queued job. Requires billing_runs:write; answers 404 for an unknown run and 409 when background jobs are not enabled on the installation.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run whose invoices to archive (prefix brn_).

Devolve

202 The queued job id

Erros 409

Permissões billing_runs:write · Funções: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs/{id}/invoice-pdfs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 202

The queued job id

Obter o estado do arquivo de facturas em PDF

Registos

GET /billing-runs/{id}/invoice-pdfs/status

Whether the invoice PDF archive can be prepared and is ready, without a 404 while it is absent

Returns enabled, which says whether background jobs can prepare an archive on this installation, and available, which says whether a finished archive for the run can be downloaded now. It answers 200 in both cases so a client can poll after queuing; 404 only when the run itself is unknown.

Parâmetros

idstring · caminho · obrigatório

Identifier of the billing run whose archive status to read (prefix brn_).

Devolve

200 The archive state

Mostrar atributos
enabledboolean · obrigatório

False when this installation runs without the job queue

availableboolean · obrigatório

True when a finished archive can be downloaded

Permissões billing_runs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}/invoice-pdfs/status" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "enabled": true,
  "available": true
}