Sandbox

Con una clave xy_test_... trabajas contra el sandbox: misma URL, mismas respuestas y mismos errores que en producción, pero con datos de ejemplo y sin tocar los datos reales de la empresa.

Cómo se comporta

Lecturas: devuelven siempre el mismo conjunto de datos de ejemplo (3 áreas, 3 empleados —uno inactivo—, solicitudes de vacaciones en varios estados, saldos y tramos de horas). Los ids son estables: puedes usarlos en tus pruebas automáticas.
Escrituras (POST, PATCH): se validan igual que en producción y devuelven un objeto plausible, pero no se guarda nada. Un GET posterior no verá el cambio, y el external_id tampoco se guarda.
Importación de empleados: el job sí se guarda (entorno test) para que puedas probar el flujo completo de encolar y consultar resultados.
Webhooks: cada escritura en sandbox emite su evento a los webhooks registrados en el entorno Test, firmado con el secreto de ese entorno. Ideal para probar tu receptor.
Mensajes y Verify: los envíos son reales, pero solo a tus números de prueba confirmados en el panel (ver Mensajes y Verify).
Autenticación, scopes, IPs permitidas, límite de peticiones y log: funcionan exactamente igual (con la configuración del entorno Test del panel).

Datos de ejemplo útiles

Dato	Valor
Empleados (`external_id`)	`ERP-0001` (activa), `ERP-0002` (activo, contrato a término fijo), `ERP-0003` (inactiva)
Teléfonos ya usados	`+573000000001`, `+573000000002`, `+573000000003` → un alta con uno de ellos responde `409 employee_already_exists`
Áreas	Operaciones (raíz), Almacen (hija de Operaciones), Administracion

Busca un empleado de ejemplo por su external_id:

curl "https://api.xyago.com/v1/employees?external_id=ERP-0001" \
  -H "Authorization: Bearer $XYAGO_API_KEY"

Antes de pasar a live

Tu integración trata todos los códigos de error que le afectan, en especial 409, 422, 429 y 502.
Recorres los listados con next_cursor hasta que sea null.
Respetas Retry-After y reintentas con backoff exponencial.
Tu receptor de webhooks verifica la firma, responde 2xx en menos de 10 s y descarta eventos repetidos por id.
Guardas el X-Request-Id de cada petición en tus logs.

El sandbox no sustituye a una prueba con datos reales: en live hay efectos que el sandbox no reproduce (notificaciones a los empleados, calendario, reglas de vacaciones de la empresa). Haz la primera carga real con pocos empleados.