Saltar al contenido principal

Ejemplos prácticos

El flujo esencial de una integración, de punta a punta, en curl: registrar el cliente, crear el cobro y seguir el resto por webhooks. Exporta 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. Crear el cliente​

POST /people. Solo name es obligatorio; documento, contactos y dirección hacen el cobro mucho más eficaz (sin e-mail/teléfono no hay adónde la regla de cobranza pueda enviar mensajes):

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

La respuesta 201 trae el cliente creado; guarda el id. Un documento duplicado en la cuenta responde 409. El evento person.created se emite hacia los webhooks.

2. Crear el cobro​

POST /charges. Obligatorios: personId, originalAmount (positivo), issueDate y 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"
  }'

También puedes informar collectionRuleId para fijar el cobro a una regla de cobranza específica; sin él, aplican las reglas de enrollment automático de la cuenta. Campos como fineAmount, interestAmount, discountAmount, barcode y pixEmv completan el cuadro financiero.

Observa el X-Idempotency-Key: si la red se cae y repites el request con la misma clave, la API devuelve la respuesta original (header X-Idempotent-Replay: true) en vez de crear un cobro duplicado.

3. Seguimiento por webhooks​

En vez de hacer polling de GET /charges/{id}, registra un endpoint y deja que los eventos lleguen:

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

Guarda el secret de la respuesta (solo se muestra una vez) y verifica la firma de cada entrega. A partir de aquí tu sistema se entera de pagos, atrasos, acuerdos y disputas sin consultar nada.

4. Consultas útiles del día a día​

# Cobros vencidos, los más antiguos primero
curl -s "$BASE/charges?status=overdue&sort_by=due_date&sort_order=asc&per_page=50" \
  -H "$AUTH" -H "$UA"

# Cobros de un 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"

Los listados devuelven { data: [...], meta: { total, page, limit, totalPages } }; los filtros de cada recurso están en la Referencia de la API. Si algo falla, el envelope de error está descrito en Errores y códigos.