PT EN

Tarifas

URL base: $BUSINESS_API

O objecto

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
O objecto
{
  "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"
}

Listar tarifas

Registos

GET /tariffs

Returns the tenant's tariff schedules in cursor pages (limit up to 100, 20 by default, after for the next page), including drafts and superseded versions unless filtered. A free-text q parameter narrows the list further. Requires tariffs:read.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

categorystring · consulta · opcional

Returns only tariffs for this customer category: residential, commercial, industrial, institutional or government.

um de residential, commercial, industrial, institutional, government

statusstring · consulta · opcional

Returns only tariffs in this status: draft, active or superseded.

um de draft, active, superseded

Devolve

200 Tariffs in the utility tenant

Mostrar atributos
dataarray of UtilityTariff · obrigatório
Mostrar atributos filhos
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
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 403

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

curl -X GET "$BUSINESS_API/tariffs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Criar uma tarifa

Registos

POST /tariffs

Creates the schedule in draft status; it has no effect on billing until it is activated. code and name are required, category defaults to residential, currency defaults to the tenant's currency, and effective_from defaults to now. Tiers, fixed charges and charge components are validated (contiguous tier volumes, positive amounts, no duplicate fixed charge per code and diameter) and a violation returns 400; requires tariffs:write.

Corpo application/json

codestring · obrigatório
namestring · obrigatório
categorystring · opcional

um de residential, commercial, industrial, institutional, government

currencystring · opcional
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

Devolve

201 Tariff schedule created

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 · 403

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

curl -X POST "$BUSINESS_API/tariffs" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'
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"
}

Obter uma tarifa

Registos

GET /tariffs/{id}

Returns one tariff schedule with its tiers, fixed charges, charge components, taxes and effective dates. Returns 404 when the tariff is not in the caller's tenant; requires tariffs:read.

Parâmetros

idstring · caminho · obrigatório

ID of the tariff in the caller's tenant.

Devolve

200 Tariff in the authenticated tenant

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 403 · 404

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

curl -X GET "$BUSINESS_API/tariffs/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "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"
}

Activar uma tarifa

Registos

POST /tariffs/{id}/activate

Sets the tariff to active and bounds the tariff currently in force for the same category: if the new tariff is already effective, the old one is superseded now; if it is future-dated, the old one stays active until the new effective_from. A tariff.activated event is emitted, which also records the tariff's validity in the point-in-time history. The current status is not checked, so activating again re-applies the same changes; requires tariffs:write.

Parâmetros

idstring · caminho · obrigatório

ID of the tariff in the caller's tenant to activate.

Devolve

200 Activated tariff in the authenticated tenant

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 403 · 404

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

curl -X POST "$BUSINESS_API/tariffs/{id}/activate" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "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"
}

Obter os metadados de uma tarifa

Registos

GET /tariffs/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on the tariff, as an entry with resource_type, resource_id and a metadata map. The tariff must exist in the caller's tenant (404 otherwise); requires business:metadata:read.

Parâmetros

idstring · caminho · obrigatório

ID of the tariff in the caller's tenant, at most 120 characters.

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/tariffs/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Actualizar os metadados de uma tarifa

Registos

PUT /tariffs/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the keys in the metadata object into what the tariff already has; keys not sent are kept, and a key sent with an empty string is removed. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and a resource holds at most 50 keys; violations return 400 with one entry per invalid key. Returns the full metadata after the merge; requires business:metadata:write.

Parâmetros

idstring · caminho · obrigatório

ID of the tariff in the caller's tenant, at most 120 characters.

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

curl -X PUT "$BUSINESS_API/tariffs/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}