Guia do integrador

O caminho do desenvolvedor que vai ligar o ERP, o sistema de faturamento ou o gateway ao Dunning: chave, primeira chamada, primeiro cliente e cobrança, webhooks e retries seguros. Esta página é a rota; os contratos completos vivem na Referência da API (gerada do OpenAPI, nunca escrita à mão).

1. Crie a chave de API

Em Configurações → Segurança (apenas administradores), crie uma chave com:

• Nível de acesso "Leitura e escrita" — cobre toda a operação de negócio sem expor administração da conta. Recursos administrativos respondem 403 API_KEY_FORBIDDEN para qualquer chave: uma chave vazada não cria administradores nem outras chaves.
• Expiração (30/90/365 dias) com e-mails de aviso — rotação periódica limita o estrago de um vazamento.

O token aparece uma única vez; guarde-o num cofre de segredos. Detalhes em Chaves de API.

2. Primeira chamada

Único ambiente público (o Sandbox está em preparação — para desenvolver sem risco enquanto isso, use uma conta sem canais de envio configurados: os envios são simulados):

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>"

O User-Agent identificando a integração é obrigatório e vai para a auditoria.

3. Primeiro cliente e primeira cobrança

O fluxo mínimo é POST /people seguido de POST /charges — os payloads completos, comentados, estão em Exemplos práticos. O que importa acertar desde o primeiro dia:

• externalId em tudo — o ID do registro no seu sistema. É a chave de deduplicação: documento duplicado responde 409, e importações futuras atualizam em vez de duplicar.
• Contatos no cliente — sem e-mail/telefone, a régua não tem para onde enviar.
• X-Idempotency-Key em toda mutação — veja o passo 5.
• Régua: informe collectionRuleId para prender a cobrança a uma régua específica, ou omita e deixe o enrollment automático colocar a cobrança na régua padrão.
• Dados de pagamento (pixEmv, paymentUrl, barcode) — as mensagens da régua já saem "pagáveis".

4. Webhooks em vez de polling

Cadastre um endpoint (POST /webhook-endpoints ou pela tela Webhooks) e receba os fatos de negócio como POST JSON: charge.paid, charge.overdue, agreement.accepted, dispute.created... Regras do jogo (visão geral):

• URL obrigatoriamente https://; o secret (whsec_) aparece uma vez e assina cada entrega via HMAC (X-Webhook-Signature) — verifique sempre.
• Responda 2xx em até 10 segundos: enfileire e processe depois.
• Entrega é pelo menos-uma-vez: deduplique pelo par evento + data.id + timestamp. Falhas entram no retry com backoff, com toda tentativa capturada e re-envio manual.

5. Idempotência e retries

Toda mutação aceita X-Idempotency-Key (um UUID por operação de negócio). Se a rede cair e você repetir o request com a mesma chave em até 24h, a API devolve a resposta original (X-Idempotent-Replay: true) em vez de duplicar a operação. Combine com a política de retry: backoff exponencial para 5xx, Retry-After para 429 RATE_LIMITED, e timeout de rede tratado como 5xx — a idempotência resolve a ambiguidade de "executou ou não?".

As regras da casa, em uma tabela

Tema	Resumo	Referência
Autenticação	Authorization: Bearer <chave>; escopos dunning.dashboard.*	Autenticação
Formato	JSON UTF-8; respostas em camelCase; datas ISO 8601; valores monetários como string decimal	Introdução
Paginação	page/per_page/sort_by/sort_order; filtros em snake_case	Paginação
Erros	Envelope { message, code, details? }; trate pelo code	Erros e códigos
Retenção	Chaves de idempotência 24h; auditoria append-only	Retenção de dados
Spec e Postman	OpenAPI 3.1 em PT/EN/ES + coleção pronta	Especificações · Postman

Checklist do integrador

• Chave "Leitura e escrita" com expiração, guardada em cofre.
• User-Agent e X-Idempotency-Key em produção desde o primeiro deploy.
• Webhook com verificação de assinatura e deduplicação; monitorado na tela de entregas.
• Retry com backoff + Retry-After; nenhum loop imediato.
• Conciliação por externalId nos dois sentidos (seu sistema ↔ Dunning).