Versiones y retirada de la API

Te pedimos que apuntes tus propios scripts, integraciones y librerías cliente de Zendesk a HelpFalcon. Esta página es la promesa que va con eso: qué podemos cambiar, qué no y con cuánta antelación te avisamos. Cubre la API REST en /api, la API compatible con Zendesk en /zd/api/v2 y el contrato de los webhooks. Cada cambio queda en el registro de cambios de la API.

La versión corta

Aviso antes de retirar nada	12 meses
Versiones de la API REST	Ninguna en la URL: /api solo crece
Número de versión	info.version en openapi.json, semántico
API compatible con Zendesk	Congelada en las formas documentadas de Zendesk
Webhooks	Entero version en el payload, fijado por webhook
Cómo se anuncia una retirada	Registro de cambios, cabeceras Deprecation y Sunset, deprecated en el documento OpenAPI, correo

Una API REST viva, solo aditiva

/api no tiene versión en la URL y no la tendrá. En su lugar, la ampliamos:

• endpoints nuevos,
• parámetros opcionales nuevos en la consulta y en el cuerpo,
• campos nuevos en las respuestas.

Escribe tu cliente para que ignore los campos que no conoce, y los campos nuevos nunca serán un problema. A cambio, nunca eliminamos un campo, nunca cambiamos su tipo sobre la marcha y nunca hacemos obligatorio un parámetro existente.

La versión que puedes citar en un informe de error es info.version del documento OpenAPI. Es semántica: el número de parche sube con las correcciones, el menor con las ampliaciones y el mayor solo junto con la regla de abajo.

Si algo tiene que romperse

Un cambio incompatible sale junto a la forma antigua, nunca en su lugar. La forma nueva aparece como un campo nuevo o en una ruta nueva solo para los recursos afectados (/api/v2/<resource>), y la antigua sigue funcionando durante todo el periodo de aviso indicado abajo. No usamos una cabecera de versión por fecha: multiplica los comportamientos por endpoint, y nuestras librerías cliente generadas fijan rutas, no cabeceras.

La API compatible con Zendesk está congelada

/zd/api/v2 existe para que los clientes escritos para Zendesk sigan funcionando. El v2 es la versión de Zendesk, no la nuestra. En esa superficie solo añadimos endpoints y campos, y nunca cambiamos una respuesta que analice el cliente de otro proveedor. Nos comprometemos con las formas documentadas en la página de la API compatible con Zendesk, y las pruebas de contrato las vigilan en cada build. Si Zendesk cambia su propia API, la nuestra sigue como está documentada y la diferencia se anota en el registro de cambios.

Versiones del payload de los webhooks

Cada entrega y cada ping de webhook llevan un entero version en su sobre. Hoy es 1 y forma parte del contrato público.

• Un sobre incompatible recibe un entero nuevo, nunca un cambio en uno existente.
• La versión se elige por suscripción de webhook, así que un webhook existente conserva el sobre para el que se construyó.
• Mientras se retira una versión, se entregan ambas durante todo el periodo de aviso.
• Los tipos de evento son aditivos. Una suscripción a un tipo de evento que no conoces nunca falla.
• Si alguna vez cambia el esquema de firma, la nueva firma llega en una cabecera nueva y se envían ambas durante el periodo de aviso.

12 meses de aviso

La retirada de un endpoint, un campo, un tipo de evento o una versión del sobre de webhook de cualquiera de las tres superficies se anuncia con al menos 12 meses de antelación.

«Anunciar» significa todo esto, no solo lo primero:

1. una entrada en Obsoleto del registro de cambios de la API, con la fecha prevista de retirada;
2. cabeceras de respuesta Deprecation y Sunset (RFC 8594) en las operaciones afectadas, para que un cliente lo vea sin leer nada;
3. deprecated: true en la operación o el campo del documento OpenAPI;
4. un correo a los propietarios de los espacios de trabajo y a los propietarios de los tokens de API que hayan llamado al endpoint en los últimos 90 días.

Las cabeceras tienen este aspecto:

HTTP/1.1 200 OK
Deprecation: Thu, 12 Mar 2026 00:00:00 GMT
Sunset: Fri, 12 Mar 2027 00:00:00 GMT
Link: <https://helpfalcon.com/developers/api-changelog>; rel="deprecation"; type="text/html"

Deprecation es cuándo lo anunciamos; Sunset es el primer momento en que la operación puede dejar de responder.

La única excepción es un cambio que nos impone un problema de seguridad o legal. Recibe tanto aviso como sea seguro dar, nunca menos de 7 días, y siempre un correo directo además de la entrada en el registro de cambios.

Qué no está cubierto

• Los endpoints propios de la aplicación de agentes (/mobile-api) son internos de nuestras apps y cambian con ellas. No construyas sobre ellos; la API REST tiene los mismos datos.
• Los endpoints beta, cuando los ofrecemos, se marcan como beta en el registro de cambios y no están sujetos a la regla de 12 meses hasta que el registro lo diga. Nada es beta por defecto: todo lo que aparece en la referencia de la API sin nota de beta está sujeto a la política completa.
• Comportamientos que siempre fueron un error. Corregir una respuesta que contradecía esta documentación es una corrección, y sale en una versión de parche con su entrada en el registro de cambios.

Mantenerse al día

• Sigue el registro de cambios de la API, que es donde cada cambio se escribe primero.
• Regenera o actualiza tu librería cliente cuando cambie el número menor de la versión de OpenAPI; los clientes se generan a partir de ese documento.
• Registra las cabeceras Deprecation y Sunset en tu integración. Son el primer aviso legible por máquina que recibirás.

Registro de decisión: ADR 0014, versiones de la API y de los webhooks y política de retirada.