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.

Tokenak 90 egunen buruan iraungitzen dira: login-aren erantzunak data dakar token_expires_at eremuan, eta hura igarotakoan APIak 401 erantzuten du eta beste bat eskatu behar da. Login-ean device_name bidaltzen baduzu («Anaren iPhonea»), tokena izen horrekin agertzen da Profila → Sarbidea duten gailuak atalean, eta hortik baliogabe dezake pertsonak.

2. Endpoint erabilgarriak

Endpoint guztiek autentifikatutako erabiltzailearen gainean jarduten dute: pertsona bakoitzak bere fitxaketak, absentziak eta saldoa bakarrik ikusten ditu. Mezuak (message) pertsonaren hizkuntzan iristen dira, eta 403 bakoitzak zer gertatzen den adierazten duen code bat dakar: solo_lectura, empresa_bloqueada, cuenta_desactivada, email_no_verificado edo sin_empresa.

3. APItik fitxatzea

Fitxaketa bakoitzak client_uuid bat darama: UUID bat, behin sortzen duzuna, lehen saiakeraren aurretik, eta saiakera bakoitzean errepikatzen duzuna. Horrela, sarea eteten bada eta berriro saiatzen bazara, fitxaketa ez da inoiz bikoizten (hura gabe, 422). Bidali type ere (in edo out); ematen ez baduzu, azken fitxaketaren arabera txandakatzen da, panelaren botoiak bezala (nola dabilen fitxaketa).

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" }'

201 erantzuna fitxaketarekin (status, id, type, happened_at…). client_uuid berarekin egindako saiakera batek 200 eta gorputz bera itzultzen ditu.

• Ordua zerbitzariarena da. Konexiorik gabe harrapatutakoa offline: true, captured_at (mugikorraren ordua sakatzean) eta sent_at (mugikorraren ordua bidaltzean) eremuekin berriro bidaltzen da: zerbitzariak erlojuaren desfasea zuzentzen du. 72 ordu baino geroago iristen bada, berrikusteko zain dagoen gorabehera gisa geratzen da (202): ez da galtzen. Bere orduaren ondoren jasota dagoen lehenengoa, 5 minutu baino gutxiago geroago, mota bereko fitxaketa bat bada (pertsonak kioskoan edo panelean errepikatu zuen ilaran zain zegoen bitartean), fitxaketa bera da errepikatuta: 200 "duplicate": true eta jasota dagoenarekin. Fitxaketa hori berrikusteko zain badago, 202 da, "duplicate": true eta gorabehera horrekin. Eta 5 minutu baino gutxiagora jasota dagoena eskuz erregistratutako mota bereko fitxaketa bat bada, sakatu ondoren erregistratua (ilara iritsi aurretik onartutako ahaztutako bat edo onartutako zuzenketa bat): minutu berean, 200 erantzunak hori dakar; beste minutu batean, bidalitakoa da balio duena: eskuz erregistratutakoa baliogabetu egiten da (ikusgai jarraitzen du) eta 200 "duplicate": true erantzunak bidalitako client_uuid-arekin erregistratutako fitxaketa dakar.
• Kokapena (latitude, longitude, accuracy): enpresak aktibatuta badu bakarrik (geolocation_mode /config-en); bestela, baztertu egiten da. obligatoria bada, kokapenik gabe une horretan egindako fitxaketak 422 jasotzen du.
• Mugikorreko egiaztapena (verification, aukerakoa): telefonoak berak egindakoaren emaitza bakarrik, inoiz ez datu biometrikorik: {"method": "biometric_local" | "pin" | "none", "verified": true | false, "os_auth_type": "face" | "fingerprint" | "credential" | null}. Zure aplikazioak adierazten duena da: zerbitzariak ezin du egiaztatu. Zuriuneak kentzen dira, eta testu huts batek null balio du. Formatu hori betetzen ez badu, baztertu egiten da: fitxaketa erregistratu egiten da hala ere, eta erantzunak "verification_discarded": true dakar (inoiz ez 422); beste gakoak ez dira kontuan hartzen. Fitxaketan geratzen da, eta pertsonak «Nire erregistroa» atalean ikusten du.
• known_ms (aukerakoa): sakatzean zure aplikazioak ezagutzen zuen azken fitxaketaren ordua, milisegundotan, zerbitzariarena (/config-ekoa edo azken erantzunekoa), ez mugikorrarena. Ondoren mota bereko beste bat badago eta zerbitzariak sakatzean bazuen (adibidez, kioskoan) edo zure aplikazioak lehenago bidali bazuen konexiorik gabeko ilaratik, dagokiona erregistratzen da, panelaren botoiak egiten duen bezala, salbu eta fitxaketa hori duela 5 minutu baino gutxiagokoa bada eta ilara horretatik ez badator: fitxaketa bera errepikatua da, eta erantzuna 200 da, "duplicate": true eta dagoeneko dagoenarekin. known_ms gabe gauza bera gertatzen da mota bereko fitxaketa hori, duela 5 minutu baino gutxiagokoa, beste kanal batetik egin bazen (kioskoa edo panela); baina denbora gehiagoko botoi desfasatua ez da zuzentzen, beraz, bidali beti.
• Erroreak: 422 behin betikoa da (erakutsi arrazoia); 401, 429, 5xx edo sarerik gabe, gorde fitxaketa eta saiatu berriro client_uuid berarekin.

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

Enpresaren doako proba harpidetzarik gabe amaitu bada, kontua irakurtzeko soilik dago eta POST /fichar-ek 403 erantzuten du (solo_lectura). Kontsulta-endpointek funtzionatzen jarraitzen dute (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.