Exemplos práticos

O fluxo essencial de uma integração, ponta a ponta, em curl: cadastrar o cliente, criar a cobrança e acompanhar o resto por webhooks. Exporte antes:

export BASE="https://dunning.kobana.com.br/api/v1"
export AUTH="Authorization: Bearer $DUNNING_API_KEY"
export UA="User-Agent: Minha Integracao <dev@minhaempresa.com.br>"

1. Criar o cliente

POST /people. Só name é obrigatório; documento, contatos e endereço deixam a cobrança muito mais eficaz (sem e-mail/telefone não há para onde a régua mandar mensagem):

curl -s -X POST "$BASE/people" \
  -H "$AUTH" -H "$UA" -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Maria Oliveira",
    "kind": "natural",
    "documentType": "cpf",
    "documentNumber": "12345678900",
    "emails": [{ "label": "personal", "address": "maria@example.com" }],
    "phones": [{ "kind": "whatsapp", "countryCode": "55", "areaCode": "11", "number": "987654321" }],
    "externalId": "cliente-123-no-meu-erp",
    "tags": ["plano-anual"]
  }'

A resposta 201 traz o cliente criado; guarde o id. Documento duplicado na conta responde 409. O evento person.created é emitido para os webhooks.

2. Criar a cobrança

POST /charges. Obrigatórios: personId, originalAmount (positivo), issueDate e dueDate:

curl -s -X POST "$BASE/charges" \
  -H "$AUTH" -H "$UA" -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "personId": "<id-do-passo-1>",
    "description": "Mensalidade julho/2026",
    "originalAmount": 1500.00,
    "issueDate": "2026-07-01",
    "dueDate": "2026-07-25",
    "documentNumber": "NF-4321",
    "externalId": "fatura-987-no-meu-erp",
    "paymentUrl": "https://pagamentos.minhaempresa.com.br/fatura-987"
  }'

Você também pode informar collectionRuleId para prender a cobrança a uma régua específica; sem ele, valem as regras de enrollment automático da conta. Campos como fineAmount, interestAmount, discountAmount, barcode e pixEmv completam o quadro financeiro.

Repare no X-Idempotency-Key: se a rede cair e você repetir o request com a mesma chave, a API devolve a resposta original (header X-Idempotent-Replay: true) em vez de criar cobrança duplicada.

3. Acompanhar por webhooks

Em vez de fazer polling de GET /charges/{id}, cadastre um endpoint e deixe os eventos chegarem:

curl -s -X POST "$BASE/webhook-endpoints" \
  -H "$AUTH" -H "$UA" -H "Content-Type: application/json" \
  -d '{
    "url": "https://minhaempresa.com.br/webhooks/dunning",
    "description": "Conciliacao do ERP",
    "events": ["charge.paid", "charge.overdue", "agreement.accepted", "dispute.created"]
  }'

Guarde o secret da resposta (só aparece uma vez) e verifique a assinatura de cada entrega. A partir daqui o seu sistema fica sabendo de pagamento, atraso, acordo e disputa sem consultar nada.

4. Consultas úteis no dia a dia

# Cobrancas vencidas, mais antigas primeiro
curl -s "$BASE/charges?status=overdue&sort_by=due_date&sort_order=asc&per_page=50" \
  -H "$AUTH" -H "$UA"

# Cobrancas de um cliente
curl -s "$BASE/charges?person_id=<id>" -H "$AUTH" -H "$UA"

# Buscar cliente por documento
curl -s "$BASE/people?search=12345678900" -H "$AUTH" -H "$UA"

Listagens devolvem { data: [...], meta: { total, page, limit, totalPages } }; filtros de cada recurso estão na Referência da API. Se algo falhar, o envelope de erro está descrito em Erros e códigos.