API de control horari: què ha d'oferir i què preguntar abans de contractar
Set preguntes concretes per saber si una API és usable o és un adorn de la pàgina de preus: claus de només lectura, què retorna cada fitxatge, com s'obtenen els totals i si quadren amb la nòmina, límits documentats i webhooks. Amb una prova de foc de vint minuts.
Resposta curta: demana la documentació abans de signar i llegeix-la. Si és pública, bon senyal. Si te l'envien per correu després d'una trucada comercial, mal senyal. I comprova quatre coses concretes: si pots crear claus de només lectura, què retorna cada fitxatge, si hi ha webhooks o cal consultar, i en quin pla està inclosa.
Per què la documentació hauria de ser pública
Alguna vegada ens han preguntat si no és perillós tenir la documentació de l'API oberta a tothom. És un dubte raonable i la resposta és que no, per dos motius.
El primer és de seguretat: la seguretat d'una API no està en que ningú sàpiga quins endpoints té, sinó en la credencial. Saber que existeix /api/v1/fichajes no serveix de res sense una clau vàlida. La seguretat per ocultació no és seguretat, és un retard.
El segon és pràctic: qui avalua la integració gairebé mai és qui signa. És un desenvolupador, o el proveïdor que manté l'ERP. Si per veure si la integració és viable cal donar-los accés al teu compte, o demanar un PDF a comercial, l'avaluació es posposa i de vegades no es fa.
Tots els proveïdors seriosos de programari d'infraestructura publiquen la seva documentació. Si el teu proveïdor de fitxatge l'amaga, la pregunta interessant és què més no vol que es vegi abans de signar.
Les set preguntes que separen una API usable d'un adorn
1. Està inclosa en el meu pla o és un mòdul a part?
És la primera i la que fa trencar més pressupostos. Molts comparadors mostren un preu per empleat i l'API apareix com a extra, de vegades amb un mínim mensual que multiplica el cost. Pregunta també si funciona durant el període de prova: si no, no pots validar la integració abans de comprometre't, que és just quan cal.
2. Puc crear una clau de només lectura?
Fonamental i moltes vegades absent. La majoria d'integracions només llegeixen: portar hores a un full, a un BI, a la nòmina. Si l'única clau disponible pot a més escriure al registre, qualsevol fuita d'aquesta clau —un repositori, un full compartit, un empleat que marxa— passa de ser un problema de confidencialitat a un problema d'integritat del teu registre legal.
El correcte és que les claus neixin de només lectura i que l'escriptura sigui una excepció justificada.
3. Què retorna exactament cada fitxatge?
Demana un exemple real de resposta. Coses que haurien d'estar-hi i sovint falten:
- Identificador estable de l'apunt.
- Tipus d'apunt: entrada, sortida, inici i fi de pausa. Si només et donen parells tancats entrada-sortida, no podràs calcular les pauses i les teves hores no quadraran amb les seves.
- Segell en UTC i hora local ja convertida. Si només et donen una de les dues, prepara't per a l'error d'una hora.
- Mètode de fitxatge: sense ell no saps si el dada ve del mòbil, del quiosc o d'una importació.
- Centre de treball.
- Un camp lliure per a la teva referència. Vegeu la pregunta 5.
4. Com obtinc les hores totals?
Si la resposta és «aparellant els apunts», que existeixi almenys un endpoint que retorni els totals ja sumats. I llavors la pregunta important: ¿usa el mismo cálculo que el informe que descarga mi gestoría?
Si no, tindràs dues xifres per al mateix mes, i aquest és el pitjor lloc on pot aparèixer una discrepància. Abans de signar, compara el total de l'endpoint amb el de l'export de nòmina per al mateix període. Si no coincideix al minut, tens un problema que apareixerà el dia d'una revisió salarial.
5. Puc enviar el meu propi codi de projecte, obra o client?
Un camp de text lliure per fitxatge, on poses el teu identificador, és el que converteix el registre horari en informació de gestió. Sense ell, creuar hores amb obres exigeix mantenir una taula de correspondències pel teu compte.
I una pregunta de segon nivell: si envio aquest codi, s'imputa només a un projecte en el seu sistema, o es queda en un camp solt que ningú fa servir?
6. Hi ha webhooks?
Si n'hi ha, bé. Si no n'hi ha, tampoc és descalificatori: per a la majoria de casos, consultar cada quinze minuts o fer una passada nocturna funciona igual i és més fàcil de depurar —si una passada falla, la següent recupera, sense cues ni reintents que mantenir—.
El que sí que és descalificatori és que et diguin que sí i després resulti que són un avís genèric sense dades, o que no hi hagi reintents. Demana un exemple de payload.
7. Quins límits té?
Els límits no són dolents; els límits no documentats sí. Necessites saber peticions per minut, màxim de dies per consulta, màxim de registres per resposta i —això s'oblida— com t'avisa que la resposta venia truncada. Sense aquest avís, un dia el teu informe mostrarà mig mes i ningú se n'adonarà.
Dues preguntes extra si t'integraran la nòmina
- Hi venen les absències i les vacances? Sense elles la nòmina no es tanca des de l'API, i tornaràs al CSV.
- Com apareixen les correccions? Si un fitxatge corregit substitueix l'original, el teu sistema perdrà el rastre. Si s'afegeix un de nou amb el seu estat i el seu motiu, pots auditar. I aquí veuràs si el proveïdor es pren seriosament la inalterabilitat del registre.
La prova de foc, en vint minuts
Amb la documentació pública i un compte de prova, això es resol ràpid:
- Crea una clau. Comprova que és de només lectura intentant escriure: ha de respondre amb un error clar.
- Demana els fitxatges d'un mes. Mira si hi ha les pauses i si venen les dues hores (UTC i local).
- Demana els totals del mateix mes. Compara'ls amb l'export de nòmina. Han de coincidir.
- Força un error: una data mal formada, un rang invertit. Un bon error et diu què has fet malament; un de dolent retorna 500 i et deixa a les fosques.
- Demana un rang enorme i comprova què passa quan superes el límit.
Si els cinc passos surten bé, la integració et costarà una tarda. Si el tercer falla, no la facis fins que t'ho expliquin.
Documentació pública, claus de només lectura per defecte
Pots llegir la documentació completa a controlhorariolegal.com/api sense registrar-te, i validar tota la integració durant els 30 dies de prova. Els totals de l'API surten del mateix càlcul que l'exportació per a nòmina.
Prova 30 dies gratis →Preguntes freqüents
És perillós que la documentació d'una API sigui pública?
No. La seguretat d'una API està en la credencial, no en desconèixer els endpoints: saber que existeix una ruta no serveix de res sense una clau vàlida. Publicar la documentació permet a més que el desenvolupador o el proveïdor que farà la integració l'avaluï sense necessitat d'accés al compte.
Què és una clau d'API de només lectura i per què és important?
És una credencial que permet consultar dades però no modificar-les. És important perquè la majoria d'integracions només necessiten llegir, i si l'única clau disponible també pot escriure al registre horari, una filtració d'aquesta clau passa de ser un problema de confidencialitat a comprometre la integritat d'un registre amb valor legal.
Ha de retornar l'API les pauses per separat?
Sí. Si només retorna parells tancats d'entrada i sortida, no es poden calcular les pauses i els totals propis mai no quadraran amb els del proveïdor. Cada apunt —entrada, sortida, inici de pausa i fi de pausa— ha de venir identificat amb el seu tipus.
És un problema que un programari de fitxatge no tingui webhooks?
No necessàriament. Per a la majoria d'integracions, consultar l'endpoint de fitxatges cada quinze minuts o fer una passada nocturna funciona igual de bé i és més fàcil de depurar. El que sí que és un problema és que els anunciïn i després no portin dades o no tinguin reintents.
Com comprovo que els totals de l'API són fiables?
Demanant el total d'un mes per API i comparant-lo amb l'informe d'hores que descarrega la gestoria per a aquell mateix període. Si no coincideixen, hi ha dos càlculs diferents per a la mateixa jornada, i aquesta discrepància apareixerà en el pitjor moment possible.
Sol estar inclosa l'API en el preu base?
Depèn del proveïdor: en molts és un mòdul a part, de vegades amb un mínim mensual que altera bastant el cost real. Convé preguntar també si funciona durant el període de prova, perquè si no es pot validar la integració abans de contractar, s'està comprant a cegues.
Darrera actualització: 17 d'agost de 2026. Aquest article té finalitats informatives i no constitueix assessorament legal.