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. Get a Kobana Account access token — it is the API v1 credential (Authorization: Bearer <token>); the panel does not issue credentials. Details in Authentication.
2. Make the first call:
curl -s "https://api.dunning.kobana.com.br/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 <token> (Kobana Account access token); scopes dunning/<resource> + access level (read, write, delete, import, export, all), one per request |
| 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://api.dunning.kobana.com.br/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.