Versionado

Una fecha, no un número

Cada cambio que rompe el contrato entra en vigor en una fecha, anunciada antes en el changelog. Esa fecha es la versión. Hoy hay una:

Lo que no rompe —campos nuevos opcionales, códigos de error nuevos, recursos nuevos— no estrena versión: llega a todas.

Anclar tu integración: Tikin-Version

curl https://api.tikin.is/v1/tenant \
  -H "Authorization: Bearer tk_live_51Hx…" \
  -H "Tikin-Version: 2026-09-08"

• Rige la última versión publicada en o antes de la fecha que mandes. Puedes mandar el día en que escribiste la integración: no tiene que coincidir con una fecha de la tabla.
• Sin el header rige la más reciente. Es cómodo para empezar y peligroso para producción: cuando publiquemos una versión que rompe, tu integración la recibirá sin que hayas cambiado nada. Ancla antes de salir a producción.
• Toda respuesta de /v1 —éxito o error— trae el header Tikin-Version con la versión con la que se escribió.
• Un header que no es una fecha YYYY-MM-DD, o anterior a la primera versión, es 400 invalid_field. No hay contrato que darle.

GET /v1/tenant lo resume de una vez:

{
  "code": "acme",
  "name": "Acme S.A.S.",
  "scopes": ["read", "transfers"],
  "api_version": { "effective": "2026-09-08", "requested": "2026-09-30", "latest": "2026-09-08" }
}

effective es la que rige tus pedidos; requested lo que mandaste (o null); latest la más reciente. Si effective y latest difieren, hay una versión más nueva y el changelog dice qué cambió.

Cómo migrar de versión

1. Lee en el changelog la entrada de la fecha nueva: qué rompe y cómo se ve.
2. Prueba con Tikin-Version: <fecha nueva> en tu sandbox (o con un token read en producción, para las lecturas).
3. Cambia el header en producción. Volver atrás es cambiar el header de vuelta: las versiones anteriores siguen sirviendo.

Una versión se retira con al menos 6 meses de aviso en el changelog.