Autenticação

Toda requisição leva uma chave de API. A API aceita dois headers equivalentes — use o que preferir:

Authorization: Bearer <sua-chave>

x-api-key: <sua-chave>

A chave nunca é armazenada em claro no nosso lado (apenas o hash SHA-256) e identifica a sua organização: todos os dados retornados são automaticamente escopados a ela.

Criando chaves

Crie chaves no dashboard em Configurações → Segurança, com três níveis de acesso:

• Total — toda a API.
• Leitura e escrita — toda a operação de cobrança, sem administração da conta.
• Somente leitura — apenas GET.

Os escopos seguem o catálogo dunning.dashboard.<recurso>.<ação>; chave sem escopos tem acesso total ao negócio. A chave é exibida uma única vez na criação — copie e guarde em local seguro.

Chaves podem ter expiração (30/90/365 dias) com aviso por e-mail antes do vencimento. Administração da conta (membros, roles, chaves, configurações) nunca é acessível via API — responde 403.

Chaves também podem ser rotacionadas: a rotação cria uma chave sucessora com os mesmos nome, escopos e política de validade (token exibido uma única vez, como na criação) e antecipa a expiração da antiga para o fim de uma janela de carência — 7 dias por padrão, configurável de 0 a 30 (com 0, a antiga é cortada na hora). Troque o secret nas suas integrações dentro dessa janela; depois dela, a chave antiga responde 401. O ciclo de vida das chaves (rotação, mudança de status, revogação) é publicado nos eventos de webhook api_key.*.

Escopos

Cada escopo é dunning.dashboard.<recurso>.<ação>. Wildcards são aceitos: dunning.dashboard.charges.* (todas as ações de cobranças) ou dunning.dashboard.* (tudo).

Presets

Ao criar a chave você escolhe um preset; os três derivam do mesmo catálogo:

Preset	Cobre	Uso típico
Somente leitura	ações list/show/view de todos os recursos	espelhar dados, BI, dashboards — nunca altera nada
Leitura e escrita	toda a operação de cobrança (todos os recursos, menos administração da conta)	integrações ERP/CRM que criam e atualizam clientes, cobranças, acordos...
Total	dunning.dashboard.*	tudo que uma chave pode alcançar

Uma chave criada sem escopos equivale a "Leitura e escrita" (acesso total ao negócio). Você também pode montar um conjunto sob medida escolhendo escopos individuais do catálogo abaixo.

Catálogo de recursos

Recurso	Ações	O que permite
dashboard	view	ler os indicadores do painel
people	list show create update delete	carteira de clientes/devedores
charges	list show create update delete notify	cobranças e disparo manual de notificação
collection_rules	list show create update delete activate	réguas de cobrança e sua ativação
classifications	list show create update delete	classificações/tags da carteira
templates	list show create update delete duplicate	modelos de mensagem
notifications	list show create update resend delete	notificações e reenvio
tasks	list show create update delete complete	tarefas da operação
interactions	list show create update delete	interações/histórico de contato
agreements	list show create update cancel	acordos de pagamento
disputes	list show create resolve	disputas e sua resolução
negativations	list show create approve cancel	negativação em bureau
protests	list show create approve cancel	protesto em cartório
portal	generate_link revoke_link	links do portal do devedor
webhooks	list show create update delete	endpoints de webhook
email_layouts	list show create update delete	layouts de e-mail
imports	list show create	importações em lote
exports	create	exportações de dados
companies	list manage	empresas e filiais da conta (manage é vedado a chaves — ver abaixo)
integrations	list manage	integrações da conta (manage é vedado a chaves — ver abaixo)
audit	list show	trilha de auditoria (somente leitura)

Administração da conta

Membros, papéis (roles), chaves de API e configurações da conta compõem a administração da conta: uma chave, mesmo com o preset Total, recebe 403 (API_KEY_FORBIDDEN) ao tentar alcançá-los. Conta e permissões se gerenciam apenas pelo dashboard. Empresas/filiais (companies) e integrações têm a leitura liberada para chaves, mas a ação de configuração (manage) é igualmente vedada. A trilha de auditoria (GET /api/v1/audit-logs) é somente leitura e acessível via API.

Requisição válida

export DUNNING_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

curl -i \
  -H "Authorization: Bearer $DUNNING_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Minha Integração <dev@minhaempresa.com.br>' \
  -X GET 'https://api.dunning.kobana.com.br/api/v1/charges?per_page=1'

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599

{
  "data": [
    {
      "id": "cmd8k2p4x0001ab3f",
      "status": "overdue",
      "amount": "1500.00",
      "dueDate": "2026-07-10T00:00:00.000Z",
      ...
    }
  ],
  "meta": { "total": 142, "page": 1, "limit": 1, "totalPages": 142 }
}

Requisição inválida

Chave ausente, malformada, revogada ou expirada responde 401 com o envelope de erro padrão:

curl -i \
  -H "Authorization: Bearer chave-invalida" \
  -X GET 'https://api.dunning.kobana.com.br/api/v1/charges'

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Não autorizado",
  "code": "UNAUTHORIZED"
}

Chave válida sem o escopo necessário responde 403 com code: "FORBIDDEN" (ou API_KEY_FORBIDDEN) e o campo required indicando a permissão que faltou.

Boas práticas

• Nunca versione chaves em git. Use variáveis de ambiente ou cofres de segredo (Vault, AWS Secrets Manager...).
• Use uma chave por integração (ERP, CRM, BI...) — revogar uma não derruba as outras, e a auditoria fica legível.
• Prefira o menor nível de acesso que resolve: integrações de leitura não precisam de escrita.
• Defina expiração sempre que possível; o aviso por e-mail chega antes do vencimento.
• Rotacione periodicamente: a janela de carência da rotação permite trocar o secret sem downtime; assine os eventos api_key.* para acompanhar.
• Revogue imediatamente qualquer chave exposta — a revogação é instantânea (sem carência).
• HTTPS obrigatório em todas as chamadas.