Generar cobro de una cuenta por cobrar

POST 
/receivables/:id/charge

Issues a bank slip or a Pix charge on the gateway so the customer has something to pay, and mirrors it onto the receivable. Requires scope finance.receivables.charge — a dedicated action scope, never bundled into .write, and the read god-scope finance.all does not satisfy it. An X-Idempotency-Key header is required: a duplicate charge is a second debt your customer receives.

⚠️ The charge in the response is not deliverable yet. Registration at the institution is asynchronous, so it comes back charge_state: "registering" — a bank slip does not exist at the bank yet and a Pix has no kobana_pix_qrcode. Poll GET /receivables/{id} until charge_state is registered before sending anything to the payer. There is no refresh endpoint on purpose: the mirror is kept current by a background poll and by the gateway's webhook, and a per-call re-read would burn the same hourly request budget the rest of the integration shares.

The two rails differ in what they require of the payer — a bank slip needs their full address, a Pix only name and document — and in what must be registered on the gateway account (an agreement vs. a Pix charging account). A missing piece comes back as 422 naming it; a state that forbids charging comes back as 409.

Solicitud

Respuestas

200

Charge issued. The body is the refreshed receivable detail with the charge mirror populated (charge_state will read registering).

400

Malformed JSON, or a missing / empty X-Idempotency-Key.

401

Missing / invalid / expired / revoked token.

403

Token lacks the finance.receivables.charge scope.

404

Receivable not found within the tenant.

409

The receivable's state forbids charging: it already has a charge, or it was already received or cancelled. Also returned when X-Idempotency-Key is reused with a different body.

422

Something required is missing, and the message names it: no person linked, no CPF/CNPJ, no due date, no full address (bank slip only), or no charging account / agreement registered on the gateway account.

429

Rate limit exceeded for this token. Reads and writes have separate budgets, both on a 1-hour sliding window. The response carries ratelimit-limit, ratelimit-remaining, ratelimit-reset and retry-after — wait out retry-after rather than retrying immediately.

500

The gateway refused the issue, or an unhandled server error.