Comece aqui
Tudo que o dashboard faz na operação de cobrança existe na API v1: clientes, cobranças, réguas, acordos, disputas, tarefas, importações, webhooks. Esta seção traz o caminho prático; os contratos completos estão na Referência da API, gerada do OpenAPI (nunca escrita à mão).
Você não precisa sair da doc para testar: cada endpoint na Referência da API tem um botão Send API Request que dispara a chamada ao vivo contra produção. Cole sua chave, preencha os parâmetros e veja a resposta real na hora — sem Postman, sem curl, sem escrever código. Comece com uma chave somente leitura para explorar sem risco.
Em 3 passos
1. Obtenha um access token da Conta Kobana — é a credencial da API v1 (Authorization: Bearer <token>); o painel não emite credenciais. Detalhes em Autenticação.
2. Faça a primeira chamada:
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. Siga o fluxo completo em Exemplos práticos: criar cliente, criar cobrança e acompanhar tudo por webhooks.
As regras da casa
Cada uma tem página própria na visão geral da referência — leia antes de ir para produção:
| Tema | Resumo de uma linha |
|---|---|
| Autenticação | Authorization: Bearer <token> (access token da Conta Kobana); escopos dunning/<recurso> + nível de acesso (read, write, delete, import, export, all), um por requisição |
| User-Agent | Identifique sua integração em toda requisição; vai para a auditoria |
| Idempotência | X-Idempotency-Key nas mutações; replay seguro por 24h |
| Paginação e filtros | page/per_page/sort_by/sort_order; filtros em snake_case |
| Rate limiting | 429 RATE_LIMITED por chave; re-tente com backoff |
| Especificações OpenAPI | Spec 3.1 em PT/EN/ES, importável em qualquer ferramenta |
Ambiente
Há um único ambiente público:
| Ambiente | Base URL |
|---|---|
| Produção | https://api.dunning.kobana.com.br/v1 |
Não existe sandbox público. Para desenvolver sem disparar mensagens reais, use uma conta sem canais de envio configurados (os envios são simulados) e chaves Somente leitura onde escrita não for necessária. O comportamento do ambiente de teste está descrito em Sandbox (em preparação).
Convenções que valem em toda a API
- JSON UTF-8, campos de resposta em
camelCase. - Datas em ISO 8601 (UTC); campos de data aceitam também
YYYY-MM-DD. - Valores monetários: retornados como string decimal (
"1500.00"), aceitos como number no request. - Erros: envelope
{ message, code, details? }com códigos estáveis — a lista real está em Erros e códigos.
Nesta seção
- Exemplos práticos — o fluxo ponta a ponta em
curl. - Erros e códigos — todos os códigos que a API devolve.
- Postman e SDKs — coleção pronta e geração de clientes a partir do OpenAPI.