API REST v1

L'API REST d'AccessTime és la mateixa que fa servir la nostra app mòbil: tot el que fa l'app passa per aquí. També la pots fer servir per a petites integracions pròpies, per exemple consultar els fitxatges del dia des d'un script o sol·licitar una absència des d'una altra eina.

L'URL base és https://tudominio/api/v1, totes les peticions i respostes són JSON i les rutes protegides requereixen la capçalera Authorization: Bearer {token}.

1. Aconsegueix un token

L'autenticació fa servir tokens personals (Laravel Sanctum), sense cookies ni sessió. El token s'obté amb l'email i la contrasenya de l'empleat, els mateixos amb què entra al panell web:

curl -X POST https://tudominio/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "empleado@empresademo.com", "password": "********" }'

La resposta inclou el token i les dades bàsiques de l'usuari:

{
  "token": "1|abcdef...",
  "user": { "id": 1, "name": "...", "email": "...", "role": "empleado", "company_id": 2 }
}

Guarda el token en un lloc segur i no el comparteixis: dona accés a les dades d'aquella persona. Si les credencials no són vàlides rebràs un 422, i l'endpoint està limitat a 10 intents per minut.

Per tancar sessió, POST /api/v1/logout (autenticat) revoca el token actual.

Els tokens caduquen als 90 dies: la resposta del login porta la data a token_expires_at i, passada, l'API respon 401 i cal tornar-ne a demanar un. Si envies device_name al login («iPhone de l'Anna»), el token apareix amb aquest nom a Perfil → Dispositius amb accés, des d'on la persona el pot revocar.

2. Endpoints disponibles

Tots els endpoints operen sobre l'usuari autenticat: cada persona només veu els seus fitxatges, les seves absències i el seu saldo. Els missatges (message) arriben en l'idioma de la persona, i cada 403 porta un code que diu què passa: solo_lectura, empresa_bloqueada, cuenta_desactivada, email_no_verificado o sin_empresa.

3. Fitxar des de l'API

Cada fitxatge porta un client_uuid: un UUID que generes una vegada, abans del primer intent, i repeteixes a cada reintent. Així, si es talla la xarxa i ho tornes a provar, el fitxatge mai no es duplica (sense ell, 422). Envia també type (in o out); si l'omets, alterna segons el darrer fitxatge, igual que el botó del tauler (com funciona el fitxatge).

curl -X POST https://tudominio/api/v1/fichar \
  -H "Authorization: Bearer 1|abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "client_uuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "type": "in" }'

Resposta 201 amb el fitxatge (status, id, type, happened_at…). Un reintent amb el mateix client_uuid retorna 200 i el mateix cos.

• L'hora és la del servidor. El que s'ha capturat sense connexió es reenvia amb offline: true, captured_at (l'hora del mòbil en prémer) i sent_at (la del mòbil en enviar): el servidor corregeix el desfasament del rellotge. Si arriba més de 72 hores després, queda com a incidència pendent de revisió (202): no es perd. Si el primer que consta després de la seva hora, a menys de 5 minuts, és un fitxatge del mateix tipus (la persona el va repetir al quiosc o al tauler mentre esperava a la cua), és el mateix fitxatge repetit: 200 amb "duplicate": true i el que consta. Si aquest fitxatge està pendent de revisió, és un 202 amb "duplicate": true i aquesta incidència. I si el que consta a menys de 5 minuts és un fitxatge del mateix tipus registrat a mà després que es premés (un oblit aprovat o una correcció acceptada abans que arribés la cua): en el mateix minut, el 200 porta aquest; en un altre, compta l'enviament: el registrat a mà s'anul·la (continua visible) i el 200 amb "duplicate": true porta el fitxatge registrat amb el client_uuid enviat.
• Ubicació (latitude, longitude, accuracy): només si l'empresa la té activada (geolocation_mode a /config); si no, es descarta. Amb obligatoria, un fitxatge en el moment sense ubicació rep 422.
• Verificació al mòbil (verification, opcional): només el resultat de la que va fer el mateix telèfon, mai dades biomètriques: {"method": "biometric_local" | "pin" | "none", "verified": true | false, "os_auth_type": "face" | "fingerprint" | "credential" | null}. És el que declara la teva aplicació: el servidor no ho pot comprovar. Es retallen els espais i un text buit compta com a null. Si no compleix aquest format, es descarta: el fitxatge es registra igualment i la resposta porta "verification_discarded": true (mai 422); altres claus s'ignoren. Queda al fitxatge i la persona la veu a «El meu registre».
• known_ms (opcional): l'hora en mil·lisegons de l'últim fitxatge que coneixia la teva aplicació en prémer, la del servidor (la de /config o la de l'última resposta), no la del mòbil. Si després consta un altre del mateix tipus que el servidor ja tenia en prémer (per exemple, al quiosc) o que la teva aplicació va enviar abans des de la seva cua sense connexió, es registra el que toca, com fa el botó del tauler, llevat que aquest fitxatge sigui de fa menys de 5 minuts i no vingui d'aquesta cua: és el mateix fitxatge repetit i la resposta és 200 amb "duplicate": true i el que consta. Sense known_ms passa el mateix si aquest fitxatge del mateix tipus, de fa menys de 5 minuts, es va fer per un altre canal (el quiosc o el tauler); però el botó desfasat de més temps no es corregeix, així que envia'l sempre.
• Errors: 422 és definitiu (mostra el motiu); 401, 429, 5xx o sense xarxa, conserva el fitxatge i torna-ho a provar amb el mateix client_uuid.

Els fitxatges es desen en UTC i les consultes d'"avui" i "setmana" fan servir la zona horària de la teva empresa. El resum mensual es calcula a partir de les jornades consolidades cada nit, les mateixes que alimenten els informes.

Si la prova gratuïta de l'empresa ha acabat sense subscripció, el compte està en només lectura i POST /fichar respon 403 (solo_lectura). Els endpoints de consulta continuen funcionant (plans i facturació).

4. Absències des de l'API

Pots consultar els tipus disponibles, el saldo i sol·licitar una absència:

curl -X POST https://tudominio/api/v1/ausencias \
  -H "Authorization: Bearer 1|abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "absence_type_id": 1, "starts_on": "2026-08-03", "ends_on": "2026-08-07", "reason": "Vacaciones" }'

L'API aplica les mateixes validacions que el panell: solapaments amb altres absències pròpies, saldo disponible en els tipus que descompten i que el rang contingui dies laborables (descompta caps de setmana i festius). Si el tipus requereix aprovació, la sol·licitud entra en el flux d'aprovacions amb estat pending; si no, queda aprovada directament. Més detall a absències i vacances.

Els tipus d'absència que exigeixen justificant no es poden sol·licitar per API: la petició retorna un error i cal fer-la des del panell web, on sí que es pot adjuntar el document.

I ara què?

• Si encara no tens el compte muntat, comença pels primers passos.
• Per fitxar en una tauleta compartida no necessites l'API: fes servir el quiosc QR.