Integrator's guide

The path for the developer wiring an ERP, billing system, or gateway into Dunning: key, first call, first customer and charge, webhooks, and safe retries. This page is the route; the full contracts live in the API Reference (generated from the OpenAPI spec, never handwritten).

1. Create the API key

In Settings → Security (administrators only), create a key with:

• "Read and write" access level — it covers the entire business operation without exposing account administration. Administrative resources answer 403 API_KEY_FORBIDDEN to any key: a leaked key cannot create administrators or other keys.
• Expiration (30/90/365 days) with warning emails — periodic rotation limits the blast radius of a leak.

The token is shown only once; store it in a secrets vault. Details in API keys.

2. First call

Single public environment (the Sandbox is in preparation — to develop risk-free in the meantime, use an account without configured sending channels: sends are simulated):

curl -s "https://dunning.kobana.com.br/api/v1/people?per_page=5" \
  -H "Authorization: Bearer $DUNNING_API_KEY" \
  -H "User-Agent: My Integration <dev@mycompany.com>"

The User-Agent identifying your integration is mandatory and goes into the audit trail.

3. First customer and first charge

The minimum flow is POST /people followed by POST /charges — the complete, annotated payloads are in Practical examples. What matters to get right from day one:

• externalId on everything — the record's ID in your system. It is the deduplication key: a duplicate document answers 409, and future imports update instead of duplicating.
• Contacts on the customer — without email/phone, the rule has nowhere to send.
• X-Idempotency-Key on every mutation — see step 5.
• Rule: pass collectionRuleId to pin the charge to a specific rule, or omit it and let automatic enrollment place the charge in the default rule.
• Payment data (pixEmv, paymentUrl, barcode) — the rule's messages go out already "payable".

4. Webhooks instead of polling

Register an endpoint (POST /webhook-endpoints or through the Webhooks screen) and receive business facts as JSON POSTs: charge.paid, charge.overdue, agreement.accepted, dispute.created... Rules of the game (overview):

• The URL must be https://; the secret (whsec_) is shown once and signs every delivery via HMAC (X-Webhook-Signature) — always verify it.
• Answer 2xx within 10 seconds: enqueue and process later.
• Delivery is at-least-once: deduplicate by event + data.id + timestamp. Failures enter the backoff retry cycle, with every attempt captured and manual redelivery available.

5. Idempotency and retries

Every mutation accepts X-Idempotency-Key (one UUID per business operation). If the network drops and you repeat the request with the same key within 24 hours, the API returns the original response (X-Idempotent-Replay: true) instead of duplicating the operation. Combine it with your retry policy: exponential backoff for 5xx, Retry-After for 429 RATE_LIMITED, and network timeouts treated as 5xx — idempotency resolves the "did it run or not?" ambiguity.

The house rules, in one table

Topic	Summary	Reference
Authentication	Authorization: Bearer <key>; scopes from dunning.dashboard.*	Authentication
Format	JSON UTF-8; camelCase responses; ISO 8601 dates; monetary values as decimal strings	Introduction
Pagination	page/per_page/sort_by/sort_order; filters in snake_case	Pagination
Errors	{ message, code, details? } envelope; branch on code	Errors and codes
Retention	Idempotency keys 24h; append-only audit trail	Data retention
Spec and Postman	OpenAPI 3.1 in PT/EN/ES + ready-made collection	Specifications · Postman

Integrator's checklist

• "Read and write" key with expiration, stored in a vault.
• User-Agent and X-Idempotency-Key in production from the first deploy.
• Webhook with signature verification and deduplication; monitored on the deliveries screen.
• Retry with backoff + Retry-After; no tight loops.
• Reconciliation by externalId in both directions (your system ↔ Dunning).