Skip to main content

Practical examples

The essential flow of an integration, end to end, in curl: register the customer, create the charge and track the rest through webhooks. Export first:

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. Create the customer​

POST /people. Only name is required; document, contacts and address make collection much more effective (without an email/phone there is nowhere for the collection rule to send messages):

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"]
  }'

The 201 response carries the created customer; keep the id. A duplicate document in the account responds 409. The person.created event is emitted to the webhooks.

2. Create the charge​

POST /charges. Required: personId, originalAmount (positive), issueDate and 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"
  }'

You can also pass collectionRuleId to pin the charge to a specific collection rule; without it, the account's automatic enrollment rules apply. Fields like fineAmount, interestAmount, discountAmount, barcode and pixEmv complete the financial picture.

Note the X-Idempotency-Key: if the network drops and you repeat the request with the same key, the API returns the original response (X-Idempotent-Replay: true header) instead of creating a duplicate charge.

3. Track through webhooks​

Instead of polling GET /charges/{id}, register an endpoint and let the events come to you:

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"]
  }'

Keep the secret from the response (it appears only once) and verify the signature of every delivery. From here on, your system learns about payments, late charges, agreements and disputes without polling anything.

4. Useful day-to-day queries​

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

Listings return { data: [...], meta: { total, page, limit, totalPages } }; each resource's filters are in the API Reference. If something fails, the error envelope is described in Errors and codes.