Introducción

La API v1 de la Regla de Cobranza expone programáticamente todo lo que el panel hace en la operación de cobranza: clientes, cobros, reglas de cobranza, acuerdos, disputas, tareas, importaciones y webhooks.

Para agentes de IA

Esta documentación está optimizada para LLMs: el índice completo en Markdown está en /llms.txt y el contrato de la API en /openapi/openapi-v1-es.yaml (variantes -pt y -en en el mismo directorio). Prefiere esas fuentes antes que raspar el HTML.

Formato

La API acepta y devuelve solo JSON (UTF-8). Envía Content-Type: application/json en toda request con body.

Tipo de campo	Formato
Campos	camelCase en las respuestas y en los bodies de request (dueDate, documentNumber)
Fechas	ISO 8601 en UTC. Ej.: 2026-07-23T12:00:00.000Z
Montos monetarios	Se devuelven como string decimal ("1500.00") para no perder precisión; se aceptan como number en las requests
Filtros de listado	Query string en snake_case (due_date_from, person_id) — mira Paginación y filtros

Convenciones

Convención	Descripción
:id	Variable de ruta que debe reemplazarse en la URL.
...	Contenido de la respuesta truncado para facilitar la lectura.
$DUNNING_TOKEN	Tu clave de API. Para probar en línea de comandos, expórtala: export DUNNING_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx y pega los comandos de la documentación en la terminal.

Envelope de error

Todo error responde con un envelope estable — message legible para humanos, code estable para máquinas (y, cuando es útil, details):

{
  "message": "Permissão insuficiente",
  "code": "FORBIDDEN"
}

Decide siempre por el code (VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, IDEMPOTENCY_KEY_REUSED, RATE_LIMITED, INTERNAL_ERROR...) — el texto de message puede cambiar sin aviso.

Códigos de retorno

La API usa los códigos HTTP estándar:

	Código	Descripción
✅	200 OK	Request exitosa con cuerpo de respuesta.
✅	201 Created	Recurso creado con éxito.
✅	204 No Content	Request exitosa, sin cuerpo de respuesta.
❌	400 Bad Request	Request malformada — JSON inválido, header de idempotencia inválido.
❌	401 Unauthorized	Clave de API ausente, inválida, revocada o expirada.
❌	403 Forbidden	Clave sin el scope necesario, o recurso administrativo inaccesible vía API.
❌	404 Not Found	Recurso o ruta inexistente (o perteneciente a otra organización).
❌	409 Conflict	Conflicto de estado — reuso de X-Idempotency-Key, transición inválida.
❌	422 Unprocessable Entity	Request bien formada, pero los datos no pasan la validación de negocio.
❌	429 Too Many Requests	Límite de requests excedido — espera el Retry-After.
❌	5xx	Error en el servidor — mira abajo cómo reintentar.

Errores 5xx y reintentos

500, 502, 503 y 504 indican una falla de nuestro lado, casi siempre transitoria. Tu integración debe:

1. Reintentar con backoff exponencial (ej.: 1s, 2s, 4s, 8s...) y un tope de intentos — nunca en loop inmediato.
2. Usar X-Idempotency-Key en las mutaciones — el reintento devuelve la respuesta original en vez de duplicar la operación.
3. Tratar el timeout de red como 5xx: no recibir respuesta no significa que la operación no se ejecutó; la idempotencia resuelve la ambigüedad.

En 429, espera la cantidad de segundos del header Retry-After antes del próximo intento.

Próximos pasos

• Autenticación — claves de API y scopes.
• Endpoints — ambientes y URLs base.
• Especificaciones OpenAPI — el contrato completo en OpenAPI 3.1.
• Rate limiting — límites y headers de respuesta.
• Paginación y filtros — listados e iteración.
• Idempotencia — reintentos seguros en mutaciones.
• Webhooks — eventos en tiempo real, sin polling.