PT EN

Modelos de tarifa

URL base: $BUSINESS_API

O objecto

country_codestring · obrigatório
currencystring · opcional
availableboolean · obrigatório
reasonstring · opcional

um de no_template_for_country, country_unset

templatesarray of object · obrigatório
Mostrar atributos filhos
idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

currencystring · obrigatório
fixed_fee_centsinteger · obrigatório
min_consumption_m3number · obrigatório
sanitation_surcharge_percentnumber · obrigatório
tax_percentnumber · obrigatório
tiersarray of object · obrigatório
Mostrar atributos filhos
min_m3number · opcional
max_m3number · opcional

0 means no upper bound

rate_per_m3_centsinteger · opcional
O objecto
{
  "country_code": "MZ",
  "currency": "MZN",
  "available": true,
  "reason": "no_template_for_country",
  "templates": [
    {
      "id": "mz.dom",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "category": "residential",
      "currency": "MZN",
      "fixed_fee_cents": 125000,
      "min_consumption_m3": 13.42,
      "sanitation_surcharge_percent": 1,
      "tax_percent": 1,
      "tiers": [
        {
          "min_m3": 1,
          "max_m3": 1,
          "rate_per_m3_cents": 1
        }
      ]
    }
  ]
}

Listar modelos de tarifa

Registos

GET /tariff-templates

The tariffs of the seed dataset for the utility's country, at the dataset's latest prices, as starting points, so a tariff never starts from a blank form and no tariff values live in clients. available is false with reason no_template_for_country or country_unset when there is none. Requires tariffs:read.

Devolve

200 The templates

Mostrar atributos
country_codestring · obrigatório
currencystring · opcional
availableboolean · obrigatório
reasonstring · opcional

um de no_template_for_country, country_unset

templatesarray of object · obrigatório
Mostrar atributos filhos
idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

currencystring · obrigatório
fixed_fee_centsinteger · obrigatório
min_consumption_m3number · obrigatório
sanitation_surcharge_percentnumber · obrigatório
tax_percentnumber · obrigatório
tiersarray of object · obrigatório
Mostrar atributos filhos
min_m3number · opcional
max_m3number · opcional

0 means no upper bound

rate_per_m3_centsinteger · opcional

Erros 401 · 403

curl -X GET "$BUSINESS_API/tariff-templates" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "country_code": "MZ",
  "currency": "MZN",
  "available": true,
  "reason": "no_template_for_country",
  "templates": [
    {
      "id": "mz.dom",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "category": "residential",
      "currency": "MZN",
      "fixed_fee_cents": 125000,
      "min_consumption_m3": 13.42,
      "sanitation_surcharge_percent": 1,
      "tax_percent": 1,
      "tiers": [
        {
          "min_m3": 1,
          "max_m3": 1,
          "rate_per_m3_cents": 1
        }
      ]
    }
  ]
}

Criar uma tarifa a partir de um modelo

Registos

POST /tariff-templates/{templateID}/apply

Creates the template's tariff through the billing service, optionally with another code or name and an effective date (default now), and activates it when activate is true. A template applied and activated in the real account completes the utility_real tariffs step. Returns the created tariff. Requires tariffs:write.

Parâmetros

templateIDstring · caminho · obrigatório

Template ID from the list

Corpo application/json

codestring · opcional
namestring · opcional
effective_fromstring (date-time) · opcional
activateboolean · opcional

Devolve

201 The created tariff

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
categorystring · obrigatório

um de residential, commercial, industrial, institutional, government

currencystring · obrigatório
minor_unitsinteger · opcional
fixed_fee_centsinteger (int64) · opcional
min_consumption_m3number · opcional
minimum_charge_centsinteger (int64) · opcional
sanitation_surcharge_percentnumber · opcional
tax_percentnumber · opcional
tiersarray of UtilityTariffTier · opcional
Mostrar atributos filhos
tier_numberinteger · opcional
min_m3number · opcional
max_m3number · opcional

Zero means unbounded

rate_per_m3_centsinteger (int64) · opcional
volume_start_linteger (int64) · opcional
volume_end_linteger (int64) · opcional · anulável
fixed_chargesarray of UtilityTariffFixedCharge · opcional
Mostrar atributos filhos
charge_codestring · obrigatório
descriptionstring · opcional
diameter_mminteger · opcional
amount_minorinteger (int64) · obrigatório
charge_componentsarray of UtilityTariffChargeComponent · opcional
Mostrar atributos filhos
codestring · obrigatório
namestring · obrigatório
descriptionstring · opcional
labelsobject · opcional
kindstring · obrigatório

um de fixed, percentage

amount_minorinteger (int64) · opcional
rate_basis_pointsinteger (int64) · opcional
rate_percentnumber · opcional
basisstring · opcional

um de service_subtotal

taxableboolean · opcional
sort_orderinteger · opcional
cadencestring · opcional

um de every_bill, every_n_periods, one_time

interval_periodsinteger · opcional
anchor_datestring (date-time) · opcional · anulável
effective_fromstring (date-time) · opcional · anulável
effective_tostring (date-time) · opcional · anulável
partial_period_policystring · opcional

um de full, prorate, skip

skipped_cycle_policystring · opcional

um de skip

activeboolean · opcional
diameter_mminteger · opcional · anulável
service_area_idstring · opcional
payment_termsstring · opcional

um de inherit_invoice

accounting_rolestring · opcional
effective_fromstring (date-time) · opcional
effective_tostring (date-time) · opcional · anulável
statusstring · obrigatório

um de draft, active, superseded

created_atstring (date-time) · opcional
updated_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 404 · 409

curl -X POST "$BUSINESS_API/tariff-templates/{templateID}/apply" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "effective_from": "2026-11-19T09:30:00Z",
  "activate": true
}'
Resposta 201
{
  "id": "uti_2lVUY3v2KN5iaJpucZDwaxd8of9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "category": "residential",
  "currency": "MZN",
  "minor_units": 1,
  "fixed_fee_cents": 125000,
  "min_consumption_m3": 13.42,
  "minimum_charge_cents": 1,
  "sanitation_surcharge_percent": 1,
  "tax_percent": 1,
  "tiers": [
    {
      "tier_number": 1,
      "min_m3": 1,
      "max_m3": 1,
      "rate_per_m3_cents": 1,
      "volume_start_l": 1342,
      "volume_end_l": 1342
    }
  ],
  "fixed_charges": [
    {
      "charge_code": "CHA-2026-000142",
      "description": "Leitura confirmada no local.",
      "diameter_mm": 1,
      "amount_minor": 125000
    }
  ],
  "charge_components": [
    {
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "labels": {
        "key": "value"
      },
      "kind": "fixed",
      "amount_minor": 125000,
      "rate_basis_points": 1,
      "rate_percent": 1,
      "basis": "service_subtotal",
      "taxable": true,
      "sort_order": 1,
      "cadence": "every_bill",
      "interval_periods": 1,
      "anchor_date": "2026-11-19T09:30:00Z",
      "effective_from": "2026-11-19T09:30:00Z",
      "effective_to": "2026-11-19T09:30:00Z",
      "partial_period_policy": "full",
      "skipped_cycle_policy": "skip",
      "active": true,
      "diameter_mm": 1,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "payment_terms": "inherit_invoice",
      "accounting_role": "accounting role"
    }
  ],
  "effective_from": "2026-11-19T09:30:00Z",
  "effective_to": "2026-11-19T09:30:00Z",
  "status": "draft",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}