> ## Documentation Index
> Fetch the complete documentation index at: https://commet.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Versionado de API

> Cómo Commet versiona su API y webhooks para que tu integración nunca se rompa inesperadamente.

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-08-27`.

## Cómo se resuelven las versiones

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

| Prioridad | Origen | Descripción |
| - | - | - |
| 1 | Header `Commet-Version` | Override por request (solo API) |
| 2 | Pin del endpoint | Versión por endpoint de webhook (solo webhooks) |
| 3 | Pin de la organización | Definido al crear la org o en el último upgrade |
| 4 | Versión actual | Última versión, usada como fallback |

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

```bash theme={null}
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:

| SDK | Opción de pin |
| - | - |
| Node.js | `apiVersion` en las opciones del constructor |
| Python | `api_version` en el constructor |
| Go | Opción de cliente `commet.WithApiVersion(...)` |
| Java | `Commet.builder().apiVersion(...)` |
| PHP | Argumento `apiVersion` del constructor |

## Versionado de webhooks

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

```json theme={null}
{
  "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.


## Related topics

- [Referencia del SDK](/docs/es/sdk-reference.md)
- [Introducción](/docs/es/webhooks/introduction.md)
- [Verificación de cuenta](/docs/es/payouts-verification.md)
- [AI Onboarding](/docs/es/ai-onboarding.md)
- [Manejo de errores](/docs/es/error-handling.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.