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.

2. Endpoints disponibles

Tots els endpoints operen sobre l'usuari autenticat: cada persona veu només els seus fitxatges, les seves absències i el seu saldo.

3. Fitxar des de l'API

POST /fichar alterna automàticament entre entrada i sortida segons l'últim fitxatge, igual que el botó del panell (com funciona el fitxatge). La geolocalització és opcional:

curl -X POST https://tudominio/api/v1/fichar \
  -H "Authorization: Bearer 1|abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "latitude": 40.4168, "longitude": -3.7038, "accuracy": 12 }'

Resposta 201: { "type": "in", "happened_at": "2026-07-07T09:00:00+00:00" }.

Els fitxatges es guarden en UTC i les consultes de "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 persona queda fora de les 10 places actives del pla gratuït, POST /fichar respon 403 (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.