PT EN

Créditos

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
account_idstring · obrigatório
campaign_idstring · opcional
fundingstring · obrigatório

um de cash, granted

sourcestring · obrigatório
amount_minorinteger (int64) · obrigatório
remaining_minorinteger (int64) · obrigatório
currencystring · obrigatório
applies_toarray of string · opcional
charge_kindsarray of string · opcional
expires_atstring (date-time) · opcional
statusstring · obrigatório

um de pending_approval, active, exhausted, expired, rejected

proposed_bystring · opcional
approved_bystring · opcional
rejection_reasonstring · opcional
reasonstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "id": "cre_2cmf76oNbMmjnic9ZsClLOiDDwu",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "campaign_id": "cam_2WQBFWMJR6y3LeY1tCERReuZREk",
  "funding": "cash",
  "source": "source",
  "amount_minor": 125000,
  "remaining_minor": 1,
  "currency": "MZN",
  "applies_to": [
    "2026-11-19"
  ],
  "charge_kinds": [
    "charge kind"
  ],
  "expires_at": "2026-11-19T09:30:00Z",
  "status": "pending_approval",
  "proposed_by": "proposed by",
  "approved_by": "approved by",
  "rejection_reason": "rejection reason",
  "reason": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar créditos

Registos

GET /credit-grants

List the utility's credit grants, such as those waiting for approval

Requires invoices:read. Newest first, one cursor page at a time.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

statusstring · consulta · opcional

Return only grants in this status: pending_approval, active, exhausted, expired or rejected; any other value returns 400.

um de pending_approval, active, exhausted, expired, rejected

account_idstring · consulta · opcional

Return only grants made to this account ID.

Devolve

200 Grant page

Mostrar atributos
dataarray of CreditGrant · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
account_idstring · obrigatório
campaign_idstring · opcional
fundingstring · obrigatório

um de cash, granted

sourcestring · obrigatório
amount_minorinteger (int64) · obrigatório
remaining_minorinteger (int64) · obrigatório
currencystring · obrigatório
applies_toarray of string · opcional
charge_kindsarray of string · opcional
expires_atstring (date-time) · opcional
statusstring · obrigatório

um de pending_approval, active, exhausted, expired, rejected

proposed_bystring · opcional
approved_bystring · opcional
rejection_reasonstring · opcional
reasonstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400

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

curl -X GET "$BUSINESS_API/credit-grants" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "cre_2cmf76oNbMmjnic9ZsClLOiDDwu",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "campaign_id": "cam_2WQBFWMJR6y3LeY1tCERReuZREk",
      "funding": "cash",
      "source": "source",
      "amount_minor": 125000,
      "remaining_minor": 1,
      "currency": "MZN",
      "applies_to": [
        "2026-11-19"
      ],
      "charge_kinds": [
        "charge kind"
      ],
      "expires_at": "2026-11-19T09:30:00Z",
      "status": "pending_approval",
      "proposed_by": "proposed by",
      "approved_by": "approved by",
      "rejection_reason": "rejection reason",
      "reason": "Leitura confirmada no local.",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Atribuir um crédito

Registos

POST /credit-grants

Creates a credit for one account; account_id and a positive amount_minor are required. Unless requires_approval is true the grant is active immediately: a grant transaction is recorded and the credit is applied to the account's open invoices, and the response shows the remaining amount after that. With requires_approval true the grant is stored as pending_approval and a different user must approve it. Optional fields default to funding granted, source promotion, applies_to water_invoice and charge_kinds water and sanitation; requires invoices:write.

Devolve

201 Credit grant created

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

curl -X POST "$BUSINESS_API/credit-grants" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Resposta 201

Credit grant created

Aprovar um crédito

Registos

POST /credit-grants/{id}/approve

Approve a pending credit grant (maker-checker)

Activates a grant that is pending approval, records the grant transaction and applies the credit to the account's open invoices, then returns the updated grant. The user who proposed the grant cannot approve it. Requires invoices:write; a grant that is not pending approval, or approval by its proposer, returns 400, and an unknown grant returns 404.

Parâmetros

idstring · caminho · obrigatório

Identifier of the credit grant to approve; it must be in the pending_approval status.

Devolve

200 Credit grant approved

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

curl -X POST "$BUSINESS_API/credit-grants/{id}/approve" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Credit grant approved

Rejeitar um crédito

Registos

POST /credit-grants/{id}/reject

Marks a pending grant as rejected, stores the rejection reason and sets its remaining amount to zero, so no credit is ever applied. A non-empty reason is required. Requires invoices:write; a missing reason or a grant that is not pending approval returns 400, and an unknown grant returns 404.

Parâmetros

idstring · caminho · obrigatório

Identifier of the credit grant to reject; it must be in the pending_approval status.

Corpo application/json

reasonstring · opcional

Devolve

200 Credit grant rejected

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

curl -X POST "$BUSINESS_API/credit-grants/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Resposta 200

Credit grant rejected

Atribuir créditos a várias contas

Registos

POST /credit-grants/bulk

Creates one active granted credit per account in account_ids, each for the same amount_minor, and applies each to that account's open invoices. The response reports how many grants were created and lists them. Grants are created one at a time without a transaction, so if one account fails the request returns the error and the grants already created remain. Requires invoices:write; an empty account_ids or a non-positive amount returns 400.

Devolve

201 Bulk credit grants created

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

curl -X POST "$BUSINESS_API/credit-grants/bulk" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Resposta 201

Bulk credit grants created

Obter o passivo de créditos

Registos

GET /credit-grants/liability

Summarizes the tenant's outstanding granted credit: the unapplied remaining amount of active, unexpired granted-funding grants, how many such grants exist, and how much of that amount expires within the next 30 days. The response also lists the tenant's credit campaigns. Requires invoices:read.

Devolve

200 Credit liability report

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

curl -X GET "$BUSINESS_API/credit-grants/liability" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Credit liability report