Saltar al contenido principal

Changelog de la API

Historial del contrato de la API v1 de la Regla de Cobranza: lo que existe hoy y cómo los cambios futuros se versionarán y comunicarán. Los cambios de endpoints, campos y comportamiento aparecen aquí en orden cronológico inverso (más reciente primero).

La fuente canónica del contrato es siempre la especificación OpenAPI 3.1 (/openapi/openapi-v1-pt.yaml y las variantes -en/-es). Este changelog resume lo que cambia entre versiones; el YAML tiene el detalle campo por campo.

Agosto de 2026​

Cambios aditivos, dentro de la garantía de compatibilidad:

  • customData con límites documentados y merge opt-in. El campo de datos personalizados de los recursos núcleo (people, charges, agreements, tasks, interactions) pasa a validar límites explícitos — payload serializado de hasta 64 KB, 16 niveles de anidamiento y rechazo de las claves __proto__/constructor/prototype (las violaciones responden 400 VALIDATION_ERROR). En los updates de esos recursos, el nuevo campo opcional customDataMode (replace | merge) permite mezclar el payload sobre el valor almacenado en lugar de sustituirlo; el default sigue siendo replace (comportamiento histórico). Las disputas aceptan customMetadata en la creación, con los mismos límites. Mira Campos personalizados.
  • Eventos de webhook del ciclo de vida de claves de API. Nueva categoría api_key.* en el catálogo: api_key.rotated, api_key.status_changed y api_key.revoked — el payload trae el shape público de la clave (nunca el token ni el hash).

v1.0 — Julio de 2026​

Lanzamiento público de la API v1. Baseline del contrato, con cobertura programática de toda la operación de cobranza que existe en el dashboard:

  • Cartera — clientes/deudores (people), clasificaciones e interacciones de contacto.
  • Cobros — creación, actualización, consulta y disparo manual de notificación (charges).
  • Regla de cobranza — reglas multicanal (collection_rules), plantillas de mensaje (templates) y layouts de correo.
  • Acuerdos y disputas — acuerdos de pago (agreements) y disputas (disputes).
  • Negativación y protesto — registro en bureau (negativations) y notaría (protests).
  • Operación — tareas (tasks), notificaciones (notifications), importaciones por lote y exportaciones.
  • Portal del deudor — generación y revocación de links.
  • Webhooks — endpoints firmados (HMAC-SHA256), entrega en cola con reintento exponencial y pista de entregas.

Convenciones fijadas en el baseline y cubiertas por la garantía de compatibilidad de abajo:

  • Envelope de error estable { message, code, details? } — decide siempre por el code.
  • Respuestas en camelCase, fechas en ISO 8601 (UTC), valores monetarios como string decimal.
  • Autenticación por clave de API con scopes dunning.dashboard.<recurso>.<acción> (ver Autenticación).
  • Idempotencia vía X-Idempotency-Key, paginación page/per_page y rate limiting por clave.

Política de versionado​

La API se versiona en la ruta (/api/v1). Mientras la versión mayor no cambie, el contrato solo evoluciona de forma retrocompatible.

Cambios retrocompatibles (pueden ocurrir en cualquier momento, sin nueva versión)​

Tu integración debe tolerarlos sin romperse:

  • Nuevos endpoints y nuevos recursos.
  • Nuevos campos opcionales en respuestas — ignora los que no conozcas (no hagas strict parsing que rechace campos extra).
  • Nuevos valores en enums y nuevos code de error — maneja valores desconocidos con un fallback.
  • Nuevos parámetros de query opcionales y nuevos headers de respuesta.
  • Nuevos tipos de evento de webhook — suscríbete solo a los que manejas e ignora el resto.

Cambios que rompen (exigen una nueva versión mayor, ej.: /api/v2)​

Nunca se aplican silenciosamente a la v1:

  • Eliminar o renombrar endpoints, campos o code de error.
  • Cambiar el tipo o el significado de un campo existente.
  • Hacer obligatorio un parámetro antes opcional.
  • Endurecer reglas de validación de modo que un request antes válido empiece a fallar.

Cómo se comunican los cambios​

  • Los cambios aditivos entran en la especificación OpenAPI y quedan registrados en este changelog, con fecha.
  • Las depreciaciones se anuncian aquí y en el changelog con antelación, manteniendo el comportamiento antiguo en funcionamiento durante el período de transición antes de cualquier eliminación (que solo ocurre en una nueva versión mayor).
  • Recomendamos seguir esta página y suscribirte a los webhooks para reaccionar a nuevos eventos.