Versionado, compatibilidad y cambios

Estado documental: Contrato propuesto. Las políticas y periodos concretos de transición se confirman al publicar cada cambio.

Objetivo

Esta página explica cómo evolucionan la API, los eventos y la documentación de YUPY sin confundir sus diferentes versiones.

Tres ejes de versión

Versión principal de API

/v1/

La versión incluida en la ruta identifica el contrato principal de la API. Un cambio incompatible importante puede requerir otra versión principal.

Versión de evento

{
  "event_type": "payment.reconciled",
  "event_version": "1.0"
}

La versión del evento permite evolucionar su payload sin cambiar necesariamente toda la API.

Versión documental

0.15.0-reference-catalogs-conventions-versioning

La versión documental identifica una publicación de esta biblioteca. No demuestra por sí sola que todas las interfaces descritas estén implementadas.

Estados documentales

Una página puede estar publicada y continuar como Propuesto.

Cambios compatibles

Normalmente se consideran compatibles:

• añadir un campo opcional;
• añadir un endpoint nuevo;
• añadir un evento nuevo;
• añadir un tipo de reporte;
• añadir un valor no terminal documentado;
• ampliar una respuesta sin retirar ni cambiar campos existentes;
• mejorar un mensaje legible sin cambiar el código procesable.

El cliente debe ignorar campos desconocidos que no necesite para su lógica.

Cambios incompatibles

Normalmente se consideran incompatibles:

• eliminar un campo disponible;
• volver obligatorio un campo antes opcional;
• cambiar el tipo de un valor;
• cambiar el significado de un estado o código;
• renombrar un evento;
• cambiar la forma de calcular o validar una firma;
• retirar una transición contractual;
• modificar una ruta sin ofrecer transición.

Un cambio incompatible requiere una versión, una migración o una ventana de transición definida.

Reglas para campos nuevos

El cliente debe:

• tolerar campos JSON adicionales;
• no depender del orden de los campos;
• no fallar por un campo opcional desconocido;
• no interpretar un estado desconocido como éxito;
• registrar la versión cuando la respuesta la incluya.

Versionado de eventos

El receptor debe procesar los eventos a partir de:

event_type
event_version
event_id

Cuando una versión nueva sea incompatible, el cliente debe adaptar su receptor antes de activarla. Los intentos de entrega del mismo evento conservan el mismo event_id.

Deprecación

Cuando una interfaz sea deprecada, YUPY informará:

• el recurso afectado;
• el reemplazo recomendado;
• la compatibilidad;
• la acción requerida;
• la ventana de transición aplicable;
• la fecha efectiva cuando esté confirmada.

No se promete un periodo universal de deprecación. Cada cambio debe publicar su propio alcance y transición.

Changelog

Cada entrada debe incluir:

fecha
versión
tipo de cambio
recurso afectado
descripción
compatibilidad
acción requerida
estado documental

Ejemplo de cambio compatible

Fecha: 2026-07-20
Versión: API v1
Tipo: compatible
Recurso: payment_order.context
Cambio: se añadió custom_reference_2
Acción requerida: ninguna
Estado documental: propuesto

Ejemplo de cambio con migración

Fecha: por confirmar
Versión: evento payment.reconciled 2.0
Tipo: incompatible
Cambio: estructura nueva del objeto state
Acción requerida: adaptar el receptor antes de activar 2.0
Estado documental: propuesto

Consulta de referencia

La biblioteca de endpoints propone:

GET /v1/reference/api-version
GET /v1/reference/statuses
GET /v1/reference/errors
GET /v1/reference/events
GET /v1/reference/changelog

Estas rutas pasan a implementadas o verificadas únicamente cuando estén disponibles y probadas.

Notificación de cambios

Según el alcance, YUPY puede comunicar cambios mediante:

• changelog;
• consola;
• correo a responsables técnicos;
• notas de versión;
• documentación actualizada.

La empresa debe mantener actualizado al menos un responsable técnico.

Compatibilidad de SDKs y colecciones

Un SDK, colección de pruebas o archivo OpenAPI debe indicar la versión del contrato que representa.

API version
event versions supported
documented_at
compatibility notes

La existencia de documentación no reemplaza la prueba de compatibilidad en sandbox.

Regla para integraciones productivas

Antes de adoptar una versión nueva, la empresa debe:

1. revisar el changelog;
2. identificar cambios incompatibles;
3. actualizar y probar en sandbox;
4. verificar webhooks, idempotencia y errores;
5. coordinar la activación productiva cuando corresponda.

Criterios de aceptación documental

1. API, eventos y documentación tienen versiones distintas.
2. Los estados documentales no implican automáticamente disponibilidad.
3. Los cambios compatibles pueden añadir campos opcionales.
4. Los cambios incompatibles requieren migración o versión.
5. Los eventos se procesan por tipo, versión e ID.
6. La deprecación informa reemplazo y transición.
7. No existe un plazo universal prometido.
8. El changelog indica compatibilidad y acción requerida.
9. Los artefactos procesables identifican su versión.
10. Los cambios se prueban en sandbox antes de producción.