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-07-31.

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-07-31"

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

Una versión nueva sale cada vez que un breaking change la necesita — a veces salen varias en el mismo mes, a veces pasan meses sin ninguna. Esto nunca afecta a una integración en marcha: tu organización y tus endpoints de webhook siguen en su versión fijada sin importar cuántas versiones salgan después. 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 — los responses mantienen la forma de tu versión fijada
2. Los pins no vencen: no hay ventana de soporte ni upgrade automático. Tu versión solo cambia cuando tú la cambias
3. Si un pin referencia una versión que ya no existe, los requests se resuelven a la versión actual
4. Las rutas legacy sin versionar /api/* (anteriores a /api/v1) devuelven los headers Deprecation: true y Sunset, con un Link a su sucesora en /api/v1 — los endpoints versionados nunca llevan estos headers

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

Cada release de SDK sale fijada a la versión de API contra la que fue compilada y envía el header Commet-Version automáticamente. Esto previene el clásico bug en que actualizar el SDK cambia silenciosamente las formas de los responses.

Además, todos los SDKs permiten fijar otra versión al construir el cliente — sin necesidad de actualizar el SDK:

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-07-31",
  "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.