Start here
Everything the dashboard does in the collection operation exists in the API v1: customers, charges, collection rules, agreements, disputes, tasks, imports, webhooks. This section covers the practical path; the full contracts are in the API Reference, generated from the OpenAPI spec (never hand-written).
You don't have to leave the docs to try it out: every endpoint in the API Reference has a Send API Request button that fires the call live against production. Paste your key, fill in the parameters and see the real response instantly — no Postman, no curl, no code to write. Start with a read-only key to explore risk-free.
In 3 steps
1. Create an API key in Settings → Security (you must be an administrator). Choose the access level — for integrations, "Read and write" covers the entire operation without exposing account administration — and copy the token, which is shown only once. Details in API keys.
2. Make the first call:
curl -s "https://dunning.kobana.com.br/api/v1/people?per_page=5" \
-H "Authorization: Bearer $DUNNING_API_KEY" \
-H "User-Agent: Minha Integracao <dev@minhaempresa.com.br>"
3. Follow the full flow in Practical examples: create a customer, create a charge and track everything through webhooks.
House rules
Each has its own page in the reference's overview — read them before going to production:
| Topic | One-line summary |
|---|---|
| Authentication | Authorization: Bearer <chave>; scopes in the dunning.dashboard.* catalog |
| User-Agent | Identify your integration on every request; it goes into the audit trail |
| Idempotency | X-Idempotency-Key on mutations; safe replay for 24h |
| Pagination and filters | page/per_page/sort_by/sort_order; filters in snake_case |
| Rate limiting | 429 RATE_LIMITED per key; retry with backoff |
| OpenAPI specifications | 3.1 spec in PT/EN/ES, importable in any tool |
Environment
There is a single public environment:
| Environment | Base URL |
|---|---|
| Production | https://dunning.kobana.com.br/api/v1 |
There is no public sandbox yet. To develop without firing real messages, use an account with no sending channels configured (sends are simulated) and Read-only keys wherever writing is not needed. The test environment's behavior is described in Sandbox (in preparation).
Conventions that apply across the API
- UTF-8 JSON, response fields in
camelCase. - Dates in ISO 8601 (UTC); date fields also accept
YYYY-MM-DD. - Monetary amounts: returned as decimal strings (
"1500.00"), accepted as numbers in requests. - Errors: a
{ message, code, details? }envelope with stable codes — the actual list is in Errors and codes.
In this section
- Practical examples — the end-to-end flow in
curl. - Errors and codes — every code the API returns.
- Postman and SDKs — a ready-made collection and client generation from the OpenAPI spec.