Versiones y cambios

La versión forma parte de la URL (/v1). Dentro de una versión solo hacemos cambios compatibles; los cambios incompatibles irán en una versión nueva.

Política de versiones

Compatibles (pueden llegar en v1 sin aviso previo; tu integración debe tolerarlos):

Endpoints, parámetros opcionales o campos de respuesta nuevos.
Códigos de error nuevos (con un status HTTP coherente) y eventos de webhook nuevos (solo los recibes si te suscribes).
Cambios en el texto de message de los errores.
Nuevos valores de enumeraciones documentadas como ampliables.

Incompatibles (solo en una versión nueva): eliminar o renombrar campos, endpoints o eventos, cambiar tipos o hacer obligatorio un parámetro. Cuando salga una versión nueva, la anterior seguirá funcionando durante un periodo de transición que se anunciará con antelación a los administradores de las empresas que la usan.

Ignora los campos desconocidos al leer JSON (no uses deserialización estricta) y no dependas del orden de las claves.

Estado

Versión	Estado	Contenido
`v1`	Estable	Áreas, empleados (incl. importación), vacaciones, registro de horas, mensajes con plantilla, códigos de verificación (Verify) y webhooks.
`v2`	Prevista	Contratos (con documento firmado; eventos `contract.signed` y `contract.expiring`). Hoy aparece en el panel como no disponible.

Registro de cambios

v1 — Plantillas con botones y revisión (noviembre de 2026)

Las plantillas pueden tener hasta 3 botones: respuesta rápida (quick_reply, con un payload que vuelve en el webhook) y enlace (url, máx. 2, con una variable opcional que se rellena con el campo nuevo button_variables de POST /messages). Ver Plantillas y botones.
El texto de los botones va por idioma (texts, con la forma de languages, uno por idioma de la plantilla) y cada mensaje lo muestra en el idioma de su texto.
Webhook nuevo message.button_clicked (primer clic de cada botón; con el text del botón en el idioma del envío y su language).
Objeto plantilla: campos nuevos buttons, version y review_flags; estado nuevo superseded (editar una aprobada crea una versión nueva). Errores nuevos 409 template_paused y 422 invalid_button_variables.
El texto de una plantilla ya no puede llevar enlaces (http(s)://, www.): se usan botones de enlace. Las plantillas ya aprobadas siguen funcionando.
POST /verify/check sigue funcionando aunque los límites no se puedan comprobar en ese momento (ya no responde 503 limits_unavailable).

v1 — Verify (noviembre de 2026)

Producto verify: POST /verify/start (con Idempotency-Key obligatoria), POST /verify/check y GET /verify/{id}. Códigos de 6 dígitos por el chat de xYago, con respuesta inmediata 404 recipient_not_on_xyago para el SMS de respaldo. Ver Verify.
Webhooks verification.delivered, verification.read, verification.verified, verification.expired y verification.failed.
Se retira el producto previsto otp (v2, /otp/send y /otp/verify, nunca publicado): lo sustituye verify.

v1 — mensajes (noviembre de 2026)

Producto messages: POST /messages (con Idempotency-Key obligatoria), GET /messages, GET /messages/{id}, GET /senders y GET /templates. Ver Mensajes e Invitar usuarios.
Webhooks message.sent, message.delivered, message.read, message.failed, sender.status_changed y template.status_changed.

v1 — publicación inicial

Productos areas, employees, vacations y time_entries con API keys live y sandbox, scopes, IPs permitidas y límite de peticiones configurables en el panel.
Importación asíncrona de empleados con upsert por external_id.
Webhooks firmados (HMAC-SHA256) con reintentos y rotación de secreto sin cortes.