Versionado y deprecación

La API se versiona en la URL: todos los endpoints viven bajo /v1/. Nuestro compromiso es que tu integración no se rompa de un día para otro.

Qué es y qué no es un breaking change

Dentro de una versión (/v1) solo hacemos cambios aditivos — nunca rompemos lo existente:

Cambios compatibles (pueden ocurrir en cualquier momento, sin aviso):

Agregar un endpoint nuevo.
Agregar un campo nuevo a una respuesta.
Agregar un parámetro opcional a una petición.
Agregar un valor nuevo a un enum o un tipo de evento de webhook.

Diseña tu integración para tolerar campos desconocidos: ignora los que no esperas en lugar de fallar. Así los cambios aditivos nunca te afectan.

Cambios incompatibles (NO ocurren dentro de /v1):

Quitar o renombrar un campo, endpoint o parámetro.
Cambiar el tipo o el significado de un campo.
Volver requerido un parámetro antes opcional.

Si algún día un cambio incompatible es realmente necesario, no se aplica sobre /v1: se publica en una versión nueva (/v2) y /v1 se deprecia de forma ordenada.

Cómo deprecamos

Cuando un endpoint o versión entra en deprecación:

Te avisamos con antelación (correo + estos docs).
La versión vieja sigue funcionando durante un período mínimo de coexistencia de 60 días.
Las respuestas del endpoint deprecado incluyen headers estándar para que lo detectes automáticamente:


Deprecation: true
Sunset: Tue, 15 Sep 2026 00:00:00 GMT
Link: </v2/...>; rel="successor-version"

Header	Significado
`Deprecation`	El endpoint está deprecado.
`Sunset`	Fecha a partir de la cual dejará de funcionar.
`Link` (`rel="successor-version"`)	A dónde migrar.

Vigila el header Deprecation en tus respuestas (o suscríbete a nuestros avisos): es la señal para planificar la migración antes de la fecha de Sunset.

Recomendaciones

Fija la versión (/v1) explícitamente en tus llamadas; no asumas “la última”.
Registra en tus logs si ves un header Deprecation — así te enteras temprano.
Mantén tu correo de contacto al día en el dashboard para recibir los avisos.