API REST v1

AccessTime-ren API REST-a gure aplikazio mugikorrak erabiltzen duen bera da: aplikazioak egiten duen guztia hemendik pasatzen da. Zure integrazio txikietarako ere erabil dezakezu, adibidez eguneko fitxaketak script batetik kontsultatzeko edo beste tresna batetik absentzia bat eskatzeko.

Oinarrizko URLa https://zuredomeinua/api/v1 da, eskaera eta erantzun guztiak JSON dira, eta babestutako bideek Authorization: Bearer {token} goiburua behar dute.

1. Lortu token bat

Autentifikazioak token pertsonalak erabiltzen ditu (Laravel Sanctum), cookierik eta saiorik gabe. Tokena langilearen email eta pasahitzarekin lortzen da, web panelean sartzeko erabiltzen dituen berberekin:

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

Erantzunak tokena eta erabiltzailearen oinarrizko datuak dakartza:

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

Gorde tokena leku seguru batean eta ez partekatu: pertsona horren datuetarako sarbidea ematen du. Kredentzialak baliozkoak ez badira 422 bat jasoko duzu, eta endpoint-a 10 saiakera minutuko mugatuta dago.

Saioa ixteko, POST /api/v1/logout (autentifikatua) egiteak uneko tokena errebokatzen du.

2. Endpoint erabilgarriak

Endpoint guztiek autentifikatutako erabiltzailearen gainean jarduten dute: pertsona bakoitzak bere fitxaketak, bere absentziak eta bere saldoa bakarrik ikusten ditu.

3. APItik fitxatzea

POST /fichar-ek automatikoki txandakatzen ditu sarrera eta irteera azken fitxaketaren arabera, panelaren botoiak bezala (nola funtzionatzen duen fitxaketak). Geolokalizazioa aukerakoa da:

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

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

Fitxaketak UTCn gordetzen dira, eta "gaur" eta "aste" kontsultek zure enpresaren ordu-eremua erabiltzen dute. Hileko laburpena gauero sendotutako lanaldietatik kalkulatzen da, txostenak elikatzen dituzten berberetatik.

Pertsona doako planaren 10 plaza aktiboetatik kanpo geratzen bada, POST /fichar-ek 403 erantzuten du (planak eta fakturazioa).

4. Absentziak APItik

Mota erabilgarriak eta saldoa kontsulta ditzakezu, eta absentzia bat eskatu:

curl -X POST https://zuredomeinua/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": "Oporrak" }'

APIak panelaren balidazio berberak aplikatzen ditu: norberaren beste absentziekiko gainjartzeak, deskontatzen duten motetan saldo erabilgarria eta tarteak lanegunak izatea (asteburuak eta jaiegunak deskontatzen ditu). Motak onespena behar badu, eskaera onespen-fluxuan sartzen da pending egoerarekin; behar ez badu, zuzenean onartuta geratzen da. Xehetasun gehiago absentziak eta oporrak atalean.

Justifikagiria eskatzen duten absentzia motak ezin dira APItik eskatu: eskaerak errore bat itzultzen du eta web paneletik egin behar da, han bai erants baitaiteke dokumentua.

Eta orain zer?

• Kontua oraindik muntatu gabe baduzu, hasi lehen urratsetatik.
• Tablet partekatu batean fitxatzeko ez duzu APIrik behar: erabili QR kioskoa.