Versiones y obsolescencias

Esta política se aplica a toda la API de integración: REST API v1, widget, webhooks salientes y entrantes, SCIM 2.0. Las llamadas internas que usan los portales Core, Workspace y Desk no están cubiertas y pueden cambiar en cualquier momento: no las uses en las integraciones.

Versiones principales

• La versión principal está en la ruta: /api/v1/…. Cada respuesta de /api/v1 contiene X-Exo-API-Version: 1.
• La v1 es estable. Dentro de la v1 solo hacemos cambios compatibles:
  • nuevos endpoints, nuevos campos opcionales en las solicitudes, nuevos parámetros de consulta;
  • nuevos campos en las respuestas: tu cliente debe ignorar los que no conozca;
  • nuevos tipos de evento de webhook: tu sistema debe ignorar los que no conozca;
  • nuevos códigos de error: gestiona los desconocidos según el estado HTTP;
  • nuevos encabezados opcionales.
• Un cambio incompatible requiere una nueva versión principal (/api/v2). Es incompatible eliminar o renombrar un campo, un endpoint o un evento, cambiar un tipo, hacer obligatorio un campo opcional o cambiar la autenticación.
• Cuando sale una nueva versión principal, la anterior sigue disponible durante al menos 12 meses.

Obsolescencias

• Una función obsoleta sigue funcionando durante al menos 6 meses desde el anuncio.
• Las respuestas que usan una función obsoleta contienen:
  • Deprecation: @<unix-seconds>: cuándo se anunció la obsolescencia (RFC 9745);
  • Sunset: <HTTP-date>: cuándo dejará de funcionar la función (RFC 8594);
  • Link: <url>; rel="deprecation": la guía de migración.
• Cada obsolescencia figura en el changelog y está marcada como deprecated en la especificación OpenAPI.

Obsolescencias en curso

Función	Anunciada	Deja de funcionar	Qué usar
Claves de API nh_…	1 de noviembre de 2026	30 de junio de 2027	Claves nhk.<keyid>.<secret>
Firma X-NH-Signature en los webhooks salientes	1 de noviembre de 2026	30 de junio de 2027	X-Exo-Signature con X-Exo-Timestamp
Firma X-NH-Connector-Signature en los webhooks entrantes	1 de noviembre de 2026	30 de junio de 2027	X-Exo-Signature con X-Exo-Timestamp
Campos event, timestamp, source en el cuerpo de los webhooks	1 de noviembre de 2026	30 de junio de 2027	type, created_at, data

Especificación y changelog

• La especificación OpenAPI es el contrato. Su versión sigue el versionado semántico 1.MINOR.PATCH: MINOR aumenta con las adiciones compatibles y PATCH, solo con las correcciones de documentación.
• Cada cambio en la API actualiza la versión de la especificación y añade una entrada al changelog.