Versionado de la API

Estrategia de versionado

Migo prefiere la evolución aditiva y retrocompatible por encima de saltos de versión forzados. La mayoría de los cambios salen en su lugar, sin una nueva versión. Donde existe un segmento de versión, este forma parte de la ruta.

• Middleware (migo-api) usa versionado de ruta por servicio: algunas rutas de servicio llevan un segmento /v1/ (por ejemplo /v1/subscriptions/...), mientras que otras — incluyendo los puntos de entrada de Payment Link POST /transactions y POST /transactions-hook — se sirven en la raíz sin segmento de versión. Usa siempre la ruta exacta que se muestra en la referencia de la API Middleware y en las recetas de este portal; no asumas que un prefijo /v1/ está presente (o ausente) en todas las rutas.
• Wallet Gateway (ali-api-gw-rest) y CMS Backoffice (ali-api-cms-rest) hoy no están versionados — no hay segmento de versión en sus rutas. Trata el contrato actual como la línea base.

Usa la Referencia de API como fuente de verdad para la ruta en vivo de cada endpoint.

Qué cuenta como cambio incompatible

Incompatible (se anuncia con anticipación, puede introducir una nueva ruta versionada):

• Eliminar un endpoint
• Eliminar un campo de respuesta
• Cambiar el tipo de un campo de solicitud o de respuesta
• Agregar un nuevo campo requerido en la solicitud
• Cambiar patrones de URL o verbos HTTP
• Endurecer validaciones que antes aceptaban entradas válidas
• Cambiar los requisitos de autenticación

No incompatible (sale en su lugar, sin nueva versión):

• Agregar un nuevo endpoint
• Agregar un campo opcional en la solicitud
• Agregar un nuevo campo de respuesta
• Agregar un nuevo valor de enum (los clientes deben ignorar los valores desconocidos — ver abajo)
• Mejoras de rendimiento
• Correcciones de errores que hacen que el endpoint se ajuste a su documentación

Expectativas del cliente

Para consumir las APIs de Migo de forma resiliente:

1. Ignora los campos de respuesta desconocidos. Aparecerán nuevos campos en respuestas existentes.
2. Ignora los valores de enum desconocidos. Trata los valores desconocidos como "otro" en lugar de fallar.
3. Nunca dependas de comportamiento no documentado. Si no está en la especificación OpenAPI, puede cambiar sin previo aviso.
4. Suscríbete al Changelog. Los anuncios de cambios incompatibles aparecen ahí con más de 90 días de anticipación.

Política de deprecación

Política a futuro

La señalización de deprecación basada en headers descrita a continuación es la política prevista. Los gateways actualmente no emiten los headers Sunset / Deprecation / x-migo-warning ni responden 410 Gone en una fecha de sunset — apóyate en el Changelog como canal autoritativo de deprecación hasta que esto se implemente.

Cuando un endpoint o campo se depreca, la señalización planeada es:

1. Lo anunciamos en el Changelog con una ventana mínima de sunset de 90 días (180 días para cambios incompatibles en producción).
2. Los endpoints deprecados retornarán un header de respuesta Sunset: <rfc-1123-date> y un header Deprecation: true.
3. Las respuestas incluirán un header x-migo-warning con un enlace a la guía de migración.
4. Después de la fecha de sunset, el endpoint retornará 410 Gone.

Cómo se realizaría una migración

Si un cambio incompatible llegara a requerir una nueva ruta versionada, la secuencia prevista es:

1. Sale la nueva ruta y se documenta en la Referencia de API.
2. Se publica una guía de migración en el Changelog.
3. La ruta reemplazada se anuncia como deprecada, con la ventana de sunset indicada arriba.
4. La ruta reemplazada se retira solo después de que esa ventana cierre.

Completa tu migración dentro de la ventana anunciada. El soporte está disponible en support@migopayments.com.