Per a desenvolupadors

API de Tiemio

Llegeix els registres de jornada de la teva empresa des de les teves pròpies eines: un full de nòmines, un informe, un assistent d’IA. L’API és de només lectura, de manera que res fora de l’aplicació pot canviar el registre.

Què fa i què no fa

Llegeix el teu equip, les hores de cada persona per dia, els fitxatges de cada dia, les correccions i la cadena de hashes.
No pot fitxar, canviar ni aprovar res. El fitxatge el fa el treballador i cada canvi l’aprova una persona: això és el que dona valor de prova al registre.
No pot descarregar fulls de registre: cada descàrrega queda anotada com a prova de a qui es va lliurar què, així que es fa a l’aplicació.
Una clau mai no veu el DNI/NIE, el correu ni el telèfon d’una persona, ni el text de les notes d’hores. Sí que veu els motius de les correccions, perquè formen part del registre.
No hi ha webhooks. Per veure els canvis, torna a llegir.

Aconsegueix una clau

Entra com a titular de l’empresa i obre la pàgina Empresa.
A Claus d’API, posa un nom a la clau i crea-la.
Copia-la en aquell moment: només es mostra una vegada. Només guardem un hash.
Envia-la a cada crida com a Authorization: Bearer <clau>. Guarda-la al teu servidor, mai en una pàgina web ni en una aplicació: qui la tingui pot llegir els registres dels teus empleats.
Pots revocar una clau quan vulguis. El titular rep un correu per cada clau nova.

La teva primera crida

curl -H "Authorization: Bearer tmk_your_key" \
  "https://tiemio.com/api/employer/month?month=2026-09"

La resposta dona els mil·lisegons treballats per persona i dia, amb les correccions aprovades ja aplicades. L’índex 0 és el dia 1 del mes.

{
  "month": "2026-09",
  "today": "2026-10-30",
  "timeZone": "Europe/Madrid",
  "days": 30,
  "people": [
    {
      "employmentId": "emp_01",
      "personId": "usr_01",
      "name": "Ana García",
      "from": "2026-01-12",
      "until": null,
      "workedMs": [28800000, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "flagged": [false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false]
    }
  ]
}

Les cinc rutes

GET /api/employer: L’empresa i la seva gent, amb el fitxatge actual de cada persona activa. Fes servir l’id de la relació laboral (employment) d’aquí a les rutes següents.
GET /api/employer/month?month=YYYY-MM: El temps treballat per persona i dia en un mes, i quins dies queden fora de l’horari de la persona.
GET /api/employer/employments/{id}/day?date=YYYY-MM-DD: Un dia d’una persona: cada fitxatge, amb l’hora del dispositiu, la de recepció, si va esperar sense connexió, i les correccions resoltes aquell dia.
GET /api/employer/corrections: Les correccions de l’empresa: qui les va demanar, qui va decidir, quan i per què. Afegeix ?status=pending o ?employment=<id> per acotar.
GET /api/employer/employments/{id}/chain: Cada fitxatge tal com se’n va calcular el hash, 500 per pàgina, perquè la teva eina recalculi la cadena. Afegeix ?after=<next> per a la pàgina següent i ?kind=corrections per a les files de correccions.

Llegir un mes sense arribar al límit

Per als totals, una crida a month cobreix tot l’equip.
Les hores d’entrada i sortida necessiten una crida a day per persona i dia. Amb 20 persones i 31 dies són 620 crides, uns 11 minuts al límit, així que espaia-les.
Els dies es tallen a la zona horària de l’empresa, que ve a cada resposta. Els instants van en UTC.
Fes-ho una vegada, quan el mes hagi tancat, en lloc de consultar contínuament.

Límits i errors

60 peticions per minut, per clau i per adreça del client. Per sobre: 429 amb el codi rate_limited i Retry-After: 60. Espera i torna-ho a provar.
401 bad_api_key: la clau és desconeguda o està revocada.
400 bad_request: un mes, una data o un paràmetre mal formats, o una data futura.
404, a les rutes day i chain: aquesta persona no és de la teva empresa. A corrections, un id que no és teu retorna una llista buida.
500: alguna cosa ha fallat per part nostra, i la resposta pot venir sense codi. Torna-ho a provar.
Els errors són { error, code }. Fes servir el codi: el text pot canviar.
Una clau continua llegint encara que el teu pla caduqui. Deixa de funcionar quan es revoca, quan es tanca el negoci o quan qui la va crear deixa de ser el titular.

Què es manté estable

Només es garanteixen els camps de la referència. Les rutes retornen altres camps; no t’hi recolzis.
Un camp documentat no s’elimina ni es canvia. En poden aparèixer de nous, així que ignora els que no coneguis.

Prova-la sense compte

La prova obre una empresa de demostració amb persones fictícies i setmanes d’historial. La resposta et dona un token de titular que funciona a les mateixes cinc rutes, al servidor de prova, durant 24 hores.

curl -X POST https://testdrive.tiemio.com/api/testdrive

Una diferència: el token de titular de la prova és una sessió, no una clau d’API, així que també veu dades de contacte i notes que una clau no veu.