Producte · 17/08/2026

Connectar el fitxatge amb Google Sheets o AppSheet: guia amb l'API

Codi d'Apps Script llest per copiar, quin endpoint demanar segons el que necessitis (i per què demanar el que no toca et costa una tarda), el patró que funciona a AppSheet, i les tres coses —zones horàries, truncament i geolocalització— que t'estalviaran depurar de nit.

Resposta curta: es connecta amb una clau d'API i peticions HTTP. Des de Google Sheets, amb una funció d'Apps Script que porta els fitxatges a una pestanya. Des d'AppSheet, recolzant-te en aquest mateix full. No calen webhooks ni integracions especials: una consulta programada cada quinze minuts, o una passada nocturna, cobreix el 95% dels casos.

El cas típic

Tens la gestió de projectes muntada en un full de càlcul, amb les hores pressupostades de cada feina. I tens el fitxatge, que sap les hores reals. El que vols és que la comparació es faci sola.

És una integració petita i ben delimitada: llegir dades, escriure-les en una pestanya, i deixar que les fórmules que ja tens facin la resta. No necessites un projecte d'integració.

Pas 1: la clau d'API

A Control Horario Legal es genera des de Ajustes → Integraciones. Es mostra una sola vegada, així que desa-la al gestor de contrasenyes abans de tancar la pantalla.

Tres coses que convé saber abans de continuar:

• La clau és de només lectura per defecte. Per al que farem, és exactament el que vols.
• Identifica l'empresa sencera, no un usuari. Tracta-la com una contrasenya: no l'enganxis en una cel·la del full compartit.
• Fes servir una clau per integració. Si demà has de revocar la del full, no tombes res més.

Pas 2: decidir quin endpoint necessites

Aquí és on es guanya o es perd el temps. Hi ha dues maneres de respondre «quantes hores porta aquesta persona aquest mes», i una és molt més barata:

• /api/v1/fichajes et dona els apunts solts (entrada, pausa, sortida). Els necessites si vols el detall: a quina hora va entrar cada dia, des de quin mètode, amb quin projecte.
• /api/v1/horas et dona els totals ja sumats per empleat i període. Si només vols el total, no aparellis apunts a Apps Script: demana això.
• /api/v1/proyectos/horas et dona hores fitxades enfront de previstes per projecte, amb la desviació calculada. Si el teu cas és exactament comparar pressupost contra real, aquest endpoint et pot estalviar tota la lògica del full.

Pas 3: portar les dades a Google Sheets

Al full: Extensiones → Apps Script. El codi mínim que funciona:

const API_KEY = 'chl_tu_clave';   // mejor en Propiedades del script
const BASE = 'https://controlhorariolegal.com/api/v1';

function traerFichajes() {
  const hoy = new Date();
  const desde = Utilities.formatDate(new Date(hoy.getFullYear(), hoy.getMonth(), 1), 'Europe/Madrid', 'yyyy-MM-dd');
  const hasta = Utilities.formatDate(hoy, 'Europe/Madrid', 'yyyy-MM-dd');

  const res = UrlFetchApp.fetch(
    BASE + '/fichajes?desde=' + desde + '&hasta=' + hasta,
    { headers: { 'X-Api-Key': API_KEY }, muteHttpExceptions: true }
  );
  const data = JSON.parse(res.getContentText());
  if (!data.ok) throw new Error(data.error);

  const filas = data.fichajes.map(f => [
    f.id, f.fecha, f.hora, f.empleado, f.tipo,
    f.centro, f.referencia || '', f.proyecto ? f.proyecto.codigo : ''
  ]);

  const hoja = SpreadsheetApp.getActive().getSheetByName('Fichajes');
  hoja.clear();
  hoja.appendRow(['ID','Fecha','Hora','Empleado','Tipo','Centro','Referencia','Proyecto']);
  if (filas.length) hoja.getRange(2, 1, filas.length, filas[0].length).setValues(filas);
}

Desa la clau a Configuración del proyecto → Propiedades del script en lloc de deixar-la al codi, i llegeix-la amb PropertiesService.getScriptProperties().getProperty('API_KEY'). Si comparteixes el full, el codi hi va amb ell.

Per programar-ho: Activadores → Añadir activador, temporitzador cada hora o diari. Una passada nocturna del dia anterior és suficient per a informes; cada 15 minuts si vols alguna cosa propera al temps real.

Pas 4: la comparació amb el pressupostat

Si el teu mestre de projectes viu al full, creua pel codi amb un SUMIF contra la columna Projecte i ja tens previst contra real.

Però hi ha una drecera que molta gent es perd: si dones d'alta aquests mateixos codis al mestre de projectes de Control Horario Legal, la comparació te la retorna feta:

GET /api/v1/proyectos/horas?desde=2026-08-01&hasta=2026-08-31

I retorna, per projecte, hores fitxades, previstes, desviació i percentatge consumit. Menys fórmules que mantenir.

Com fer que els fitxatges arribin ja imputats

Si el fitxatge entra des del teu propi sistema per API, pots enviar el teu codi intern d'obra al camp referència. Si coincideix amb un projecte del mestre, el fitxatge queda imputat sol, sense que ningú triï res.

Si la teva gent fitxa des del mòbil de l'app, es tria en un desplegable en fitxar l'entrada, entre els projectes que tingui assignats.

I a AppSheet

AppSheet no crida APIs REST arbitràries amb comoditat. El patró que funciona és no intentar-ho: que Apps Script escrigui al full i AppSheet llegeixi el full. Guanyes memòria cau, historial i depuració trivial —si alguna cosa falla, ho veus a la pestanya—.

Si necessites refrescar sota demanda des de l'app, una acció d'AppSheet pot cridar un webhook d'Apps Script desplegat com a aplicació web, que al seu torn executa la funció de dalt.

Tres coses que t'estalviaran depurar de nit

• Zones horàries. El camp ts ve en UTC; fecha y hora vénen ja convertits a l'hora local del centre. Fes servir aquests últims per presentar i el ts per ordenar. Barrejar-los és l'origen clàssic de l'error d'una hora.
• Volum. Una consulta admet 366 dies de rang i retorna fins a 10.000 apunts; si s'arriba al límit, la resposta porta truncado: true. Comprova aquest camp en lloc de suposar-ho.
• Geolocalització. No viatja tret que la demanis amb ?geo=1. Si la portes al full, recorda que continua sent una dada personal: reflecteix-ho al teu registre d'activitats de tractament i limita qui veu aquesta pestanya.

No hi ha webhooks: per què i què fer

No emetem webhooks sortints. És una limitació real i preferim dir-la abans que dissenyes comptant amb ells. Per a aquest cas d'ús el polling acotat funciona igual de bé i és més fàcil de depurar: si una passada falla, la següent recupera, sense cues ni reintents que mantenir.

Si el que vols és un tauler de presència en viu, /api/v1/presencia et resol tota la plantilla en una sola crida.

---

Preguntes freqüents

Necessito el pla Pro per usar l'API?

Sí, l'API està inclosa al pla Pro. Durant els 30 dies de prova el compte funciona amb permisos de Pro, així que pots muntar i validar la integració completa abans de contractar res.

Puc crear una clau d'API que només pugui llegir?

Sí, i és el que obtens per defecte: totes les claus neixen de només lectura. Escriure al registre requereix un permís addicional que es concedeix cas per cas. Per portar dades a un full de càlcul no necessites escriptura.

Hi ha webhooks per avisar de nous fitxatges?

No. Per mantenir sincronitzat un sistema extern es consulta l'endpoint de fitxatges amb un rang acotat: cada 15 minuts si es necessita alguna cosa propera al temps real, o una passada nocturna del dia anterior per a informes.

Com obtinc les hores totals de cada treballador sense sumar els apunts?

Amb l'endpoint /api/v1/horas, que retorna dies treballats i hores totals per empleat i període, en decimal i en HH:MM. Fa servir el mateix càlcul que l'exportació per a nòmina, de manera que la integració i el CSV de la gestoria no poden donar xifres diferents.

Puc enviar el meu codi intern de projecte en cada fitxatge?

Sí. Cada fitxatge admet un camp referència de text lliure de fins a 64 caràcters. Si aquest codi coincideix amb el d'un projecte donat d'alta al mestre, el fitxatge queda imputat a aquest projecte automàticament.

Quins límits de consulta té l'API?

Cada clau disposa de 180 unitats per minut i 6.000 per hora, on cada crida gasta segons el que costa: consultar /ping o /proyectos val 1 unitat i /fichajes o /proyectos/horas valen 8. A la pràctica són 22 consultes seguides de les més cares per minut, molt per sobre del que necessita una integració que sincronitza cada quinze minuts. Cada resposta inclou la capçalera X-RateLimit-Remaining perquè no hagis d'estimar-ho, i si esgotes el marge reps un 429 amb els segons d'espera a Retry-After. A més hi ha límits per consulta: màxim 366 dies de rang i 10.000 registres per resposta a l'endpoint de fitxatges, i 62 dies al d'horaris planificats.

Darrera actualització: 17 d'agost de 2026. Aquest article té finalitats informatives i no constitueix assessorament legal.

Continua llegint