Versionado de la API

DVS utiliza versionado basado en path con un prefijo /v1/ en cada endpoint. Esto garantiza compatibilidad hacia atrás durante todo el tiempo que se utilice una versión mayor determinada.

Reglas

Los cambios aditivos no incrementan la versión

Agregar campos opcionales a los bodies de request/response, nuevos error codes, nuevos tipos de eventos, nuevos query parameters — todos son compatibles hacia atrás. Estos se incorporan en v1 sin romper la integración.

Los cambios incompatibles van a un nuevo path

Renombrar o eliminar campos, cambiar tipos de campo, modificar la semántica de un error code existente, hacer obligatorio un campo previamente opcional — esos cambios se publican bajo /v2/.

Las versiones antiguas coexisten durante 6 meses

Cuando se publica /v2/, /v1/ sigue funcionando durante al menos 6 meses. Se notifica a todos los providers con anticipación a través de support@osigu.com y se publica en el Changelog.

Señales de deprecación mediante response headers

Durante la ventana de sunset, las responses deprecadas incluyen los headers estándar Deprecation y Sunset (RFC 8594). Es recomendable monitorearlos en los logs de la aplicación para saber cuándo migrar.

Versión del path vs versión del evento

Son independientes:

• /v1/ en la URL versiona el contrato de la API (estructuras de request/response).
• event_version: 1 en los payloads de webhook versiona el schema del evento.

Un endpoint /v1/ puede emitir eventos con event_version: 2 si el schema del evento evolucionó sin que cambie la API en sí. La versión actual del evento siempre está presente en el header X-DVS-Event-Version — conviene verificarlo antes de parsear.

Detección programática de deprecación

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jun 2027 00:00:00 GMT
Sunset: Wed, 01 Dec 2027 00:00:00 GMT
Link: <https://docs.osigu.com/changelog>; rel="deprecation"

Si el cliente recibe un header Deprecation, conviene registrarlo y notificar al equipo. Es necesario planificar la migración antes de la fecha de Sunset.