{"info":{"name":"xYago Public API v1","description":"Generada desde el OpenAPI de la API publica de xYago (https://api.xyago.com/v1/docs/es/). Rellena la variable `apiKey` con tu clave de sandbox (xy_test_...) o live (xy_live_...): ambas usan la misma `baseUrl`.","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json"},"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{apiKey}}","type":"string"}]},"variable":[{"key":"baseUrl","value":"https://api.xyago.com/v1","type":"string"},{"key":"apiKey","value":"xy_test_EXAMPLE_replace-with-your-sandbox-key","type":"string"}],"item":[{"name":"Áreas","description":"Áreas (departamentos, sedes, secciones) de la empresa. Scopes `areas:read` y `areas:write`.","item":[{"name":"Listar áreas","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/areas","host":["{{baseUrl}}"],"path":["areas"],"query":[{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Áreas **activas** de la empresa, de la más reciente a la más antigua, paginadas\npor cursor. Las áreas inactivas no aparecen.\n\nScope: `areas:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/areas","host":["{{baseUrl}}"],"path":["areas"],"query":[{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Áreas **activas** de la empresa, de la más reciente a la más antigua, paginadas\npor cursor. Las áreas inactivas no aparecen.\n\nScope: `areas:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\",\n      \"public_id\": \"AR-0004-02\",\n      \"name\": \"Bodega Medellín\",\n      \"parent_id\": \"6f1d2c3b-4a5e-4f60-8a71-0b2c3d4e5f60\",\n      \"status\": \"active\",\n      \"minimum_employees\": 3,\n      \"maximum_employees\": 12,\n      \"skills\": [\n        \"montacargas\",\n        \"inventarios\"\n      ],\n      \"created_at\": \"2026-03-02T14:05:00Z\",\n      \"updated_at\": \"2026-03-02T14:05:00Z\"\n    },\n    {\n      \"id\": \"6f1d2c3b-4a5e-4f60-8a71-0b2c3d4e5f60\",\n      \"public_id\": \"AR-0004\",\n      \"name\": \"Logística\",\n      \"status\": \"active\",\n      \"minimum_employees\": 5,\n      \"maximum_employees\": 40,\n      \"skills\": [],\n      \"created_at\": \"2026-02-10T13:00:00Z\",\n      \"updated_at\": \"2026-02-18T16:30:00Z\"\n    }\n  ],\n  \"next_cursor\": \"MjAyNi0wMi0xMFQxMzowMDowMHw2ZjFkMmMzYg\"\n}"}]},{"name":"Crear un área","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/areas","host":["{{baseUrl}}"],"path":["areas"]},"description":"Crea un área en la empresa de la API key (la empresa nunca se envía: sale de la\nclave). Campos desconocidos → `422 validation_error`. `parent_id` debe ser un\nárea activa de la empresa. Emite el webhook `area.created`.\n\nScope: `areas:write`.","body":{"mode":"raw","raw":"{\n  \"name\": \"Bodega Medellín\",\n  \"parent_id\": \"6f1d2c3b-4a5e-4f60-8a71-0b2c3d4e5f60\",\n  \"minimum_employees\": 3,\n  \"maximum_employees\": 12,\n  \"skills\": [\n    \"montacargas\",\n    \"inventarios\"\n  ]\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201 Creado","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/areas","host":["{{baseUrl}}"],"path":["areas"]},"description":"Crea un área en la empresa de la API key (la empresa nunca se envía: sale de la\nclave). Campos desconocidos → `422 validation_error`. `parent_id` debe ser un\nárea activa de la empresa. Emite el webhook `area.created`.\n\nScope: `areas:write`.","body":{"mode":"raw","raw":"{\n  \"name\": \"Bodega Medellín\",\n  \"parent_id\": \"6f1d2c3b-4a5e-4f60-8a71-0b2c3d4e5f60\",\n  \"minimum_employees\": 3,\n  \"maximum_employees\": 12,\n  \"skills\": [\n    \"montacargas\",\n    \"inventarios\"\n  ]\n}","options":{"raw":{"language":"json"}}}},"status":"Creado","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\",\n  \"public_id\": \"AR-0004-02\",\n  \"name\": \"Bodega Medellín\",\n  \"parent_id\": \"6f1d2c3b-4a5e-4f60-8a71-0b2c3d4e5f60\",\n  \"status\": \"active\",\n  \"minimum_employees\": 3,\n  \"maximum_employees\": 12,\n  \"skills\": [\n    \"montacargas\",\n    \"inventarios\"\n  ],\n  \"created_at\": \"2026-03-02T14:05:00Z\",\n  \"updated_at\": \"2026-03-02T14:05:00Z\"\n}"}]},{"name":"Obtener un área","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/areas/:id","host":["{{baseUrl}}"],"path":["areas",":id"],"variable":[{"key":"id","value":"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162","description":"Id del área."}]},"description":"Detalle de un área de la empresa. Un id de otra empresa responde `404`, igual\nque uno inexistente.\n\nScope: `areas:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/areas/:id","host":["{{baseUrl}}"],"path":["areas",":id"],"variable":[{"key":"id","value":"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162","description":"Id del área."}]},"description":"Detalle de un área de la empresa. Un id de otra empresa responde `404`, igual\nque uno inexistente.\n\nScope: `areas:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\",\n  \"public_id\": \"AR-0004-02\",\n  \"name\": \"Bodega Medellín\",\n  \"parent_id\": \"6f1d2c3b-4a5e-4f60-8a71-0b2c3d4e5f60\",\n  \"status\": \"active\",\n  \"minimum_employees\": 3,\n  \"maximum_employees\": 12,\n  \"skills\": [\n    \"montacargas\",\n    \"inventarios\"\n  ],\n  \"created_at\": \"2026-03-02T14:05:00Z\",\n  \"updated_at\": \"2026-03-02T14:05:00Z\"\n}"}]}]},{"name":"Empleados","description":"Empleados de la empresa: consulta, alta, edición, desactivación e importación masiva con upsert por `external_id`. Scopes `employees:read` y `employees:write`.","item":[{"name":"Listar empleados","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees","host":["{{baseUrl}}"],"path":["employees"],"query":[{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true},{"key":"external_id","value":"","description":"Busca por el identificador de tu ERP: devuelve 0 o 1 resultado.","disabled":true}]},"description":"Empleados de la empresa (activos e inactivos), paginados por cursor en el orden\ndel panel (número de empleado). Con `external_id` devuelve 0 o 1 resultado: es la\nforma recomendada de saber si un empleado de tu ERP ya existe en xYago. Al pasar\n`cursor` se mantiene el tamaño de página de la primera petición.\n\nScope: `employees:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees","host":["{{baseUrl}}"],"path":["employees"],"query":[{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true},{"key":"external_id","value":"","description":"Busca por el identificador de tu ERP: devuelve 0 o 1 resultado.","disabled":true}]},"description":"Empleados de la empresa (activos e inactivos), paginados por cursor en el orden\ndel panel (número de empleado). Con `external_id` devuelve 0 o 1 resultado: es la\nforma recomendada de saber si un empleado de tu ERP ya existe en xYago. Al pasar\n`cursor` se mantiene el tamaño de página de la primera petición.\n\nScope: `employees:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n      \"external_id\": \"SIESA-000123\",\n      \"first_name\": \"Valentina Rojas Castaño\",\n      \"email\": \"valentina.rojas@example.com\",\n      \"phone_number\": \"+573005550123\",\n      \"document_number\": \"1020304050\",\n      \"job\": {\n        \"id\": \"9d4f6a28-3b1c-4e7d-b5a9-0e2f4c6d8a13\",\n        \"name\": \"Auxiliar de bodega\"\n      },\n      \"area_ids\": [\n        \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\"\n      ],\n      \"status\": \"active\",\n      \"contract_type\": \"Full-time fixed-term\",\n      \"hire_date\": \"2026-02-01\",\n      \"contract_end_date\": \"2027-01-31\"\n    },\n    {\n      \"id\": \"5e7b1d93-2a4c-4b6e-8f0a-3c5d7e9f1b26\",\n      \"external_id\": \"SIESA-000087\",\n      \"first_name\": \"Andrés Felipe Mejía\",\n      \"email\": \"andres.mejia@example.com\",\n      \"phone_number\": \"+573105550187\",\n      \"document_number\": \"79856412\",\n      \"job\": {\n        \"id\": \"9d4f6a28-3b1c-4e7d-b5a9-0e2f4c6d8a13\",\n        \"name\": \"Conductor\"\n      },\n      \"area_ids\": [\n        \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\"\n      ],\n      \"status\": \"inactive\",\n      \"contract_type\": \"Full-time permanent\",\n      \"hire_date\": \"2023-06-15\"\n    }\n  ],\n  \"next_cursor\": \"eyJwIjogMiwgInMiOiA1MH0\"\n}"}]},{"name":"Crear un empleado","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees","host":["{{baseUrl}}"],"path":["employees"]},"description":"Da de alta un empleado en la empresa de la API key, con los mismos efectos que el\nalta desde el panel. `phone_number` en formato E.164 (p. ej. `+573005550123`).\n`contract_end_date` es obligatoria salvo para `Full-time permanent` y\n`Part-time permanent`. Envía `external_id` (el id de tu ERP) para poder\nreintentar sin duplicar: ver la guía de idempotencia. Emite `employee.created`.\n\nScope: `employees:write`.","body":{"mode":"raw","raw":"{\n  \"external_id\": \"SIESA-000123\",\n  \"first_name\": \"Valentina\",\n  \"last_name\": \"Rojas Castaño\",\n  \"email\": \"valentina.rojas@example.com\",\n  \"phone_number\": \"+573005550123\",\n  \"document_number\": \"1020304050\",\n  \"job_title\": \"Auxiliar de bodega\",\n  \"contract_type\": \"Full-time fixed-term\",\n  \"hire_date\": \"2026-02-01\",\n  \"contract_end_date\": \"2027-01-31\",\n  \"work_shifts\": [\n    {\n      \"day\": \"Monday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Tuesday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Wednesday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Thursday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Friday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Saturday\",\n      \"start\": \"08:00\",\n      \"end\": \"12:00\"\n    }\n  ],\n  \"vacation_days\": 15\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201 Creado","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees","host":["{{baseUrl}}"],"path":["employees"]},"description":"Da de alta un empleado en la empresa de la API key, con los mismos efectos que el\nalta desde el panel. `phone_number` en formato E.164 (p. ej. `+573005550123`).\n`contract_end_date` es obligatoria salvo para `Full-time permanent` y\n`Part-time permanent`. Envía `external_id` (el id de tu ERP) para poder\nreintentar sin duplicar: ver la guía de idempotencia. Emite `employee.created`.\n\nScope: `employees:write`.","body":{"mode":"raw","raw":"{\n  \"external_id\": \"SIESA-000123\",\n  \"first_name\": \"Valentina\",\n  \"last_name\": \"Rojas Castaño\",\n  \"email\": \"valentina.rojas@example.com\",\n  \"phone_number\": \"+573005550123\",\n  \"document_number\": \"1020304050\",\n  \"job_title\": \"Auxiliar de bodega\",\n  \"contract_type\": \"Full-time fixed-term\",\n  \"hire_date\": \"2026-02-01\",\n  \"contract_end_date\": \"2027-01-31\",\n  \"work_shifts\": [\n    {\n      \"day\": \"Monday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Tuesday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Wednesday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Thursday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Friday\",\n      \"start\": \"07:00\",\n      \"end\": \"16:00\"\n    },\n    {\n      \"day\": \"Saturday\",\n      \"start\": \"08:00\",\n      \"end\": \"12:00\"\n    }\n  ],\n  \"vacation_days\": 15\n}","options":{"raw":{"language":"json"}}}},"status":"Creado","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"external_id\": \"SIESA-000123\",\n  \"first_name\": \"Valentina Rojas Castaño\",\n  \"email\": \"valentina.rojas@example.com\",\n  \"phone_number\": \"+573005550123\",\n  \"document_number\": \"1020304050\",\n  \"job\": {\n    \"id\": \"9d4f6a28-3b1c-4e7d-b5a9-0e2f4c6d8a13\",\n    \"name\": \"Auxiliar de bodega\"\n  },\n  \"area_ids\": [\n    \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\"\n  ],\n  \"status\": \"active\",\n  \"contract_type\": \"Full-time fixed-term\",\n  \"hire_date\": \"2026-02-01\",\n  \"contract_end_date\": \"2027-01-31\"\n}"}]},{"name":"Importar empleados (upsert asíncrono por external_id)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/import","host":["{{baseUrl}}"],"path":["employees","import"]},"description":"Encola una importación de 1 a 500 filas y responde `202` con el `job_id`. Cada\nfila tiene la forma de `POST /employees` con `external_id` **obligatorio** (clave\ndel upsert):\n\n- `external_id` desconocido → alta (la fila necesita todos los campos obligatorios\n  del alta).\n- `external_id` ya asociado a un empleado → edición parcial (solo los campos\n  enviados; `work_shifts` y `vacation_days` se ignoran).\n\nUna fila con error no aborta el job. Reenviar el mismo fichero no duplica\nempleados, y si un job idéntico sigue en cola o en proceso se devuelve el mismo\n`job_id`. Consulta el progreso con `GET /employees/import/{job_id}`. Emite\n`employee.created` / `employee.updated` por fila.\n\nScope: `employees:write`.","body":{"mode":"raw","raw":"{\n  \"rows\": [\n    {\n      \"external_id\": \"SIESA-000123\",\n      \"first_name\": \"Valentina\",\n      \"last_name\": \"Rojas Castaño\",\n      \"email\": \"valentina.rojas@example.com\",\n      \"phone_number\": \"+573005550123\",\n      \"document_number\": \"1020304050\",\n      \"job_title\": \"Auxiliar de bodega\",\n      \"contract_type\": \"Full-time fixed-term\",\n      \"hire_date\": \"2026-02-01\",\n      \"contract_end_date\": \"2027-01-31\",\n      \"work_shifts\": [\n        {\n          \"day\": \"Monday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Tuesday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Wednesday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Thursday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Friday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Saturday\",\n          \"start\": \"08:00\",\n          \"end\": \"12:00\"\n        }\n      ],\n      \"vacation_days\": 15\n    },\n    {\n      \"external_id\": \"SIESA-000087\",\n      \"job_title\": \"Conductor de reparto\"\n    },\n    {\n      \"external_id\": \"SIESA-000150\",\n      \"first_name\": \"Camilo\"\n    }\n  ]\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"202 Aceptado: se procesa en segundo plano","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/import","host":["{{baseUrl}}"],"path":["employees","import"]},"description":"Encola una importación de 1 a 500 filas y responde `202` con el `job_id`. Cada\nfila tiene la forma de `POST /employees` con `external_id` **obligatorio** (clave\ndel upsert):\n\n- `external_id` desconocido → alta (la fila necesita todos los campos obligatorios\n  del alta).\n- `external_id` ya asociado a un empleado → edición parcial (solo los campos\n  enviados; `work_shifts` y `vacation_days` se ignoran).\n\nUna fila con error no aborta el job. Reenviar el mismo fichero no duplica\nempleados, y si un job idéntico sigue en cola o en proceso se devuelve el mismo\n`job_id`. Consulta el progreso con `GET /employees/import/{job_id}`. Emite\n`employee.created` / `employee.updated` por fila.\n\nScope: `employees:write`.","body":{"mode":"raw","raw":"{\n  \"rows\": [\n    {\n      \"external_id\": \"SIESA-000123\",\n      \"first_name\": \"Valentina\",\n      \"last_name\": \"Rojas Castaño\",\n      \"email\": \"valentina.rojas@example.com\",\n      \"phone_number\": \"+573005550123\",\n      \"document_number\": \"1020304050\",\n      \"job_title\": \"Auxiliar de bodega\",\n      \"contract_type\": \"Full-time fixed-term\",\n      \"hire_date\": \"2026-02-01\",\n      \"contract_end_date\": \"2027-01-31\",\n      \"work_shifts\": [\n        {\n          \"day\": \"Monday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Tuesday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Wednesday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Thursday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Friday\",\n          \"start\": \"07:00\",\n          \"end\": \"16:00\"\n        },\n        {\n          \"day\": \"Saturday\",\n          \"start\": \"08:00\",\n          \"end\": \"12:00\"\n        }\n      ],\n      \"vacation_days\": 15\n    },\n    {\n      \"external_id\": \"SIESA-000087\",\n      \"job_title\": \"Conductor de reparto\"\n    },\n    {\n      \"external_id\": \"SIESA-000150\",\n      \"first_name\": \"Camilo\"\n    }\n  ]\n}","options":{"raw":{"language":"json"}}}},"status":"Aceptado: se procesa en segundo plano","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"job_id\": \"0b8c6d4e-2f1a-4c3b-9e5d-7a6b8c9d0e1f\",\n  \"status\": \"queued\"\n}"}]},{"name":"Consultar una importación","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/import/:job_id","host":["{{baseUrl}}"],"path":["employees","import",":job_id"],"variable":[{"key":"job_id","value":"0b8c6d4e-2f1a-4c3b-9e5d-7a6b8c9d0e1f","description":"`job_id` devuelto al crear la importación."}]},"description":"Progreso (`status`: `queued` → `processing` → `completed` | `failed`) y resultado\npor fila (`created`, `updated` o `failed` con `error_code` y `error_message`).\nConsulta cada pocos segundos hasta que `status` sea `completed` o `failed`. Un\njob de otra empresa o de otro entorno (live/test) responde `404`.\n\nScope: `employees:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/import/:job_id","host":["{{baseUrl}}"],"path":["employees","import",":job_id"],"variable":[{"key":"job_id","value":"0b8c6d4e-2f1a-4c3b-9e5d-7a6b8c9d0e1f","description":"`job_id` devuelto al crear la importación."}]},"description":"Progreso (`status`: `queued` → `processing` → `completed` | `failed`) y resultado\npor fila (`created`, `updated` o `failed` con `error_code` y `error_message`).\nConsulta cada pocos segundos hasta que `status` sea `completed` o `failed`. Un\njob de otra empresa o de otro entorno (live/test) responde `404`.\n\nScope: `employees:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"job_id\": \"0b8c6d4e-2f1a-4c3b-9e5d-7a6b8c9d0e1f\",\n  \"status\": \"completed\",\n  \"total_rows\": 3,\n  \"processed_rows\": 3,\n  \"created\": 1,\n  \"updated\": 1,\n  \"failed\": 1,\n  \"created_at\": \"2026-03-02T15:00:00Z\",\n  \"started_at\": \"2026-03-02T15:00:01Z\",\n  \"finished_at\": \"2026-03-02T15:00:04Z\",\n  \"results\": [\n    {\n      \"row_index\": 0,\n      \"external_id\": \"SIESA-000123\",\n      \"status\": \"created\",\n      \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\"\n    },\n    {\n      \"row_index\": 1,\n      \"external_id\": \"SIESA-000087\",\n      \"status\": \"updated\",\n      \"employee_id\": \"5e7b1d93-2a4c-4b6e-8f0a-3c5d7e9f1b26\"\n    },\n    {\n      \"row_index\": 2,\n      \"external_id\": \"SIESA-000150\",\n      \"status\": \"failed\",\n      \"error_code\": \"validation_error\",\n      \"error_message\": \"phone_number: Field required; job_title: Field required\"\n    }\n  ]\n}"}]},{"name":"Obtener un empleado","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id","host":["{{baseUrl}}"],"path":["employees",":id"],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Detalle de un empleado de la empresa. Un id de otra empresa responde `404`.\n\nNota: xYago guarda un único nombre por empresa; `first_name` trae el nombre\ncompleto y `last_name` es siempre `null`.\n\nScope: `employees:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id","host":["{{baseUrl}}"],"path":["employees",":id"],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Detalle de un empleado de la empresa. Un id de otra empresa responde `404`.\n\nNota: xYago guarda un único nombre por empresa; `first_name` trae el nombre\ncompleto y `last_name` es siempre `null`.\n\nScope: `employees:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"external_id\": \"SIESA-000123\",\n  \"first_name\": \"Valentina Rojas Castaño\",\n  \"email\": \"valentina.rojas@example.com\",\n  \"phone_number\": \"+573005550123\",\n  \"document_number\": \"1020304050\",\n  \"job\": {\n    \"id\": \"9d4f6a28-3b1c-4e7d-b5a9-0e2f4c6d8a13\",\n    \"name\": \"Auxiliar de bodega\"\n  },\n  \"area_ids\": [\n    \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\"\n  ],\n  \"status\": \"active\",\n  \"contract_type\": \"Full-time fixed-term\",\n  \"hire_date\": \"2026-02-01\",\n  \"contract_end_date\": \"2027-01-31\"\n}"}]},{"name":"Editar un empleado","request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id","host":["{{baseUrl}}"],"path":["employees",":id"],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Edición parcial: solo se cambian los campos enviados (al menos uno; `null` no\nestá permitido). Mismos campos que el alta salvo `work_shifts` y\n`vacation_days`. Emite `employee.updated`.\n\nScope: `employees:write`.","body":{"mode":"raw","raw":"{\n  \"email\": \"valentina.rojas@example.com\",\n  \"job_title\": \"Coordinadora de bodega\"\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200 OK","originalRequest":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id","host":["{{baseUrl}}"],"path":["employees",":id"],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Edición parcial: solo se cambian los campos enviados (al menos uno; `null` no\nestá permitido). Mismos campos que el alta salvo `work_shifts` y\n`vacation_days`. Emite `employee.updated`.\n\nScope: `employees:write`.","body":{"mode":"raw","raw":"{\n  \"email\": \"valentina.rojas@example.com\",\n  \"job_title\": \"Coordinadora de bodega\"\n}","options":{"raw":{"language":"json"}}}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"external_id\": \"SIESA-000123\",\n  \"first_name\": \"Valentina Rojas Castaño\",\n  \"email\": \"valentina.rojas@example.com\",\n  \"phone_number\": \"+573005550123\",\n  \"document_number\": \"1020304050\",\n  \"job\": {\n    \"id\": \"9d4f6a28-3b1c-4e7d-b5a9-0e2f4c6d8a13\",\n    \"name\": \"Auxiliar de bodega\"\n  },\n  \"area_ids\": [\n    \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\"\n  ],\n  \"status\": \"active\",\n  \"contract_type\": \"Full-time fixed-term\",\n  \"hire_date\": \"2026-02-01\",\n  \"contract_end_date\": \"2027-01-31\"\n}"}]},{"name":"Desactivar un empleado","request":{"method":"POST","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id/deactivate","host":["{{baseUrl}}"],"path":["employees",":id","deactivate"],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Desactiva al empleado en la empresa (mismo cambio de estado que el panel; no lo\nborra ni lo desvincula). Idempotente: si ya estaba inactivo responde `200` sin\ncambios. Emite `employee.deactivated` solo cuando cambia el estado.\n\nScope: `employees:write`."},"response":[{"name":"200 OK","originalRequest":{"method":"POST","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id/deactivate","host":["{{baseUrl}}"],"path":["employees",":id","deactivate"],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Desactiva al empleado en la empresa (mismo cambio de estado que el panel; no lo\nborra ni lo desvincula). Idempotente: si ya estaba inactivo responde `200` sin\ncambios. Emite `employee.deactivated` solo cuando cambia el estado.\n\nScope: `employees:write`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"external_id\": \"SIESA-000123\",\n  \"first_name\": \"Valentina Rojas Castaño\",\n  \"email\": \"valentina.rojas@example.com\",\n  \"phone_number\": \"+573005550123\",\n  \"document_number\": \"1020304050\",\n  \"job\": {\n    \"id\": \"9d4f6a28-3b1c-4e7d-b5a9-0e2f4c6d8a13\",\n    \"name\": \"Auxiliar de bodega\"\n  },\n  \"area_ids\": [\n    \"8b3e9f12-7c4d-4e5a-9b6c-1d2e3f405162\"\n  ],\n  \"status\": \"inactive\",\n  \"contract_type\": \"Full-time fixed-term\",\n  \"hire_date\": \"2026-02-01\",\n  \"contract_end_date\": \"2027-01-31\"\n}"}]}]},{"name":"Vacaciones","description":"Solicitudes de vacaciones (alta, aprobación, rechazo) y saldo anual. Scopes `vacations:read` y `vacations:write`.","item":[{"name":"Listar solicitudes de vacaciones","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations","host":["{{baseUrl}}"],"path":["vacations"],"query":[{"key":"status","value":"","description":"Filtra por estado.","disabled":true},{"key":"employee_id","value":"","description":"Filtra por empleado (uno de otra empresa devuelve una lista vacía).","disabled":true},{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Solicitudes de vacaciones de la empresa, de la más reciente a la más antigua.\n\nScope: `vacations:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations","host":["{{baseUrl}}"],"path":["vacations"],"query":[{"key":"status","value":"","description":"Filtra por estado.","disabled":true},{"key":"employee_id","value":"","description":"Filtra por empleado (uno de otra empresa devuelve una lista vacía).","disabled":true},{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Solicitudes de vacaciones de la empresa, de la más reciente a la más antigua.\n\nScope: `vacations:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"65f1a2b3c4d5e6f708192a3b\",\n      \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n      \"start_date\": \"2026-12-21\",\n      \"end_date\": \"2027-01-08\",\n      \"days\": 13,\n      \"status\": \"pending\",\n      \"reason\": \"Vacaciones de fin de año\",\n      \"created_at\": \"2026-11-03T13:20:00Z\"\n    },\n    {\n      \"id\": \"65f1a2b3c4d5e6f708192a3b\",\n      \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n      \"start_date\": \"2026-12-21\",\n      \"end_date\": \"2027-01-08\",\n      \"days\": 13,\n      \"status\": \"approved\",\n      \"reason\": \"Vacaciones de fin de año\",\n      \"created_at\": \"2026-11-03T13:20:00Z\",\n      \"decided_at\": \"2026-11-04T15:02:00Z\"\n    }\n  ]\n}"}]},{"name":"Solicitar vacaciones para un empleado","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations","host":["{{baseUrl}}"],"path":["vacations"]},"description":"Crea una solicitud de días completos (`start_date`..`end_date`, ambos incluidos,\nmáximo 366 días), igual que el alta desde el panel. Queda `pending`, o\n`approved` si el tipo de vacaciones de la empresa no requiere aprobación.\nEmite `vacation.requested`.\n\nScope: `vacations:write`.","body":{"mode":"raw","raw":"{\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"start_date\": \"2026-12-21\",\n  \"end_date\": \"2027-01-08\",\n  \"reason\": \"Vacaciones de fin de año\"\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201 Creado","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations","host":["{{baseUrl}}"],"path":["vacations"]},"description":"Crea una solicitud de días completos (`start_date`..`end_date`, ambos incluidos,\nmáximo 366 días), igual que el alta desde el panel. Queda `pending`, o\n`approved` si el tipo de vacaciones de la empresa no requiere aprobación.\nEmite `vacation.requested`.\n\nScope: `vacations:write`.","body":{"mode":"raw","raw":"{\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"start_date\": \"2026-12-21\",\n  \"end_date\": \"2027-01-08\",\n  \"reason\": \"Vacaciones de fin de año\"\n}","options":{"raw":{"language":"json"}}}},"status":"Creado","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"65f1a2b3c4d5e6f708192a3b\",\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"start_date\": \"2026-12-21\",\n  \"end_date\": \"2027-01-08\",\n  \"days\": 13,\n  \"status\": \"pending\",\n  \"reason\": \"Vacaciones de fin de año\",\n  \"created_at\": \"2026-11-03T13:20:00Z\"\n}"}]},{"name":"Aprobar una solicitud de vacaciones","request":{"method":"PATCH","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations/:id/approve","host":["{{baseUrl}}"],"path":["vacations",":id","approve"],"variable":[{"key":"id","value":"65f1a2b3c4d5e6f708192a3b","description":"Id de la solicitud (24 caracteres hexadecimales)."}]},"description":"Aprueba una solicitud `pending` (con los mismos efectos que desde el panel). Una\nsolicitud ya decidida responde `409 vacation_already_decided`. Emite\n`vacation.approved`.\n\nScope: `vacations:write`."},"response":[{"name":"200 OK","originalRequest":{"method":"PATCH","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations/:id/approve","host":["{{baseUrl}}"],"path":["vacations",":id","approve"],"variable":[{"key":"id","value":"65f1a2b3c4d5e6f708192a3b","description":"Id de la solicitud (24 caracteres hexadecimales)."}]},"description":"Aprueba una solicitud `pending` (con los mismos efectos que desde el panel). Una\nsolicitud ya decidida responde `409 vacation_already_decided`. Emite\n`vacation.approved`.\n\nScope: `vacations:write`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"65f1a2b3c4d5e6f708192a3b\",\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"start_date\": \"2026-12-21\",\n  \"end_date\": \"2027-01-08\",\n  \"days\": 13,\n  \"status\": \"approved\",\n  \"reason\": \"Vacaciones de fin de año\",\n  \"created_at\": \"2026-11-03T13:20:00Z\",\n  \"decided_at\": \"2026-11-04T15:02:00Z\"\n}"}]},{"name":"Rechazar una solicitud de vacaciones","request":{"method":"PATCH","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations/:id/reject","host":["{{baseUrl}}"],"path":["vacations",":id","reject"],"variable":[{"key":"id","value":"65f1a2b3c4d5e6f708192a3b","description":"Id de la solicitud (24 caracteres hexadecimales)."}]},"description":"Rechaza una solicitud `pending` (como desde el panel). Una solicitud ya decidida\nresponde `409 vacation_already_decided`. Emite `vacation.rejected`.\n\nScope: `vacations:write`."},"response":[{"name":"200 OK","originalRequest":{"method":"PATCH","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/vacations/:id/reject","host":["{{baseUrl}}"],"path":["vacations",":id","reject"],"variable":[{"key":"id","value":"65f1a2b3c4d5e6f708192a3b","description":"Id de la solicitud (24 caracteres hexadecimales)."}]},"description":"Rechaza una solicitud `pending` (como desde el panel). Una solicitud ya decidida\nresponde `409 vacation_already_decided`. Emite `vacation.rejected`.\n\nScope: `vacations:write`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"65f1a2b3c4d5e6f708192a3b\",\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"start_date\": \"2026-12-21\",\n  \"end_date\": \"2027-01-08\",\n  \"days\": 13,\n  \"status\": \"rejected\",\n  \"reason\": \"Vacaciones de fin de año\",\n  \"created_at\": \"2026-11-03T13:20:00Z\",\n  \"decided_at\": \"2026-11-04T15:02:00Z\"\n}"}]},{"name":"Saldo de vacaciones de un empleado","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id/vacation-balance","host":["{{baseUrl}}"],"path":["employees",":id","vacation-balance"],"query":[{"key":"year","value":"","description":"Año (por defecto el año en curso, UTC).","disabled":true}],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Días que corresponden en el año (`total_days`, prorrateados), usados\n(solicitudes aprobadas que empiezan ese año) y disponibles. Un empleado de otra\nempresa responde `404`.\n\nScope: `vacations:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/employees/:id/vacation-balance","host":["{{baseUrl}}"],"path":["employees",":id","vacation-balance"],"query":[{"key":"year","value":"","description":"Año (por defecto el año en curso, UTC).","disabled":true}],"variable":[{"key":"id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado."}]},"description":"Días que corresponden en el año (`total_days`, prorrateados), usados\n(solicitudes aprobadas que empiezan ese año) y disponibles. Un empleado de otra\nempresa responde `404`.\n\nScope: `vacations:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"year\": 2026,\n  \"total_days\": 15.0,\n  \"used_days\": 6.0,\n  \"available_days\": 9.0\n}"}]}]},{"name":"Registro de horas","description":"Tramos de trabajo cerrados de los empleados. Scopes `time:read` y `time:write`.","item":[{"name":"Listar tramos de horas de un empleado","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/time-entries?employee_id=2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54&from=2026-03-01&to=2026-03-07","host":["{{baseUrl}}"],"path":["time-entries"],"query":[{"key":"employee_id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado.","disabled":false},{"key":"from","value":"2026-03-01","description":"Primer día (UTC), incluido.","disabled":false},{"key":"to","value":"2026-03-07","description":"Último día (UTC), incluido. Máximo 31 días desde `from`.","disabled":false},{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Tramos trabajados (cerrados) del empleado en la empresa que tocan el rango\n`from`..`to` (días UTC, máximo 31 días), del más reciente al más antiguo.\nUn empleado de otra empresa responde `404`.\n\nScope: `time:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/time-entries?employee_id=2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54&from=2026-03-01&to=2026-03-07","host":["{{baseUrl}}"],"path":["time-entries"],"query":[{"key":"employee_id","value":"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54","description":"Id del empleado.","disabled":false},{"key":"from","value":"2026-03-01","description":"Primer día (UTC), incluido.","disabled":false},{"key":"to","value":"2026-03-07","description":"Último día (UTC), incluido. Máximo 31 días desde `from`.","disabled":false},{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Tramos trabajados (cerrados) del empleado en la empresa que tocan el rango\n`from`..`to` (días UTC, máximo 31 días), del más reciente al más antiguo.\nUn empleado de otra empresa responde `404`.\n\nScope: `time:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"c4e2a6f8-1b3d-4a5c-8e7f-9a0b1c2d3e4f\",\n      \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n      \"started_at\": \"2026-03-02T12:00:00Z\",\n      \"ended_at\": \"2026-03-02T21:00:00Z\",\n      \"duration_minutes\": 540,\n      \"source\": \"api\",\n      \"note\": \"Turno registrado desde Siesa\",\n      \"created_at\": \"2026-03-02T21:05:00Z\"\n    }\n  ]\n}"}]},{"name":"Registrar un tramo de horas","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/time-entries","host":["{{baseUrl}}"],"path":["time-entries"]},"description":"Registra un tramo trabajado ya terminado (el mismo registro manual que la app).\nFechas ISO 8601; sin zona horaria se interpretan en UTC (envía el offset, p. ej.\n`-05:00` para Colombia). `ended_at` posterior a `started_at`, como máximo 24 h y\nno en el futuro. Emite el webhook `time_entry.created`.\n\nScope: `time:write`.","body":{"mode":"raw","raw":"{\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"started_at\": \"2026-03-02T07:00:00-05:00\",\n  \"ended_at\": \"2026-03-02T16:00:00-05:00\",\n  \"note\": \"Turno registrado desde Siesa\"\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201 Creado","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/time-entries","host":["{{baseUrl}}"],"path":["time-entries"]},"description":"Registra un tramo trabajado ya terminado (el mismo registro manual que la app).\nFechas ISO 8601; sin zona horaria se interpretan en UTC (envía el offset, p. ej.\n`-05:00` para Colombia). `ended_at` posterior a `started_at`, como máximo 24 h y\nno en el futuro. Emite el webhook `time_entry.created`.\n\nScope: `time:write`.","body":{"mode":"raw","raw":"{\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"started_at\": \"2026-03-02T07:00:00-05:00\",\n  \"ended_at\": \"2026-03-02T16:00:00-05:00\",\n  \"note\": \"Turno registrado desde Siesa\"\n}","options":{"raw":{"language":"json"}}}},"status":"Creado","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"c4e2a6f8-1b3d-4a5c-8e7f-9a0b1c2d3e4f\",\n  \"employee_id\": \"2c9a4e71-5b3d-4f8e-a6c2-7d1e0f9b3a54\",\n  \"started_at\": \"2026-03-02T12:00:00Z\",\n  \"ended_at\": \"2026-03-02T21:00:00Z\",\n  \"duration_minutes\": 540,\n  \"source\": \"api\",\n  \"note\": \"Turno registrado desde Siesa\",\n  \"created_at\": \"2026-03-02T21:05:00Z\"\n}"}]}]},{"name":"Mensajes","description":"Notificaciones con plantilla a usuarios de xYago por el chat de la app, desde un remitente verificado. Si el destinatario aún no tiene xYago el mensaje espera hasta 7 días (`pending_install`). Scopes `messages:write` y `messages:read`. Guía: [Mensajes](https://api.xyago.com/v1/docs/es/messages).","item":[{"name":"Listar envíos","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/messages","host":["{{baseUrl}}"],"path":["messages"],"query":[{"key":"status","value":"","description":"Filtra por estado.","disabled":true},{"key":"sender_id","value":"","description":"Filtra por remitente (`business_id`).","disabled":true},{"key":"reference","value":"","description":"Filtra por tu `reference`.","disabled":true},{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Envíos del entorno de la API key (live o sandbox), del más reciente al más\nantiguo. Nunca incluye el texto ni el teléfono completo.\n\nScope: `messages:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/messages","host":["{{baseUrl}}"],"path":["messages"],"query":[{"key":"status","value":"","description":"Filtra por estado.","disabled":true},{"key":"sender_id","value":"","description":"Filtra por remitente (`business_id`).","disabled":true},{"key":"reference","value":"","description":"Filtra por tu `reference`.","disabled":true},{"key":"cursor","value":"","description":"Cursor opaco de la página siguiente (`next_cursor` de la respuesta anterior). Omitir en la primera petición.","disabled":true},{"key":"limit","value":"50","description":"Tamaño de página (1-100, por defecto 50).","disabled":true}]},"description":"Envíos del entorno de la API key (live o sandbox), del más reciente al más\nantiguo. Nunca incluye el texto ni el teléfono completo.\n\nScope: `messages:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"3e5a7c91-4b6d-4e8f-a0c2-5d7f9b1e3a64\",\n      \"status\": \"pending_install\",\n      \"to_masked\": \"+57 ••• ••• 0187\",\n      \"sender_id\": \"tiendaexpress\",\n      \"template\": \"pedido_enviado\",\n      \"language\": \"es\",\n      \"reference\": \"CLI-000087\",\n      \"created_at\": \"2026-11-04T15:00:00Z\",\n      \"expires_at\": \"2026-11-11T15:00:00Z\"\n    },\n    {\n      \"id\": \"7a1c9e35-2b4d-4f6a-8c0e-1d3f5a7b9c21\",\n      \"status\": \"read\",\n      \"to_masked\": \"+57 ••• ••• 0123\",\n      \"sender_id\": \"tiendaexpress\",\n      \"template\": \"pedido_enviado\",\n      \"language\": \"es\",\n      \"reference\": \"CLI-000123\",\n      \"created_at\": \"2026-11-04T15:00:00Z\",\n      \"sent_at\": \"2026-11-04T15:00:01Z\",\n      \"delivered_at\": \"2026-11-04T15:02:10Z\",\n      \"read_at\": \"2026-11-04T15:07:42Z\"\n    }\n  ],\n  \"next_cursor\": \"eyJ0IjogIjIwMjYtMTEtMDRUMTU6MDA6MDAiLCAiaWQiOiAiN2ExYyJ9\"\n}"}]},{"name":"Enviar una notificación con plantilla","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Obligatoria. Clave única por envío (8-128 caracteres `[A-Za-z0-9._:-]`, p. ej. un UUID o el id del aviso en tu sistema). Un reintento con la misma clave nunca duplica el mensaje."},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/messages","host":["{{baseUrl}}"],"path":["messages"]},"description":"Envía la plantilla `template` del remitente `sender_id` al teléfono `to` por el\nchat de xYago. Solo plantillas aprobadas por xYago (en sandbox también `draft`) y\nsolo remitentes aprobados (en sandbox cualquiera de la cuenta, a los números de\nprueba confirmados en el panel).\n\n- Si el destinatario aún no usa xYago el mensaje queda `pending_install` hasta 7\n  días y se entrega en cuanto instale la app y verifique su número (webhook\n  `message.sent`); si no, termina `failed` con `recipient_not_on_xyago`\n  (webhook `message.failed`).\n- Si el destinatario no puede recibir mensajes del remitente responde\n  `409 undeliverable` (no reintentes).\n- Topes por remitente: mensajes por minuto (el límite del producto), por\n  destinatario y día y destinatarios nuevos por día → `429 rate_limited`.\n- Botones: los de la plantilla se envían tal cual; si un botón `url` lleva\n  `{{1}}`, su valor va en `button_variables` (por índice del botón). Una\n  respuesta rápida pulsada llega como webhook `message.button_clicked`.\n\nScope: `messages:write`.","body":{"mode":"raw","raw":"{\n  \"to\": \"+573005550123\",\n  \"sender_id\": \"tiendaexpress\",\n  \"template\": \"pedido_enviado\",\n  \"language\": \"es\",\n  \"variables\": [\n    \"Valentina\",\n    \"TE-48213\"\n  ],\n  \"reference\": \"CLI-000123\",\n  \"button_variables\": {\n    \"0\": \"TE-48213\"\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"202 Aceptado: entregado al chat (`sent`) o en espera de que el destinatario instale xYago (`pending_install`). Una repetición con la misma `Idempotency-Key` y el mismo cuerpo responde `200` con el envío original y la cabecera `Idempotent-Replayed: true`.","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Obligatoria. Clave única por envío (8-128 caracteres `[A-Za-z0-9._:-]`, p. ej. un UUID o el id del aviso en tu sistema). Un reintento con la misma clave nunca duplica el mensaje."},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/messages","host":["{{baseUrl}}"],"path":["messages"]},"description":"Envía la plantilla `template` del remitente `sender_id` al teléfono `to` por el\nchat de xYago. Solo plantillas aprobadas por xYago (en sandbox también `draft`) y\nsolo remitentes aprobados (en sandbox cualquiera de la cuenta, a los números de\nprueba confirmados en el panel).\n\n- Si el destinatario aún no usa xYago el mensaje queda `pending_install` hasta 7\n  días y se entrega en cuanto instale la app y verifique su número (webhook\n  `message.sent`); si no, termina `failed` con `recipient_not_on_xyago`\n  (webhook `message.failed`).\n- Si el destinatario no puede recibir mensajes del remitente responde\n  `409 undeliverable` (no reintentes).\n- Topes por remitente: mensajes por minuto (el límite del producto), por\n  destinatario y día y destinatarios nuevos por día → `429 rate_limited`.\n- Botones: los de la plantilla se envían tal cual; si un botón `url` lleva\n  `{{1}}`, su valor va en `button_variables` (por índice del botón). Una\n  respuesta rápida pulsada llega como webhook `message.button_clicked`.\n\nScope: `messages:write`.","body":{"mode":"raw","raw":"{\n  \"to\": \"+573005550123\",\n  \"sender_id\": \"tiendaexpress\",\n  \"template\": \"pedido_enviado\",\n  \"language\": \"es\",\n  \"variables\": [\n    \"Valentina\",\n    \"TE-48213\"\n  ],\n  \"reference\": \"CLI-000123\",\n  \"button_variables\": {\n    \"0\": \"TE-48213\"\n  }\n}","options":{"raw":{"language":"json"}}}},"status":"Aceptado: entregado al chat (`sent`) o en espera de que el destinatario instale xYago (`pending_install`). Una repetición con la misma `Idempotency-Key` y el mismo cuerpo responde `200` con el envío original y la cabecera `Idempotent-Replayed: true`.","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"7a1c9e35-2b4d-4f6a-8c0e-1d3f5a7b9c21\",\n  \"status\": \"sent\",\n  \"to_masked\": \"+57 ••• ••• 0123\",\n  \"sender_id\": \"tiendaexpress\",\n  \"template\": \"pedido_enviado\",\n  \"language\": \"es\",\n  \"reference\": \"CLI-000123\",\n  \"created_at\": \"2026-11-04T15:00:00Z\",\n  \"sent_at\": \"2026-11-04T15:00:01Z\"\n}"}]},{"name":"Consultar un envío","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/messages/:id","host":["{{baseUrl}}"],"path":["messages",":id"],"variable":[{"key":"id","value":"7a1c9e35-2b4d-4f6a-8c0e-1d3f5a7b9c21","description":"Id del envío (`id` de la respuesta de `POST /messages`)."}]},"description":"Estado actual de un envío. Un envío de otra cuenta o del otro entorno responde\n`404`.\n\nScope: `messages:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/messages/:id","host":["{{baseUrl}}"],"path":["messages",":id"],"variable":[{"key":"id","value":"7a1c9e35-2b4d-4f6a-8c0e-1d3f5a7b9c21","description":"Id del envío (`id` de la respuesta de `POST /messages`)."}]},"description":"Estado actual de un envío. Un envío de otra cuenta o del otro entorno responde\n`404`.\n\nScope: `messages:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"7a1c9e35-2b4d-4f6a-8c0e-1d3f5a7b9c21\",\n  \"status\": \"read\",\n  \"to_masked\": \"+57 ••• ••• 0123\",\n  \"sender_id\": \"tiendaexpress\",\n  \"template\": \"pedido_enviado\",\n  \"language\": \"es\",\n  \"reference\": \"CLI-000123\",\n  \"created_at\": \"2026-11-04T15:00:00Z\",\n  \"sent_at\": \"2026-11-04T15:00:01Z\",\n  \"delivered_at\": \"2026-11-04T15:02:10Z\",\n  \"read_at\": \"2026-11-04T15:07:42Z\"\n}"}]}]},{"name":"Remitentes","description":"Remitentes de la cuenta (perfil verificado en la app) y su estado de revisión. Se crean en el panel. Scope `messages:read`.","item":[{"name":"Listar remitentes","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/senders","host":["{{baseUrl}}"],"path":["senders"]},"description":"Remitentes de la cuenta en cualquier estado (`draft`, `pending_review`,\n`approved`, `rejected`, `suspended`). Se crean y envían a revisión en el panel.\n\nScope: `messages:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/senders","host":["{{baseUrl}}"],"path":["senders"]},"description":"Remitentes de la cuenta en cualquier estado (`draft`, `pending_review`,\n`approved`, `rejected`, `suspended`). Se crean y envían a revisión en el panel.\n\nScope: `messages:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"tiendaexpress\",\n      \"display_name\": \"Tienda Express\",\n      \"logo_url\": \"https://cdn.tiendaexpress.example.com/logo.png\",\n      \"description\": \"Avisos de tus pedidos de Tienda Express.\",\n      \"website\": \"https://tiendaexpress.example.com\",\n      \"category\": \"comercio\",\n      \"status\": \"approved\",\n      \"verified\": true,\n      \"new_recipients_paused\": false,\n      \"invite_url\": \"https://web.xyago.com/app/b/tiendaexpress\",\n      \"created_at\": \"2026-11-02T14:00:00Z\",\n      \"updated_at\": \"2026-11-03T09:30:00Z\"\n    }\n  ]\n}"}]},{"name":"Consultar un remitente","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/senders/:id","host":["{{baseUrl}}"],"path":["senders",":id"],"variable":[{"key":"id","value":"tiendaexpress","description":"`business_id` del remitente."}]},"description":"Perfil y estado de revisión de un remitente de la cuenta (otro → `404`).\n\nScope: `messages:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/senders/:id","host":["{{baseUrl}}"],"path":["senders",":id"],"variable":[{"key":"id","value":"tiendaexpress","description":"`business_id` del remitente."}]},"description":"Perfil y estado de revisión de un remitente de la cuenta (otro → `404`).\n\nScope: `messages:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"tiendaexpress\",\n  \"display_name\": \"Tienda Express\",\n  \"logo_url\": \"https://cdn.tiendaexpress.example.com/logo.png\",\n  \"description\": \"Avisos de tus pedidos de Tienda Express.\",\n  \"website\": \"https://tiendaexpress.example.com\",\n  \"category\": \"comercio\",\n  \"status\": \"approved\",\n  \"verified\": true,\n  \"new_recipients_paused\": false,\n  \"invite_url\": \"https://web.xyago.com/app/b/tiendaexpress\",\n  \"created_at\": \"2026-11-02T14:00:00Z\",\n  \"updated_at\": \"2026-11-03T09:30:00Z\"\n}"}]}]},{"name":"Plantillas","description":"Plantillas de notificación (`utility`) y su estado de aprobación. Se crean en el panel y las aprueba xYago. Scope `messages:read`.","item":[{"name":"Listar plantillas","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/templates","host":["{{baseUrl}}"],"path":["templates"],"query":[{"key":"sender_id","value":"","description":"Filtra por remitente (`business_id`).","disabled":true}]},"description":"Plantillas de la cuenta con su estado de aprobación, más recientes primero. Se\ncrean en el panel y las aprueba xYago. No incluye las versiones sustituidas\n(`superseded`); se pueden consultar por id.\n\nScope: `messages:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/templates","host":["{{baseUrl}}"],"path":["templates"],"query":[{"key":"sender_id","value":"","description":"Filtra por remitente (`business_id`).","disabled":true}]},"description":"Plantillas de la cuenta con su estado de aprobación, más recientes primero. Se\ncrean en el panel y las aprueba xYago. No incluye las versiones sustituidas\n(`superseded`); se pueden consultar por id.\n\nScope: `messages:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"results\": [\n    {\n      \"id\": \"d2f4a6c8-0e1b-4d3f-9a5c-7e9b1d3f5a70\",\n      \"sender_id\": \"tiendaexpress\",\n      \"name\": \"pedido_enviado\",\n      \"category\": \"utility\",\n      \"default_language\": \"es\",\n      \"languages\": {\n        \"es\": \"Hola {{1}}, tu pedido {{2}} va en camino.\",\n        \"en\": \"Hi {{1}}, your order {{2}} is on its way.\"\n      },\n      \"variables_count\": 2,\n      \"buttons\": [\n        {\n          \"type\": \"url\",\n          \"texts\": {\n            \"es\": \"Seguir pedido\",\n            \"en\": \"Track order\"\n          },\n          \"url\": \"https://tiendaexpress.example.com/pedidos/{{1}}\"\n        },\n        {\n          \"type\": \"quick_reply\",\n          \"texts\": {\n            \"es\": \"No lo pedí\",\n            \"en\": \"Not my order\"\n          },\n          \"payload\": \"order_not_mine\"\n        }\n      ],\n      \"version\": 1,\n      \"status\": \"approved\",\n      \"review_flags\": [],\n      \"created_at\": \"2026-11-03T10:00:00Z\",\n      \"updated_at\": \"2026-11-03T16:45:00Z\"\n    }\n  ]\n}"}]},{"name":"Consultar una plantilla","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/templates/:id","host":["{{baseUrl}}"],"path":["templates",":id"],"variable":[{"key":"id","value":"d2f4a6c8-0e1b-4d3f-9a5c-7e9b1d3f5a70","description":"Id de la plantilla."}]},"description":"Una plantilla de la cuenta (otra → `404`).\n\nScope: `messages:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/templates/:id","host":["{{baseUrl}}"],"path":["templates",":id"],"variable":[{"key":"id","value":"d2f4a6c8-0e1b-4d3f-9a5c-7e9b1d3f5a70","description":"Id de la plantilla."}]},"description":"Una plantilla de la cuenta (otra → `404`).\n\nScope: `messages:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"d2f4a6c8-0e1b-4d3f-9a5c-7e9b1d3f5a70\",\n  \"sender_id\": \"tiendaexpress\",\n  \"name\": \"pedido_enviado\",\n  \"category\": \"utility\",\n  \"default_language\": \"es\",\n  \"languages\": {\n    \"es\": \"Hola {{1}}, tu pedido {{2}} va en camino.\",\n    \"en\": \"Hi {{1}}, your order {{2}} is on its way.\"\n  },\n  \"variables_count\": 2,\n  \"buttons\": [\n    {\n      \"type\": \"url\",\n      \"texts\": {\n        \"es\": \"Seguir pedido\",\n        \"en\": \"Track order\"\n      },\n      \"url\": \"https://tiendaexpress.example.com/pedidos/{{1}}\"\n    },\n    {\n      \"type\": \"quick_reply\",\n      \"texts\": {\n        \"es\": \"No lo pedí\",\n        \"en\": \"Not my order\"\n      },\n      \"payload\": \"order_not_mine\"\n    }\n  ],\n  \"version\": 1,\n  \"status\": \"approved\",\n  \"review_flags\": [],\n  \"created_at\": \"2026-11-03T10:00:00Z\",\n  \"updated_at\": \"2026-11-03T16:45:00Z\"\n}"}]}]},{"name":"Verify","description":"Códigos de verificación de un solo uso (6 dígitos, 10 minutos, 5 intentos) por el chat de xYago, para inicio de sesión, registro o confirmación de operaciones. Si el teléfono no usa xYago se responde al momento para que envíes el código por SMS. Scopes `verify:write` y `verify:read`. Guía: [Verify](https://api.xyago.com/v1/docs/es/verify).","item":[{"name":"Enviar un código de verificación","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Obligatoria. Clave única por código pedido (8-128 caracteres `[A-Za-z0-9._:-]`, p. ej. un UUID). Un reintento con la misma clave nunca envía dos códigos."},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/verify/start","host":["{{baseUrl}}"],"path":["verify","start"]},"description":"Genera un código de 6 dígitos (válido 10 minutos, 5 intentos) y lo envía al\nteléfono `to` por el chat de xYago, en nombre del remitente `sender_id`, con un\ntexto fijo de xYago en el idioma `language` (la empresa no puede cambiarlo). El\ncódigo nunca se devuelve: el usuario lo escribe en tu app y lo compruebas con\n`POST /verify/check`.\n\n- Si el teléfono no usa xYago responde `404 recipient_not_on_xyago` al momento\n  (sin espera ni reintento): envía el código por tu otro canal (p. ej. SMS).\n- Si el usuario no puede recibir mensajes del remitente: `409 undeliverable`.\n- Un nuevo código al mismo teléfono sustituye al anterior (que pasa a\n  `canceled`). Entre dos códigos al mismo teléfono hay que esperar 30 s; además\n  hay topes por teléfono y por remitente → `429 rate_limited` con `Retry-After`.\n- Si la respuesta se pierde (timeout, `502`), repite con la misma\n  `Idempotency-Key` y el mismo cuerpo: si el código ya llegó al chat recibes la\n  misma verificación. Si no llegó, se envía uno nuevo (el anterior deja de\n  valer) con la misma espera de 30 s desde el intento anterior, los mismos\n  topes (`429 rate_limited` con `Retry-After`) y la pausa de Verify.\n- Sandbox (`xy_test_`): solo a los números de prueba confirmados en el panel.\n\nScope: `verify:write`.","body":{"mode":"raw","raw":"{\n  \"to\": \"+573005550123\",\n  \"sender_id\": \"tiendaexpress\",\n  \"language\": \"es\",\n  \"reference\": \"login-CLI-000123\"\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201 Código enviado al chat de xYago del usuario (`pending`, `delivery_status: sent`). Una repetición con la misma `Idempotency-Key` y el mismo cuerpo responde `200` con la verificación original y la cabecera `Idempotent-Replayed: true`. La respuesta nunca contiene el código.","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Idempotency-Key","value":"{{$guid}}","description":"Obligatoria. Clave única por código pedido (8-128 caracteres `[A-Za-z0-9._:-]`, p. ej. un UUID). Un reintento con la misma clave nunca envía dos códigos."},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/verify/start","host":["{{baseUrl}}"],"path":["verify","start"]},"description":"Genera un código de 6 dígitos (válido 10 minutos, 5 intentos) y lo envía al\nteléfono `to` por el chat de xYago, en nombre del remitente `sender_id`, con un\ntexto fijo de xYago en el idioma `language` (la empresa no puede cambiarlo). El\ncódigo nunca se devuelve: el usuario lo escribe en tu app y lo compruebas con\n`POST /verify/check`.\n\n- Si el teléfono no usa xYago responde `404 recipient_not_on_xyago` al momento\n  (sin espera ni reintento): envía el código por tu otro canal (p. ej. SMS).\n- Si el usuario no puede recibir mensajes del remitente: `409 undeliverable`.\n- Un nuevo código al mismo teléfono sustituye al anterior (que pasa a\n  `canceled`). Entre dos códigos al mismo teléfono hay que esperar 30 s; además\n  hay topes por teléfono y por remitente → `429 rate_limited` con `Retry-After`.\n- Si la respuesta se pierde (timeout, `502`), repite con la misma\n  `Idempotency-Key` y el mismo cuerpo: si el código ya llegó al chat recibes la\n  misma verificación. Si no llegó, se envía uno nuevo (el anterior deja de\n  valer) con la misma espera de 30 s desde el intento anterior, los mismos\n  topes (`429 rate_limited` con `Retry-After`) y la pausa de Verify.\n- Sandbox (`xy_test_`): solo a los números de prueba confirmados en el panel.\n\nScope: `verify:write`.","body":{"mode":"raw","raw":"{\n  \"to\": \"+573005550123\",\n  \"sender_id\": \"tiendaexpress\",\n  \"language\": \"es\",\n  \"reference\": \"login-CLI-000123\"\n}","options":{"raw":{"language":"json"}}}},"status":"Código enviado al chat de xYago del usuario (`pending`, `delivery_status: sent`). Una repetición con la misma `Idempotency-Key` y el mismo cuerpo responde `200` con la verificación original y la cabecera `Idempotent-Replayed: true`. La respuesta nunca contiene el código.","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59\",\n  \"object\": \"verification\",\n  \"sender_id\": \"tiendaexpress\",\n  \"to_masked\": \"+57 ••• ••• 0123\",\n  \"channel\": \"xyago_chat\",\n  \"language\": \"es\",\n  \"reference\": \"login-CLI-000123\",\n  \"status\": \"pending\",\n  \"delivery_status\": \"sent\",\n  \"attempts\": 0,\n  \"max_attempts\": 5,\n  \"expires_at\": \"2026-11-04T15:10:00Z\",\n  \"created_at\": \"2026-11-04T15:00:00Z\"\n}"}]},{"name":"Comprobar un código","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/verify/check","host":["{{baseUrl}}"],"path":["verify","check"]},"description":"Comprueba el código que escribió el usuario. Correcto → `valid: true`,\n`status: verified` (un solo uso: otra comprobación responde\n`409 verification_not_pending`). Erróneo → `200` con `valid: false` y\n`attempts_remaining`; al quinto error la verificación pasa a `too_many_attempts`.\nCaducada (10 min) → `409 verification_expired`. Una verificación de otra cuenta\no del otro entorno → `404`. Hay además un tope de códigos erróneos por teléfono\ny hora (`429 rate_limited`).\n\nScope: `verify:write`.","body":{"mode":"raw","raw":"{\n  \"verification_id\": \"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59\",\n  \"code\": \"482913\"\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200 Resultado de la comprobación: `valid: true` (verificada; el código ya no sirve) o `valid: false` con los intentos que quedan.","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/verify/check","host":["{{baseUrl}}"],"path":["verify","check"]},"description":"Comprueba el código que escribió el usuario. Correcto → `valid: true`,\n`status: verified` (un solo uso: otra comprobación responde\n`409 verification_not_pending`). Erróneo → `200` con `valid: false` y\n`attempts_remaining`; al quinto error la verificación pasa a `too_many_attempts`.\nCaducada (10 min) → `409 verification_expired`. Una verificación de otra cuenta\no del otro entorno → `404`. Hay además un tope de códigos erróneos por teléfono\ny hora (`429 rate_limited`).\n\nScope: `verify:write`.","body":{"mode":"raw","raw":"{\n  \"verification_id\": \"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59\",\n  \"code\": \"482913\"\n}","options":{"raw":{"language":"json"}}}},"status":"Resultado de la comprobación: `valid: true` (verificada; el código ya no sirve) o `valid: false` con los intentos que quedan.","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59\",\n  \"valid\": true,\n  \"status\": \"verified\",\n  \"attempts_remaining\": 0\n}"}]},{"name":"Consultar una verificación","request":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/verify/:id","host":["{{baseUrl}}"],"path":["verify",":id"],"variable":[{"key":"id","value":"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59","description":"Id de la verificación (`id` de `POST /verify/start`)."}]},"description":"Estado actual de una verificación (nunca incluye el código). Una de otra cuenta o\ndel otro entorno responde `404`.\n\nScope: `verify:read`."},"response":[{"name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"X-Request-Id","value":"{{$guid}}","description":"Opcional: identificador propio de la peticion.","disabled":true}],"url":{"raw":"{{baseUrl}}/verify/:id","host":["{{baseUrl}}"],"path":["verify",":id"],"variable":[{"key":"id","value":"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59","description":"Id de la verificación (`id` de `POST /verify/start`)."}]},"description":"Estado actual de una verificación (nunca incluye el código). Una de otra cuenta o\ndel otro entorno responde `404`.\n\nScope: `verify:read`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"3e8b1f6a-9c2d-4a7e-b5f0-6d1c2a3b4e59\",\n  \"object\": \"verification\",\n  \"sender_id\": \"tiendaexpress\",\n  \"to_masked\": \"+57 ••• ••• 0123\",\n  \"channel\": \"xyago_chat\",\n  \"language\": \"es\",\n  \"reference\": \"login-CLI-000123\",\n  \"status\": \"verified\",\n  \"delivery_status\": \"read\",\n  \"attempts\": 1,\n  \"max_attempts\": 5,\n  \"expires_at\": \"2026-11-04T15:10:00Z\",\n  \"verified_at\": \"2026-11-04T15:01:12Z\",\n  \"created_at\": \"2026-11-04T15:00:00Z\"\n}"}]}]}]}