Control Horario·Legal
Para desarrolladores · API REST v1

API REST

Conecta tus fichajes con tu ERP, tu cuadro de mando o tus propias herramientas. Una API JSON de solo lectura para consultar empleados, centros y fichajes. Disponible en el plan Pro.

§ 01 · Autenticación

Una API key por empresa.

Cada empresa genera su clave desde el panel, en Integraciones (/integraciones), con sesión de RRHH o administración. Puedes crear y revocar claves cuando quieras; al revocarlas dejan de funcionar al instante. Toda petición se filtra automáticamente por tu empresa — solo ves tus propios datos.

Envía la clave en la cabecera X-Api-Key en cada petición:

curl https://controlhorariolegal.com/api/v1/ping \
  -H "X-Api-Key: chl_tu_clave_aqui"

También se acepta Authorization: Bearer chl_tu_clave_aqui. Las peticiones van siempre por HTTPS y las respuestas son JSON con codificación UTF-8.

§ 02 · Endpoints

Base: https://controlhorariolegal.com/api/v1

GET /ping

Comprueba que tu credencial es válida y devuelve los datos básicos de tu empresa y plan.

{
  "ok": true,
  "empresa": "Mi Empresa S.L.",
  "cif": "B12345678",
  "plan": "pro",
  "fecha": "2026-06-18T13:30:00+02:00"
}

GET /empleados

Lista los empleados activos de tu empresa, ordenados por apellidos.

{
  "ok": true,
  "total": 2,
  "empleados": [
    {
      "id": 14,
      "nombre": "Ana",
      "apellidos": "García López",
      "dni": "12345678Z",
      "email": "ana@empresa.es",
      "rol": "empleado",
      "id_centro": 3,
      "requiere_fichaje": true,
      "horas_semana": 40
    }
  ]
}

GET /centros

Lista los centros de trabajo de tu empresa.

{
  "ok": true,
  "total": 1,
  "centros": [
    {
      "id": 3,
      "nombre": "Oficina Central",
      "direccion": "Calle Mayor 1",
      "poblacion": "Madrid",
      "codigo_postal": "28013",
      "fichaje_activo": true
    }
  ]
}

GET /fichajes

Lista fichajes en un rango de fechas. Parámetros opcionales por query string:

  • desde, hasta — formato YYYY-MM-DD. Por defecto, los últimos 30 días. Máximo 366 días por consulta.
  • dni — filtra por un empleado (acepta DNI/NIE o email).
  • id_centro — filtra por un centro.
curl "https://controlhorariolegal.com/api/v1/fichajes?desde=2026-06-01&hasta=2026-06-18" \
  -H "X-Api-Key: chl_tu_clave_aqui"
{
  "ok": true,
  "desde": "2026-06-01",
  "hasta": "2026-06-18",
  "total": 1,
  "truncado": false,
  "fichajes": [
    {
      "id": 9021,
      "empleado": "Ana García López",
      "dni": "12345678Z",
      "centro": "Oficina Central",
      "tipo": "entrada",
      "ts": "2026-06-18 09:02:11",
      "metodo": "kiosko_pin",
      "hash": "a3f1c9..."
    }
  ]
}

Una consulta devuelve como máximo 10.000 fichajes. Si se alcanza ese tope, truncado vale true; acota el rango de fechas para obtener el resto.

§ 03 · Errores

Respuestas de error.

Cuando algo falla, la respuesta es { "ok": false, "error": "..." } con el código HTTP correspondiente:

Código Significado
401Falta la API key o es inválida/revocada.
403Tu plan no incluye la API (disponible en Pro).
404Recurso no encontrado (p. ej. empleado inexistente).
405Método HTTP no permitido en ese endpoint.
422Datos inválidos (fechas mal formadas, rango excesivo, tipo erróneo…).

¿Listo para integrar?

Genera tu API key desde el panel, en Integraciones. La API se incluye en el plan Pro.

Ver planes →