API REST

GET /ping

Comprova que la teva credencial és vàlida i retorna les dades bàsiques de la teva empresa i pla.

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

GET /empleados

Llista els empleats actius de la teva empresa, ordenats per cognoms.

{
  "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

Llista els centres de treball de la teva 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

Llista fitxatges en un rang de dates. Cada fila és un apunt individual (entrada, sortida, pausa_inicio, pausa_fin), no un parell tancat: venen ordenats cronològicament perquè puguis aparellar-los. Paràmetres opcionals:

• des de, fins a — format YYYY-MM-DD. Per defecte, els últims 30 dies. Màxim 366 dies per consulta.
• dni — filtra per un empleat (accepta DNI/NIE o correu electrònic).
• id_empleado — alternativa al DNI, amb l'id retornat per /empleados.
• id_centro — filtra per un centre.
• referència — filtra pel teu codi propi de projecte o obra. Coincidència exacta.
• geo — 1 per incloure la geolocalització de cada fitxatge. Desactivat per defecte.

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",
  "referencia": null,
  "total": 1,
  "truncado": false,
  "fichajes": [
    {
      "id": 9021,
      "empleado": "Ana García López",
      "dni": "12345678Z",
      "centro": "Oficina Central",
      "tipo": "entrada",
      "ts": "2026-06-18 07:02:11.482",
      "fecha": "2026-06-18",
      "hora": "09:02",
      "metodo": "kiosko_pin",
      "referencia": "PRY-2026/014",
      "hash": "a3f1c9...",
      "proyecto": { "id": 7, "codigo": "PRY-2026/014", "nombre": "Reforma Nave B" }
    }
  ]
}

proyecto val null si aquest apunt no està imputat a cap projecte del mestre. Vegeu § 04 · Projectes.

La teva pròpia referència de projecte

Cada fitxatge pot portar una referència lliure de fins a 64 caràcters: el teu codi de projecte, d'obra o d'expedient. És una dada opaca — no la interpretem, només la guardem i te la retornem — i s'escriu en registrar el fitxatge (POST /fichajes). S'admeten lletres, números, espais i els signes . _ - / # : ( ).

La referència no entra en el hash del registre: el hash cobreix el fet jurídic —qui, quan i quin tipus d'apunt—, i aquesta fórmula no canvia. La seva immutabilitat la garanteix el propi motor de base de dades, que no admet modificar ni esborrar un fitxatge un cop escrit.

Si aquesta referència coincideix amb el codigo d'un projecte del teu mestre, el fitxatge queda imputat automàticament a aquest projecte i comença a sumar a /proyectos/horas. Si no coincideix amb cap, la referència es guarda igualment: no rebutgem un fitxatge perquè el projecte no estigui donat d'alta encara.

Geolocalització

Amb ?geo=1 cada fitxatge inclou un objecte geo amb les coordenades registrades, la precisió del GPS en metres, la distància al centre i si ha quedat dins del perímetre configurat. Els camps valen null si aquest fitxatge es va registrar sense ubicació.

"geo": {
  "lat": 40.4321,
  "lng": -3.8123,
  "precision": 18,
  "distancia": 24,
  "valida": true
}

Està fora per defecte expressament: la ubicació d'una persona no hauria de viatjar a un sistema extern sense que algú ho demani explícitament. Si l'exportes a una altra eina, recorda que continua sent una dada personal — reflecteix-ho al teu registre d'activitats de tractament i a la informació que dones a la teva plantilla.

Una consulta retorna com a màxim 10.000 fitxatges. Si s'arriba a aquest límit, truncado val true; acota el rang de dates per obtenir la resta.

GET / hores

Hores treballades per empleat en un període, ja sumades. És la drecera quan el que necessites és el total i no t'interessa aparellar apunts tu mateix. Fa servir exactament el mateix càlcul que la columna d'hores de l'exportació per a nòmina, de manera que la integració i el CSV que obre la gestoria no poden donar xifres diferents. Només compta jornades tancades: una entrada sense sortida és una dada incompleta.

• des de, fins a — format YYYY-MM-DD. Per defecte, el mes en curs. Màxim 366 dies per consulta.
• dni — filtra per un empleat (accepta DNI/NIE o correu electrònic).
• id_empleado — alternativa al DNI.
• id_centro — filtra per un centre.

curl "https://controlhorariolegal.com/api/v1/horas?desde=2026-08-01&hasta=2026-08-31" \
  -H "X-Api-Key: chl_tu_clave"

{
  "ok": true,
  "desde": "2026-08-01",
  "hasta": "2026-08-31",
  "total": 1,
  "empleados": [
    {
      "id_empleado": 42,
      "nombre": "Ana",
      "apellidos": "García López",
      "dni": "12345678Z",
      "sociedad": "Ejemplo S.L.",
      "horas_semana": 35,
      "dias": 18,
      "segundos": 453600,
      "horas": 126.0,
      "hhmm": "126:00"
    }
  ]
}

GET /estado

Situació actual d' un empleat: si és dins, fora o en pausa, quines accions pot fer ara, el temps treballat avui i si hi ha una absència aprovada que cobreixi el dia. Pensat per pintar el botó de fitxar al teu propi portal sense duplicar les nostres regles de seqüència. Identifica l'empleat amb dni, email o id_empleado.

{
  "ok": true,
  "empleado": { "id": 14, "nombre": "Ana García López", "rol": "empleado",
                "id_centro": 3, "centro": "Oficina Central", "requiere_fichaje": true },
  "fecha": "2026-06-18",
  "ahora": "13:30",
  "solo_kiosko": false,
  "estado": "dentro",
  "acciones": ["pausa_inicio", "salida"],
  "avisar": false,
  "motivo": "jornada_abierta",
  "jornada": { "hora_entrada": "09:02", "horas_abierta": 4.5, "olvidada": false },
  "ausencia": null,
  "hoy": {
    "trabajado": "04:28",
    "en_pausa": false,
    "fichajes": [ { "tipo": "entrada", "hora": "09:02", "metodo": "kiosko_pin" } ]
  }
}

avisar indica si cal recordar-li que fitxi, i motiu explica per què sí o per què no (sin_entrada_hoy, absència, jornada_abierta, solo_kiosko…).

GET /presencia

Qui és dins ara i des de quina hora, per a tota la plantilla obligada a fitxar, en una sola crida. Paràmetre opcional id_centro. És l'equivalent al tauler d'un responsable: amb /estado caldrien tantes crides com empleats.

{
  "ok": true,
  "total": 12,
  "dentro": 7,
  "empleados": [
    {
      "id": 14,
      "nombre": "Ana García López",
      "rol": "empleado",
      "id_centro": 3,
      "centro": "Oficina Central",
      "estado": "dentro",
      "hora_entrada": "09:02",
      "trabajado": "04:28",
      "fichajes_hoy": [ { "tipo": "entrada", "hora": "09:02" } ]
    }
  ]
}

GET /horario

Torns assignats a un empleat en un rang: no quan va fitxar, sinó quan li toca. Identifica l'empleat amb dni, email o id_empleado. des de y fins a són opcionals (per defecte, la setmana en curs); màxim 62 dies per consulta. Els dies es retornen indexats per data, i un mateix dia pot tenir diversos trams (jornada partida).

{
  "ok": true,
  "empleado": { "id": 14, "nombre": "Ana García López" },
  "desde": "2026-06-15",
  "hasta": "2026-06-21",
  "dias": {
    "2026-06-15": [
      { "fecha": "2026-06-15", "id_turno": 2, "nombre": "Mañana",
        "hora_inicio": "09:00", "hora_fin": "17:00", "descanso_min": 30,
        "nota": null, "color": "#2f6f4f", "a_medida": 0 }
    ]
  }
}

GET /correcciones/listar

Sol·licituds d'un empleat (dni, email o id_empleado) amb el seu estat i la resposta de RRHH. Últimes 100.

{
  "ok": true,
  "total": 1,
  "correcciones": [
    {
      "id": 341,
      "tipo": "salida",
      "fecha": "2026-06-17",
      "hora": "18:00",
      "motivo": "Olvidé fichar la salida",
      "estado": "aprobado",
      "respuesta": "Confirmado con el encargado"
    }
  ]
}

GET /correcciones/pendientes

Cua de sol·licituds pendents de revisió a tota l'empresa. Paràmetre opcional id_centro. Últimes 200.

{
  "ok": true,
  "total": 1,
  "correcciones": [
    {
      "id": 341,
      "empleado": "Ana García López",
      "id_centro": 3,
      "centro": "Oficina Central",
      "tipo": "salida",
      "fecha": "2026-06-17",
      "hora": "18:00",
      "motivo": "Olvidé fichar la salida",
      "solicitada": "2026-06-18 08:14:02"
    }
  ]
}

POST /correcciones · requereix escriptura

Crea una sol·licitud de correcció. No escriu al registre: el que arriba és una petició, no un apunt. Les hores s'envien en hora local del centre i es converteixen a UTC en guardar-les. El motiu és obligatori (mínim 8 caràcters) i no s'admeten hores futures.

Els apunts han d'encaixar en la seqüència real de l'empleat: no cap una sortida on no hi havia cap jornada oberta, ni una entrada sobre una jornada que ja ho estava. Si alguna cosa no quadra es respon 422 amb el detall i no es crea cap sol·licitud de l'enviament, ni tan sols les que sí encaixaven. Un lot amb entrada i sortida del mateix dia es valida conjuntament, de manera que la sortida es recolza en l'entrada que l'acompanya.

curl -X POST https://controlhorariolegal.com/api/v1/correcciones \
  -H "X-Api-Key: chl_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "dni": "12345678Z",
    "motivo": "Olvidé fichar la salida del viernes",
    "apuntes": [
      { "tipo": "salida", "ts_solicitado": "2026-06-17 18:00" }
    ]
  }'

{ "ok": true, "n": 1, "ids": [341] }

{
  "ok": false,
  "error": "Ese apunte no encaja: el 17/06 a las 18:00 no había ninguna jornada abierta, así que ahí no puede ir una salida. Lo que encajaría es una entrada."
}

Per a un sol apunt també s'admet el format pla { "tipo": "...", "ts_solicitado": "..." } sense l'array.

POST /correcciones/resolver · requereix escriptura

Aprova o rebutja una sol·licitud. Aprovar insereix el fitxatge que falta a la cadena de hashes, d'aquí el permís d'escriptura. Si qui aprova des del teu portal no existeix com a usuari a Control Horario Legal, envia aprobador_nombre: queda escrit a la resolució per no perdre la traçabilitat.

curl -X POST https://controlhorariolegal.com/api/v1/correcciones/resolver \
  -H "X-Api-Key: chl_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "id_correccion": 341,
    "resolucion": "aprobado",
    "motivo": "Confirmado con el encargado",
    "aprobador_email": "rrhh@empresa.es",
    "aprobador_nombre": "Luis Martín"
  }'

{ "ok": true, "id": 341, "resolucion": "aprobado" }

GET /proyectos

El teu mestre de projectes. Paràmetre opcional activos=1 per excloure els arxivats.

{
  "ok": true,
  "total": 1,
  "proyectos": [
    {
      "id": 7,
      "codigo": "PRY-2026/014",
      "nombre": "Reforma Nave B",
      "horas_previstas": 120.0,
      "fecha_inicio": "2026-07-01",
      "fecha_fin": "2026-09-30",
      "activo": true
    }
  ]
}

horas_previstas val null si el projecte no té pressupost d'hores; aleshores no es calcula la desviació.

GET /proyectos/horas

Hores imputades per projecte en un període, amb la desviació enfront de les previstes i el percentatge consumit. És l'endpoint que resol el cas d'ús complet en una sola crida.

• des de, fins a — format YYYY-MM-DD. Per defecte, els últims 30 dies. Màxim 366 dies per consulta.
• dni, email o id_empleado — limita el càlcul a un sol treballador.

curl "https://controlhorariolegal.com/api/v1/proyectos/horas?desde=2026-08-01&hasta=2026-08-31" \
  -H "X-Api-Key: chl_tu_clave"

{
  "ok": true,
  "desde": "2026-08-01",
  "hasta": "2026-08-31",
  "proyectos": [
    {
      "id_proyecto": 7,
      "codigo": "PRY-2026/014",
      "nombre": "Reforma Nave B",
      "segundos": 411840,
      "horas": 114.4,
      "hhmm": "114:24",
      "horas_previstas": 120.0,
      "desviacion": -5.6,
      "porcentaje": 95.3
    }
  ],
  "sin_imputar": { "segundos": 28800, "horas": 8.0, "hhmm": "08:00" }
}

• desviacion — hores reals menys previstes. En negatiu, queda marge; en positiu, s'ha passat.
• porcentaje — consum sobre el previst. null si el projecte no té hores previstes.
• sin_imputar — hores treballades en el període que no estan assignades a cap projecte. Si aquesta xifra creix, és que falta imputar.

Els projectes actius sense hores en el rang apareixen a zero, perquè «zero hores imputades» és exactament el que necessites veure en un informe de seguiment.

POST /proyectos/imputar · requereix escriptura

Assigna un fitxatge ja registrat a un projecte, o el desassigna. No modifica el fitxatge — això és impossible per disseny — sinó la dada de gestió que hi penja. Tot i així exigeix escriptura, perquè és el número sobre el qual algú acaba facturant.

• id_fichaje — obligatori.
• codigo o id_proyecto — el projecte destí. Enviar tots dos buits o absents desimputa el fitxatge.
• motiu — opcional, queda al registre de la imputació.

curl -X POST https://controlhorariolegal.com/api/v1/proyectos/imputar \
  -H "X-Api-Key: chl_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "id_fichaje": 9021,
    "codigo": "PRY-2026/014",
    "motivo": "Reasignado desde AppSheet"
  }'

{ "ok": true, "id_fichaje": 9021, "id_proyecto": 7, "id_imputacion": 512 }

Si el codi no existeix al teu mestre, la resposta és 404. La imputació guarda historial: l'anterior no s'esborra, es substitueix per la nova com a vigent.

POST /fichajes · requereix escriptura

• tipo — obligatori: entrada, sortida, pausa_inicio o pausa_fin.
• dni, email o id_empleado — obligatori un d'ells.
• id_centro — opcional; per defecte, el centre de l'empleat.
• origen — extranet si el llança el propi treballador des del vostre portal (queda distingible al tauler), api en un altre cas.
• lat, lng, precision — opcionals. Si els envies, es guarden com a evidència.
• ip, user_agent — opcionals: la IP de la petició és la del teu servidor, no la del treballador. Si ens passes les reals, es registren aquestes.
• referència — el teu codi de projecte o obra, màxim 64 caràcters. Una referència invàlida retorna 422: no la retallem en silenci.
• observaciones — text lliure, màxim 500 caràcters.

curl -X POST https://controlhorariolegal.com/api/v1/fichajes \
  -H "X-Api-Key: chl_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "dni": "12345678Z", "tipo": "entrada", "origen": "extranet" }'

{
  "ok": true,
  "id": 9021,
  "empleado": 14,
  "tipo": "entrada",
  "ts": "2026-06-18 07:02:11.482",
  "hora_local": "09:02:11",
  "referencia": "PRY-2026/014",
  "duplicado": false,
  "hash": "a3f1c9..."
}

L'API respecta la política del centre: si un empleat està configurat per fitxar només al quiosc, la petició es rebutja amb 409. Un fitxatge repetit en pocs segons es considera duplicat i no trenca la cadena: es retorna duplicado: true.