Versionamiento del API

Versionamiento por fecha al estilo de las mejores plataformas: fija tu versión y actualiza cuando tú decidas.

SendIt usa versionamiento por fecha. Al crear tu cuenta, tu organización queda fijada a la versión vigente. Nada se rompe solo: tú decides cuándo adoptar cambios.

Versión actual

2026-05-01

Fija una versión

Tres mecanismos, en orden de prioridad:

1. Encabezado de petición (máxima prioridad, ideal para probar)

SendIt-Version: 2026-05-01

Útil para verificar tu código contra una versión nueva antes de adoptarla permanentemente.

2. Fijación por llave de API

curl -X PATCH https://api.sendit.mx/v1/api-keys/{id} \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "apiVersion": "2026-05-01" }'

Las peticiones con esa llave siempre usan la versión indicada, por encima de la fijación de la organización.

3. Fijación de la organización (por defecto)

curl -X PUT https://api.sendit.mx/v1/organizations/me \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "apiVersion": "2026-05-01" }'

Toda llave sin fijación propia hereda esta versión.

Actualiza sin sobresaltos

Prueba la versión nueva con el encabezado SendIt-Version en tu ambiente de staging.
Ajusta tu código a los cambios incompatibles documentados.
Actualiza la fijación de tu organización (o de llaves individuales) cuando todo esté verificado.

Política de deprecación

Momento	Qué pasa
6 meses antes	Se agrega el encabezado `SendIt-Version-Deprecated` a cada respuesta
1 mes antes	Notificación por correo a los OWNER de la organización
Tras el retiro	Las peticiones devuelven `400 API_VERSION_UNSUPPORTED`

Cada versión se mantiene al menos 18 meses.

Qué amerita una versión nueva

Las versiones nuevas son raras. Solo un cambio incompatible la requiere:

Renombrar o eliminar campos de respuesta
Cambiar el tipo de un campo (p. ej. string → objeto)
Eliminar valores de un enum
Cambiar campos obligatorios de una petición
Cambiar comportamiento por defecto

Agregar campos, endpoints, parámetros opcionales o tipos de evento no requiere versión nueva. Tu integración debe tolerar campos desconocidos.

Los payloads de webhook no llevan un campo de versión, y los endpoints de webhook no se fijan a una versión por separado. Hoy existe una sola versión del API, así que la forma de cada evento es la misma para todos tus endpoints. No necesitas ramificar tu handler por versión.