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

Campos personalizados (customData)

Los recursos principales (clientes, cobros, acuerdos, tareas, interacciones) aceptan un objeto JSON libre en el campo customData, para guardar tus propios datos junto al recurso (IDs de tu ERP, flags internas...). En disputas, el campo equivalente se llama customMetadata. Límites, iguales en todos:

• 64 KB de payload serializado, como máximo;
• 16 niveles de anidamiento, como máximo;
• las claves __proto__, constructor y prototype se rechazan.

Las violaciones responden 400 con code: "VALIDATION_ERROR" y el motivo en details. En el update, el comportamiento por defecto es replace: el objeto enviado sustituye por completo al almacenado (y null limpia el campo). Para mezclar en lugar de sustituir, envía customDataMode: "merge" en el body del update — los objetos anidados se mezclan en profundidad; escalares, arrays y null sobrescriben la clave.

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.