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. Crie uma chave de API em Configurações → Segurança (precisa ser administrador). Escolha o nível de acesso — para integrações, "Leitura e escrita" cobre toda a operação sem expor a administração da conta — e copie o token, que só aparece uma vez. Detalhes em Chaves de API.
2. Faça a primeira chamada:
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. 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 <chave>; escopos no catálogo dunning.dashboard.* |
| 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://dunning.kobana.com.br/api/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.