Comienza aquí
Todo lo que el dashboard hace en la operación de cobro existe en la API v1: clientes, cobros, reglas de cobranza, acuerdos, disputas, tareas, importaciones, webhooks. Esta sección trae el camino práctico; los contratos completos están en la Referencia de la API, generada del OpenAPI (nunca escrita a mano).
No necesitas salir de la doc para probar: cada endpoint en la Referencia de la API tiene un botón Send API Request que dispara la llamada en vivo contra producción. Pega tu clave, completa los parámetros y ve la respuesta real al instante — sin Postman, sin curl, sin escribir código. Empieza con una clave de solo lectura para explorar sin riesgo.
En 3 pasos
1. Obtén un access token de la Cuenta Kobana — es la credencial de la API v1 (Authorization: Bearer <token>); el panel no emite credenciales. Detalles en Autenticación.
2. Haz la primera llamada:
curl -s "https://api.dunning.kobana.com.br/v1/people?per_page=5" \
-H "Authorization: Bearer $DUNNING_API_KEY" \
-H "User-Agent: Minha Integracao <dev@minhaempresa.com.br>"
3. Sigue el flujo completo en Ejemplos prácticos: crear cliente, crear cobro y seguir todo por webhooks.
Las reglas de la casa
Cada una tiene su propia página en la visión general de la referencia — léelas antes de ir a producción:
| Tema | Resumen en una línea |
|---|---|
| Autenticación | Authorization: Bearer <token> (access token de la Cuenta Kobana); scopes dunning/<recurso> + nivel de acceso (read, write, delete, import, export, all), uno por solicitud |
| User-Agent | Identifica tu integración en cada solicitud; va a la auditoría |
| Idempotencia | X-Idempotency-Key en las mutaciones; replay seguro por 24h |
| Paginación y filtros | page/per_page/sort_by/sort_order; filtros en snake_case |
| Rate limiting | 429 RATE_LIMITED por clave; reintenta con backoff |
| Especificaciones OpenAPI | Spec 3.1 en PT/EN/ES, importable en cualquier herramienta |
Entorno
Hay un único entorno público:
| Entorno | Base URL |
|---|---|
| Producción | https://api.dunning.kobana.com.br/v1 |
Todavía no existe un sandbox público. Para desarrollar sin disparar mensajes reales, usa una cuenta sin canales de envío configurados (los envíos se simulan) y claves de Solo lectura donde no se necesite escritura. El comportamiento del entorno de prueba está descrito en Sandbox (en preparación).
Convenciones que valen en toda la API
- JSON UTF-8, campos de respuesta en
camelCase. - Fechas en ISO 8601 (UTC); los campos de fecha también aceptan
YYYY-MM-DD. - Valores monetarios: se devuelven como string decimal (
"1500.00"), se aceptan como number en el request. - Errores: envelope
{ message, code, details? }con códigos estables — la lista real está en Errores y códigos.
En esta sección
- Ejemplos prácticos — el flujo de punta a punta en
curl. - Errores y códigos — todos los códigos que devuelve la API.
- Postman y SDKs — colección lista y generación de clientes a partir del OpenAPI.