PT EN

Política de facturação

URL base: $BUSINESS_API

O objecto

tenant_idstring · opcional
default_due_daysinteger · opcional
grace_period_daysinteger · opcional
default_missing_reading_m3number · opcional · anulável

Default consumption in m3 used when a reading is missing and no history exists.

late_penalty_enabledboolean · opcional
late_penalty_kindstring · opcional
late_penalty_amount_minorinteger (int64) · opcional
late_penalty_rate_basis_pointsinteger (int64) · opcional
late_penalty_frequencystring · opcional
late_penalty_interval_daysinteger · opcional
late_penalty_cap_minorinteger (int64) · opcional
late_penalty_taxableboolean · opcional
late_penalty_compoundboolean · opcional
exclude_disputed_from_penaltyboolean · opcional
exclude_payment_plan_from_penaltyboolean · opcional
versioninteger · opcional
updated_atstring (date-time) · opcional
O objecto
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "default_due_days": 125000,
  "grace_period_days": 1,
  "default_missing_reading_m3": 13.42,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true,
  "version": 1,
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter a política de facturação

Registos

GET /billing-policy

Returns the tenant's billing policy: default due days, grace period, the default volume used for missing readings, and the late penalty settings (kind, amount or rate, frequency, interval, cap, tax and compounding, and exclusions for disputed invoices and payment plans). A tenant that never saved a policy gets the default policy. Requires tariffs:read.

Devolve

200 Billing policy

Mostrar atributos
tenant_idstring · opcional
default_due_daysinteger · opcional
grace_period_daysinteger · opcional
default_missing_reading_m3number · opcional · anulável

Default consumption in m3 used when a reading is missing and no history exists.

late_penalty_enabledboolean · opcional
late_penalty_kindstring · opcional
late_penalty_amount_minorinteger (int64) · opcional
late_penalty_rate_basis_pointsinteger (int64) · opcional
late_penalty_frequencystring · opcional
late_penalty_interval_daysinteger · opcional
late_penalty_cap_minorinteger (int64) · opcional
late_penalty_taxableboolean · opcional
late_penalty_compoundboolean · opcional
exclude_disputed_from_penaltyboolean · opcional
exclude_payment_plan_from_penaltyboolean · opcional
versioninteger · opcional
updated_atstring (date-time) · opcional

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

curl -X GET "$BUSINESS_API/billing-policy" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "default_due_days": 125000,
  "grace_period_days": 1,
  "default_missing_reading_m3": 13.42,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true,
  "version": 1,
  "updated_at": "2026-11-19T09:30:00Z"
}

Actualizar a política de facturação

Registos

PUT /billing-policy

Applies only the fields present in the body to the current policy, then validates the result: due days, grace period and penalty cap must not be negative, the default missing-reading volume must be a non-negative finite number, and late_penalty_frequency must be one_time or recurring (the default). When late penalties are enabled the chosen kind needs its amount or rate, for example a positive late_penalty_amount_minor for a fixed penalty. Send clear_default_missing_reading true to remove the default volume. Requires tariffs:write; returns the saved policy or 400.

Corpo application/json

default_due_daysinteger · opcional
grace_period_daysinteger · opcional
default_missing_reading_m3number · opcional · anulável
clear_default_missing_readingboolean · opcional
late_penalty_enabledboolean · opcional
late_penalty_kindstring · opcional
late_penalty_amount_minorinteger (int64) · opcional
late_penalty_rate_basis_pointsinteger (int64) · opcional
late_penalty_frequencystring · opcional
late_penalty_interval_daysinteger · opcional
late_penalty_cap_minorinteger (int64) · opcional
late_penalty_taxableboolean · opcional
late_penalty_compoundboolean · opcional
exclude_disputed_from_penaltyboolean · opcional
exclude_payment_plan_from_penaltyboolean · opcional

Devolve

200 Updated billing policy

Mostrar atributos
tenant_idstring · opcional
default_due_daysinteger · opcional
grace_period_daysinteger · opcional
default_missing_reading_m3number · opcional · anulável

Default consumption in m3 used when a reading is missing and no history exists.

late_penalty_enabledboolean · opcional
late_penalty_kindstring · opcional
late_penalty_amount_minorinteger (int64) · opcional
late_penalty_rate_basis_pointsinteger (int64) · opcional
late_penalty_frequencystring · opcional
late_penalty_interval_daysinteger · opcional
late_penalty_cap_minorinteger (int64) · opcional
late_penalty_taxableboolean · opcional
late_penalty_compoundboolean · opcional
exclude_disputed_from_penaltyboolean · opcional
exclude_payment_plan_from_penaltyboolean · opcional
versioninteger · opcional
updated_atstring (date-time) · opcional

Erros 422

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

curl -X PUT "$BUSINESS_API/billing-policy" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "default_due_days": 125000,
  "grace_period_days": 0,
  "default_missing_reading_m3": 13.42,
  "clear_default_missing_reading": true,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true
}'
Resposta 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "default_due_days": 125000,
  "grace_period_days": 1,
  "default_missing_reading_m3": 13.42,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true,
  "version": 1,
  "updated_at": "2026-11-19T09:30:00Z"
}

Aplicar penalizações por atraso

Registos

POST /billing-policy/assess-late-penalties

Runs the tenant's late penalty policy immediately instead of waiting for the scheduled run. Each open invoice with a balance whose due date plus the grace period has passed gets a late fee debit note, fixed or a percentage of the overdue balance and limited by the cap, unless the policy excludes disputed invoices or accounts on an active payment plan. Penalties are idempotent per invoice, policy version and recurrence cycle, so calling again does not charge twice. When late penalties are disabled in the billing policy nothing is applied and applied is 0. No request body is read. Requires invoices:write.

Devolve

200 Number of penalties applied by this run

Mostrar atributos
appliedinteger · obrigatório

Late fee debit notes created by this call.

Erros 400 · 401 · 403

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

curl -X POST "$BUSINESS_API/billing-policy/assess-late-penalties" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "applied": 3
}