Autenticación

Toda request lleva una clave de API. La API acepta dos headers equivalentes — usa el que prefieras:

Authorization: Bearer <tu-clave>

x-api-key: <tu-clave>

La clave nunca se almacena en claro de nuestro lado (solo su hash SHA-256) e identifica tu organización: todos los datos devueltos quedan automáticamente acotados a ella.

Creando claves

Crea claves en el panel en Configuración → Seguridad, con tres niveles de acceso:

• Total — toda la API.
• Lectura y escritura — toda la operación de cobranza, sin administración de la cuenta.
• Solo lectura — solo GET.

Los scopes siguen el catálogo dunning.dashboard.<recurso>.<acción>; una clave sin scopes tiene acceso total al negocio. La clave se muestra una única vez al crearla — cópiala y guárdala en un lugar seguro.

Las claves pueden tener expiración (30/90/365 días) con aviso por correo antes del vencimiento. La administración de la cuenta (miembros, roles, claves, configuración) nunca es accesible vía API — responde 403.

Las claves también pueden rotarse: la rotación crea una clave sucesora con el mismo nombre, scopes y política de validez (token mostrado una única vez, como al crearla) y adelanta la expiración de la antigua al final de una ventana de gracia — 7 días por defecto, configurable de 0 a 30 (con 0, la antigua se corta al instante). Cambia el secret en tus integraciones dentro de esa ventana; después, la clave antigua responde 401. El ciclo de vida de las claves (rotación, cambio de estado, revocación) se publica en los eventos de webhook api_key.*.

Scopes

Cada scope es dunning.dashboard.<recurso>.<acción>. Se aceptan wildcards: dunning.dashboard.charges.* (todas las acciones de cobros) o dunning.dashboard.* (todo).

Presets

Al crear la clave eliges un preset; los tres derivan del mismo catálogo:

Preset	Cubre	Uso típico
Solo lectura	acciones list/show/view de todos los recursos	espejar datos, BI, dashboards — nunca altera nada
Lectura y escritura	toda la operación de cobranza (todos los recursos, menos administración de la cuenta)	integraciones ERP/CRM que crean y actualizan clientes, cobros, acuerdos...
Total	dunning.dashboard.*	todo lo que una clave puede alcanzar

Una clave creada sin scopes equivale a "Lectura y escritura" (acceso total al negocio). También puedes armar un conjunto a medida eligiendo scopes individuales del catálogo de abajo.

Catálogo de recursos

Recurso	Acciones	Qué permite
dashboard	view	leer los indicadores del panel
people	list show create update delete	cartera de clientes/deudores
charges	list show create update delete notify	cobros y disparo manual de notificación
collection_rules	list show create update delete activate	reglas de cobranza y su activación
classifications	list show create update delete	clasificaciones/tags de la cartera
templates	list show create update delete duplicate	plantillas de mensaje
notifications	list show create update resend delete	notificaciones y reenvío
tasks	list show create update delete complete	tareas de la operación
interactions	list show create update delete	interacciones/historial de contacto
agreements	list show create update cancel	acuerdos de pago
disputes	list show create resolve	disputas y su resolución
negativations	list show create approve cancel	negativación en bureau
protests	list show create approve cancel	protesto en notaría
portal	generate_link revoke_link	links del portal del deudor
webhooks	list show create update delete	endpoints de webhook
email_layouts	list show create update delete	layouts de correo
imports	list show create	importaciones por lote
exports	create	exportaciones de datos
companies	list manage	empresas y sucursales de la cuenta (manage está vedado a claves — ver abajo)
integrations	list manage	integraciones de la cuenta (manage está vedado a claves — mira abajo)
audit	list show	historial de auditoría (solo lectura)

Administración de la cuenta

Miembros, roles, claves de API y configuración de la cuenta componen la administración de la cuenta: una clave, incluso con el preset Total, recibe 403 (API_KEY_FORBIDDEN) al intentar alcanzarlos. La cuenta y los permisos se gestionan solo por el dashboard. Empresas/sucursales (companies) e integraciones tienen la lectura habilitada para claves, pero la acción de configuración (manage) está igualmente vedada. El historial de auditoría (GET /api/v1/audit-logs) es de solo lectura y accesible vía API.

Request válida

export DUNNING_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

curl -i \
  -H "Authorization: Bearer $DUNNING_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mi Integración <dev@miempresa.com>' \
  -X GET 'https://api.dunning.kobana.com.br/api/v1/charges?per_page=1'

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599

{
  "data": [
    {
      "id": "cmd8k2p4x0001ab3f",
      "status": "overdue",
      "amount": "1500.00",
      "dueDate": "2026-07-10T00:00:00.000Z",
      ...
    }
  ],
  "meta": { "total": 142, "page": 1, "limit": 1, "totalPages": 142 }
}

Request inválida

Una clave ausente, malformada, revocada o expirada responde 401 con el envelope de error estándar:

curl -i \
  -H "Authorization: Bearer clave-invalida" \
  -X GET 'https://api.dunning.kobana.com.br/api/v1/charges'

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Não autorizado",
  "code": "UNAUTHORIZED"
}

Una clave válida sin el scope necesario responde 403 con code: "FORBIDDEN" (o API_KEY_FORBIDDEN) y el campo required indicando el permiso que faltó.

Buenas prácticas

• Nunca versiones claves en git. Usa variables de entorno o bóvedas de secretos (Vault, AWS Secrets Manager...).
• Usa una clave por integración (ERP, CRM, BI...) — revocar una no tumba las demás, y la auditoría queda legible.
• Prefiere el menor nivel de acceso que resuelva: las integraciones de lectura no necesitan escritura.
• Define expiración siempre que sea posible; el aviso por correo llega antes del vencimiento.
• Rota periódicamente: la ventana de gracia de la rotación permite cambiar el secret sin downtime; suscríbete a los eventos api_key.* para seguirlo.
• Revoca de inmediato cualquier clave expuesta — la revocación es instantánea (sin ventana de gracia).
• HTTPS obligatorio en todas las llamadas.