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, estructura organizacional) nunca es accesible vía API — responde 403.

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
integrations	list manage	integraciones de la cuenta

Administración de la cuenta

Miembros, roles, claves de API, workspaces, auditoría y configuración de la cuenta componen la administración de la cuenta. Esos recursos existen en el catálogo para los roles del dashboard, pero ninguna ruta de administración de la cuenta se expone en la API: una clave, incluso con el preset Total, recibe 403 al intentar alcanzarlos. La cuenta y los permisos se gestionan solo por el dashboard.

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.
• Revoca de inmediato cualquier clave expuesta — la revocación es instantánea.
• HTTPS obligatorio en todas las llamadas.