Primeros pasos

La API de xYago conecta tu ERP, tu sistema de nómina o cualquier otro sistema con xYago: sincroniza áreas, empleados, vacaciones y registro de horas, y recibe un webhook firmado cada vez que algo cambia.

URL base (producción y sandbox):

https://api.xyago.com/v1

Todo es JSON en UTF-8, las fechas van en ISO 8601 UTC (2026-03-02T14:05:00Z) y los teléfonos en formato E.164 (+573005550123). La referencia completa de cada endpoint está en la referencia de la API; también puedes descargar el OpenAPI o la colección de Postman.

Tu primera petición en 5 minutos

1. Habilita la API en el sandbox. Un administrador de tu empresa entra en el panel de xYago → API Developer, elige el entorno Test y activa los productos que vas a usar (por ejemplo Áreas y Empleados).
2. Crea una API key de sandbox. En Credenciales → Nueva credencial: ponle un nombre (p. ej. «Siesa pruebas») y marca los scopes que necesitas (areas:read, employees:read...). La clave completa (xy_test_...) se muestra una sola vez: guárdala en tu gestor de secretos.
3. Haz la primera llamada. El sandbox devuelve datos de ejemplo fijos, así que puedes probar sin miedo.

export XYAGO_API_KEY="xy_test_EXAMPLE_replace-with-your-sandbox-key"

curl "https://api.xyago.com/v1/areas?limit=1" \
  -H "Authorization: Bearer $XYAGO_API_KEY"

import os

import requests  # pip install requests

response = requests.get(
    "https://api.xyago.com/v1/areas",
    params={"limit": 1},
    headers={"Authorization": f"Bearer {os.environ['XYAGO_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

// Node.js 18+ (fetch nativo). Guardar como first-call.mjs
const response = await fetch("https://api.xyago.com/v1/areas?limit=1", {
  headers: { Authorization: `Bearer ${process.env.XYAGO_API_KEY}` },
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

using System.Net.Http.Headers;

using var http = new HttpClient { BaseAddress = new Uri("https://api.xyago.com/v1/") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("XYAGO_API_KEY"));

var response = await http.GetAsync("areas?limit=1");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Respuesta (200 OK):

{
  "results": [
    {
      "id": "51f510d8-6482-5355-b5c3-5f511c06d851",
      "public_id": "AR-0002",
      "name": "Administracion",
      "parent_id": null,
      "status": "active",
      "minimum_employees": 1,
      "maximum_employees": 4,
      "skills": [],
      "created_at": "2026-01-17T09:00:00Z",
      "updated_at": "2026-01-17T09:00:00Z"
    }
  ],
  "next_cursor": "eyJ0IjogIjIwMjYtMDEtMTdUMDk6MDA6MDAiLCAiaWQiOiAiNTFmNTEwZDgtNjQ4Mi01MzU1LWI1YzMtNWY1MTFjMDZkODUxIn0"
}

Si recibes 401 invalid_api_key, revisa la cabecera; si es 403 api_disabled, el producto no está activo en el entorno Test del panel. Consulta la tabla de errores.

Qué puedes hacer

Y webhooks para enterarte de los cambios sin consultar continuamente.

Integración típica con un ERP (p. ej. Siesa)

1. Carga inicial: importa la plantilla de empleados con POST /employees/import usando el código de empleado del ERP como external_id.
2. Altas y cambios: cuando el ERP crea o modifica un empleado, llama a POST /employees o PATCH /employees/{id} (busca antes el id de xYago con GET /employees?external_id=...). Ver idempotencia.
3. Retiros: POST /employees/{id}/deactivate.
4. Nómina: lee horas con GET /time-entries y vacaciones con GET /vacations, o suscríbete a time_entry.created y vacation.approved.

Pasar a producción

1. En el panel, entorno Live: activa los mismos productos, configura el límite de peticiones y, recomendado, las IPs permitidas de tu servidor.
2. Crea una credencial xy_live_... con los scopes mínimos necesarios.
3. Registra tus webhooks en el entorno Live y guarda su secreto de firma.
4. Cambia solo la API key: la URL base es la misma.

Nunca incluyas una API key en el código fuente, en una app móvil o en el navegador: la API está pensada para llamadas servidor a servidor.