Versionado de API

Commet usa versionado de API basado en fechas, inspirado en Stripe. Cada breaking change queda detrás de una versión, y tu integración se queda en la versión fijada hasta que decidas actualizarla.

Formato de versión

Las versiones usan la fecha en la que se lanzaron: YYYY-MM-DD (por ejemplo 2026-05-01).

La versión actual es 2026-05-01.

Cómo se resuelven las versiones

Cada request a la API y cada entrega de webhook resuelve una versión con esta prioridad:

Para requests a la API, envía el header Commet-Version para sobrescribir el pin de tu organización en ese request:

curl https://commet.co/api/v1/subscriptions \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Commet-Version: 2026-05-01"

Para webhooks, cada endpoint puede tener su propia versión fijada. Si no se define, usa el pin de la organización.

Qué cambia entre versiones

Los breaking changes se agrupan en versiones lanzadas dos veces por año. Un breaking change es cualquier cosa que:

• Elimina un campo de un response
• Renombra un campo
• Cambia el tipo de un campo
• Cambia la estructura de un objeto anidado
• Modifica el comportamiento por defecto

Los cambios no breaking se publican continuamente y nunca requieren subir de versión:

• Nuevos campos agregados a responses
• Nuevos tipos de evento
• Nuevos endpoints de API
• Nuevos parámetros opcionales de request

Política de retrocompatibilidad

Cuando se lanza una nueva versión:

1. Tu pin existente sigue funcionando sin cambios
2. La versión anterior se soporta por 12 meses después del lanzamiento de la nueva
3. Las versiones deprecadas devuelven los headers Deprecation: true y Sunset con la fecha de fin
4. Después de la fecha de sunset, los requests en esa versión se actualizan automáticamente

Actualizar tu versión

1. Revisa el changelog para ver los breaking changes entre tu versión actual y la objetivo
2. Actualiza tu código para manejar las nuevas formas de response
3. Prueba con el header Commet-Version antes de aplicar el cambio
4. Cambia la versión fijada de tu organización desde el dashboard

Para webhooks, puedes fijar un endpoint nuevo a la última versión y mantener el viejo activo. Ambos reciben los eventos transformados a su respectiva versión, lo que te permite validar en producción antes de hacer el switch.

Comportamiento de los SDKs

Los SDKs se fijan a la versión contra la que fueron compilados:

Todos los SDKs envían el header Commet-Version automáticamente. Esto previene el clásico bug en que actualizar el SDK cambia silenciosamente las formas de los responses.

Versionado de webhooks

Los payloads de webhook incluyen un campo apiVersion en el envelope, así siempre sabes qué versión modeló los datos:

{
  "event": "subscription.activated",
  "timestamp": "2026-05-12T14:30:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-05-01",
  "data": { ... }
}

Cada endpoint de webhook se puede fijar de forma independiente. Para migrar, crea un segundo endpoint fijado a la nueva versión — ambos reciben todos los eventos, cada uno transformado a su propia versión. Una vez que el nuevo endpoint esté funcionando, elimina el viejo.