PT EN

Cobrança

URL base: $BUSINESS_API

Listar contas elegíveis para corte

Registos

GET /collections/eligible-cutoffs

Accounts past the tenant threshold, excluding active plans and disputes

Lists, most overdue first, the accounts that the tenant's collection policy allows to be disconnected now: overdue past cutoff_past_due_days, owing at least cutoff_min_debt_cents, not on an active payment plan, with no disputed invoice, with an active connection, and not already pending cutoff or disconnected. The list is computed live from billing; page with limit (default 20, max 100) and the after cursor, which stays stable when an account pays between pages. Requires collections: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 Success

Erros 400 · 403 · 404 · 409

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

curl -X GET "$BUSINESS_API/collections/eligible-cutoffs" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Gerar ordens de corte

Registos

POST /collections/orders/generate

Raises a disconnection field order for each currently eligible account, or only for the ids in account_ids. For each one it opens a case if none exists, moves the case to enforcement_requested with dunning set to cutoff pending, creates the order with the optional priority and scheduled_for, and emits a cutoff-order-generated event. It first defaults payment plans that are overdue past the grace period. An existing order on a case is reused, so repeating the call does not create duplicates; requested accounts that are not eligible come back in skipped. Returns 400 when field orders are not connected. Requires collections:write.

Corpo application/json

account_idsarray of object · opcional
scheduled_forstring · opcional
prioritystring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/collections/orders/generate" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "account_ids": [],
  "scheduled_for": "scheduled for",
  "priority": "priority"
}'
Resposta 200

Success

Obter a antiguidade da dívida

Registos

GET /collections/ageing

Debt ageing buckets (current, 30, 60, 90, 120+)

Totals the outstanding balance of the tenant's open invoices into ageing buckets (current, 1-30, 31-60, 61-90 and over 90 days past due) with the number of distinct accounts in each, as of now. The figures are computed live from billing, not from collection cases. Returns 400 when billing is not connected to collections. Requires collections:read.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X GET "$BUSINESS_API/collections/ageing" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Obter a política de corte

Registos

GET /collections/policy

Returns the tenant's disconnection policy: how many days past due an account must be (cutoff_past_due_days), the minimum overdue debt (cutoff_min_debt_cents), and how many days an unpaid instalment may be late before its plan defaults (plan_default_grace_days). When the tenant has not saved a policy, the defaults are returned: 30 days, 1 minor unit and 30 days. Requires collections:read.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X GET "$BUSINESS_API/collections/policy" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Actualizar a política de corte

Registos

PUT /collections/policy

Changes only the policy fields sent and returns the full policy; omitted fields keep their current or default values. Values must not be negative, otherwise 400. The new values apply on the next eligibility check, cutoff generation and plan-default sweep. Requires collections:write.

Corpo application/json

cutoff_past_due_daysinteger · opcional
cutoff_min_debt_centsinteger · opcional
plan_default_grace_daysinteger · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X PUT "$BUSINESS_API/collections/policy" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "cutoff_past_due_days": 125000,
  "cutoff_min_debt_cents": 1,
  "plan_default_grace_days": 1
}'
Resposta 200

Success

Listar planos de pagamento

Registos

GET /collections/payment-plans

Returns a cursor-paginated list of the tenant's payment plans with their instalments, filterable by account_id, case_id and status. Page with limit (default 20, max 100) and the after cursor. Requires collections: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 Success

Erros 400 · 403 · 404 · 409

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

curl -X GET "$BUSINESS_API/collections/payment-plans" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Criar um plano de pagamento

Registos

POST /collections/payment-plans

Puts a collection case on an instalment plan and moves the case to payment_plan_active, which takes the account out of cutoff eligibility. installment_count defaults to 3, interval_months to 1 and first_due_date to one month from now; simple interest from interest_basis_points is added to the debt, with the rounding remainder on the last instalment. Interest is charged to the account in billing, and a payment-plan-created event is emitted. Returns 404 for an unknown case and 400 for negative interest. Requires collections:write.

Corpo application/json

case_idstring · opcional
installment_countinteger · opcional
first_due_datestring · opcional
interest_basis_pointsinteger · opcional
interval_monthsinteger · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/collections/payment-plans" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "case_id": "cas_2gmnNK0lRMC9tOMtZsWDhKGHpGe",
  "installment_count": 1,
  "first_due_date": "2026-11-19",
  "interest_basis_points": 1,
  "interval_months": 1
}'
Resposta 200

Success

Obter um plano de pagamento

Registos

GET /collections/payment-plans/{id}

Returns one payment plan with its totals, interest, remaining amount, next due date, status and the full instalment schedule. Returns 404 when the plan is not in this tenant. Requires collections:read.

Parâmetros

idstring · caminho · obrigatório

Id of the payment plan (prefix pln).

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X GET "$BUSINESS_API/collections/payment-plans/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Declarar um plano de pagamento em incumprimento

Registos

POST /collections/payment-plans/{id}/default

Marks an active payment plan as defaulted, which makes the account eligible for cutoff again under the collection policy. Only an active plan can default; any other status returns 409. Plans are also defaulted automatically when an instalment is unpaid past the policy's grace period. Requires collections:write.

Parâmetros

idstring · caminho · obrigatório

Id of the payment plan to default (prefix pln).

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/collections/payment-plans/{id}/default" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Abater a dívida de um caso de cobrança

Registos

POST /collections/cases/{id}/write-off

Declares the account's debt uncollectible: writes off every open invoice of the case's account in billing, moves the case to written_off (a final status), and settles any active dunning status. A non-empty reason is required and is passed to each invoice write-off. A case that cannot move to written off returns 409. Requires collections:write.

Parâmetros

idstring · caminho · obrigatório

Id of the collection case to write off (prefix col).

Corpo application/json

reasonstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

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

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

Success