Guía del integrador

El camino del desarrollador que va a conectar el ERP, el sistema de facturación o el gateway a Dunning: clave, primera llamada, primer cliente y cobro, webhooks y reintentos seguros. Esta página es la ruta; los contratos completos viven en la Referencia de la API (generada del OpenAPI, nunca escrita a mano).

1. Crea la clave de API

En Configuración → Seguridad (solo administradores), crea una clave con:

• Nivel de acceso "Lectura y escritura" — cubre toda la operación de negocio sin exponer la administración de la cuenta. Los recursos administrativos responden 403 API_KEY_FORBIDDEN a cualquier clave: una clave filtrada no crea administradores ni otras claves.
• Expiración (30/90/365 días) con correos de aviso — la rotación periódica limita el daño de una filtración.

El token aparece una única vez; guárdalo en una bóveda de secretos. Detalles en Claves de API.

2. Primera llamada

Único ambiente público (el Sandbox está en preparación — para desarrollar sin riesgo mientras tanto, usa una cuenta sin canales de envío configurados: los envíos se simulan):

curl -s "https://dunning.kobana.com.br/api/v1/people?per_page=5" \
  -H "Authorization: Bearer $DUNNING_API_KEY" \
  -H "User-Agent: Mi Integracion <dev@miempresa.com>"

El User-Agent identificando tu integración es obligatorio y va al registro de auditoría.

3. Primer cliente y primer cobro

El flujo mínimo es POST /people seguido de POST /charges — los payloads completos y comentados están en Ejemplos prácticos. Lo que importa acertar desde el primer día:

• externalId en todo — el ID del registro en tu sistema. Es la clave de deduplicación: un documento duplicado responde 409, y las importaciones futuras actualizan en vez de duplicar.
• Contactos en el cliente — sin correo/teléfono, la regla no tiene adónde enviar.
• X-Idempotency-Key en toda mutación — ver el paso 5.
• Regla: informa collectionRuleId para fijar el cobro a una regla específica, u omítelo y deja que el enrolamiento automático ponga el cobro en la regla predeterminada.
• Datos de pago (pixEmv, paymentUrl, barcode) — los mensajes de la regla salen ya "pagables".

4. Webhooks en vez de polling

Registra un endpoint (POST /webhook-endpoints o por la pantalla Webhooks) y recibe los hechos de negocio como POST JSON: charge.paid, charge.overdue, agreement.accepted, dispute.created... Reglas del juego (visión general):

• La URL debe ser https://; el secret (whsec_) aparece una vez y firma cada entrega vía HMAC (X-Webhook-Signature) — verifícala siempre.
• Responde 2xx en hasta 10 segundos: encola y procesa después.
• La entrega es al menos-una-vez: deduplica por evento + data.id + timestamp. Las fallas entran al ciclo de reintentos con backoff, con cada intento capturado y reenvío manual disponible.

5. Idempotencia y reintentos

Toda mutación acepta X-Idempotency-Key (un UUID por operación de negocio). Si la red se cae y repites el request con la misma clave dentro de 24h, la API devuelve la respuesta original (X-Idempotent-Replay: true) en vez de duplicar la operación. Combínalo con la política de reintentos: backoff exponencial para 5xx, Retry-After para 429 RATE_LIMITED, y timeout de red tratado como 5xx — la idempotencia resuelve la ambigüedad de "¿se ejecutó o no?".

Las reglas de la casa, en una tabla

Tema	Resumen	Referencia
Autenticación	Authorization: Bearer <clave>; scopes dunning.dashboard.*	Autenticación
Formato	JSON UTF-8; respuestas en camelCase; fechas ISO 8601; montos como string decimal	Introducción
Paginación	page/per_page/sort_by/sort_order; filtros en snake_case	Paginación
Errores	Envelope { message, code, details? }; decide por el code	Errores y códigos
Retención	Claves de idempotencia 24h; auditoría append-only	Retención de datos
Spec y Postman	OpenAPI 3.1 en PT/EN/ES + colección lista	Especificaciones · Postman

Checklist del integrador

• Clave "Lectura y escritura" con expiración, guardada en bóveda.
• User-Agent y X-Idempotency-Key en producción desde el primer deploy.
• Webhook con verificación de firma y deduplicación; monitoreado en la pantalla de entregas.
• Reintentos con backoff + Retry-After; ningún loop inmediato.
• Conciliación por externalId en ambos sentidos (tu sistema ↔ Dunning).