Versionado de la API externa
Qué versión de la API externa está publicada, cómo crece, qué cambios se consideran incompatibles y por qué el versionado del SDK es otra cosa.
Actualizado el . 2 min de lectura
La versión pública vigente de la API externa es v1, servida en /api/external/v1, y es la única. Esta página explica cómo cambia sin romper tu integración y qué tienes que vigilar.
Qué cambia sin versión nueva y qué no
La v1 crece de forma aditiva: lo que ya funcionaba sigue funcionando. El programa de facturación del 5 de septiembre de 2026, por ejemplo, añadió tres familias completas (suscripciones, autorizaciones de cobro y cobros programados) y cinco acciones sobre la factura sin cambiar la versión.
Dos clases de cambio
Sigue siendo la v1
Aditivo
Exigiría una versión mayor
Incompatible
Exigir un permiso nuevo no cambia la versión, pero sí puede romper tu integración
Un endpoint que empieza a exigir un permiso que antes no pedía sigue siendo el mismo endpoint con el mismo contrato: lo que cambia es la autorización. No dispara una versión nueva de la API, pero tu integración deja de funcionar hasta que alguien conceda el permiso a la aplicación.
Ocurrió el 5 de septiembre de 2026 con POST /external/v1/users/identify, que
pasó a exigir crm:users:write. Vigila los cambios marcados como incompatibles en
Cambios de las integraciones.
El versionado del SDK es otra cosa
Los SDK tienen su propio versionado semántico y no están atados a la versión de la API. Por ejemplo, la 3.0.0 fue una versión mayor porque cambió firmas de métodos, no porque la API cambiara de versión: lo que hizo fue apuntar a rutas de la v1 que antes no existían. La tabla de cambios incompatibles está en Versiones y compatibilidad del SDK.
Cómo protegerte
Trata las respuestas como contratos que crecen
Ignora los campos que no conozcas en lugar de fallar. Un campo nuevo en una respuesta puede aparecer en cualquier momento sin cambio de versión.
Fija la versión del SDK
Instala una versión exacta y actualiza a propósito, después de leer los cambios. Las versiones mayores cambian firmas.
Vigila los cambios incompatibles
El registro de cambios marca cada cambio que te exige actuar, sea de contrato o de permisos.