# 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.

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**

### Aditivo (Sigue siendo la v1)

Endpoints nuevos, familias enteras y campos opcionales nuevos, en la entrada o en la respuesta. Tu integración no tiene que tocar nada.

### Incompatible (Exigiría una versión mayor)

Retirar un endpoint o cambiar su ruta; retirar un campo o cambiar su tipo; hacer obligatorio un campo opcional; cambiar la forma de la paginación. Llegaría con aviso previo y un plan de migración.

> **Atención: 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](https://os.utilia.ai/docs/developers/changelog/integrations).

## 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](https://os.utilia.ai/docs/developers/sdk/versions).

## Cómo protegerte

1. **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.
2. **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.
3. **Vigila los cambios incompatibles**

   El registro de cambios marca cada cambio que te exige actuar, sea de contrato o de permisos.

## Siguiente paso

- [Cambios de las integraciones](https://os.utilia.ai/docs/developers/changelog/integrations): Historial de cambios de la API, los SDK y el widget.
- [Versiones y compatibilidad del SDK](https://os.utilia.ai/docs/developers/sdk/versions): Qué aportó cada versión y qué cambios exigen tocar tu código.