Versionado de la API

La API de Genius Checkout se versiona en el prefijo de URL. Hoy la versión es /v1.

https://app.geniuscheckout.com/api/v1/checkout-sessions

Un futuro cambio incompatible se entrega como /v2 junto a /v1 — la versión anterior sigue corriendo mientras los consumidores migran.

Estabilidad dentro de una versión mayor

Dentro de una versión mayor (/v1) nunca hacemos cambios incompatibles. Sí podemos:

• Añadir nuevos endpoints.
• Añadir campos opcionales nuevos a los cuerpos de solicitud.
• Añadir campos nuevos a las respuestas.
• Añadir nuevos tipos de evento o campos en payloads de webhook existentes.
• Añadir monedas a la lista soportada.
• Añadir nuevos estados a enums existentes (pero solo cuando sea contextualmente seguro — ver abajo).

No hacemos, dentro de /v1:

• Eliminar o renombrar campos.
• Cambiar el tipo de un campo.
• Hacer obligatorio un campo opcional.
• Cambiar el significado de un código de estado HTTP.
• Cambiar el esquema de firma HMAC.

Trata los campos desconocidos como compatibles hacia adelante. No valides estrictamente la forma de las respuestas — registra e ignora lo que no reconozcas.

Tipos de evento de webhook

Podemos introducir nuevos tipos de evento en el catálogo estándar (p. ej. un nuevo subscription.dunning_started). Los suscriptores deben ignorar tipos desconocidos en lugar de devolver 4xx.

Enums de estado

Cuando agregamos un nuevo estado (p. ej. un nuevo TransactionStatus), lo tratamos como aditivo — tu código debería manejar el nuevo valor como si fuera un estado existente relacionado (p. ej. un nuevo estado de falla debería tratarse como failed). Para facilitarlo, las páginas de Webhooks y de recurso registran el set actual del enum, y el changelog anota cada adición.

Política de deprecación

Eliminar un endpoint o hacer un cambio incompatible dentro de una versión mayor está reservado para el caso raro en que no podamos mantenerlo de forma segura (una vulnerabilidad, un EOL del proveedor, una directiva de cumplimiento). Cuando lo hagamos:

1. Aviso de 12 meses publicado en el Changelog, enviado por correo a cada consumidor de la API con tráfico al endpoint afectado en los 30 días previos, y anunciado en el panel.
2. Encabezado Sunset en cada respuesta del endpoint deprecado, con la fecha planeada de eliminación en formato HTTP-date. Sigue el RFC 8594.
3. Encabezado Deprecation establecido a true en cada respuesta.
4. Encabezado Link apuntando al endpoint sucesor y su documentación.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 22 May 2027 00:00:00 GMT
Link: <https://docs.geniuscheckout.com/es/payments>; rel="successor-version"

Tienes un año desde el primer encabezado Sunset para migrar. El endpoint deja de responder en esa fecha; las solicitudes empiezan a recibir 410 Gone.

Saltos de versión mayor

Cuando se lanza /v2:

• /v1 sigue corriendo con los encabezados de deprecación anteriores.
• La ventana de migración es de al menos 18 meses antes de que /v1 se apague.
• Una guía de migración se publica en el sitio de documentación en /migration/v1-to-v2.

Cómo descubrir lo que cambió

• Sigue el Changelog — cada cambio entregado con la fecha.
• Suscríbete a anuncios escribiendo a [email protected] y pidiendo ser agregado al newsletter de desarrolladores.
• Corre periódicamente una suite de smoke-test contra tu integración — publicamos tarjetas de prueba que puedes integrar en CI.

Siguiente

• Changelog — qué se entregó y cuándo
• Webhooks — agregar eventos es seguro entre versiones