API REST v1

A API REST de AccessTime é a mesma que usa a nosa app móbil: todo o que fai a app pasa por aquí. Tamén podes usala para pequenas integracións propias, por exemplo consultar as fichaxes do día desde un script ou solicitar unha ausencia desde outra ferramenta.

A URL base é https://oteudominio/api/v1, todas as peticións e respostas son JSON e as rutas protexidas requiren a cabeceira Authorization: Bearer {token}.

1. Consegue un token

A autenticación usa tokens persoais (Laravel Sanctum), sen cookies nin sesión. O token obtense co email e o contrasinal do empregado, os mesmos cos que entra no panel web:

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

A resposta inclúe o token e os datos básicos do usuario:

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

Garda o token nun lugar seguro e non o compartas: dá acceso aos datos desa persoa. Se as credenciais non son válidas recibirás un 422, e o endpoint está limitado a 10 intentos por minuto.

Para pechar sesión, POST /api/v1/logout (autenticado) revoga o token actual.

2. Endpoints dispoñibles

Todos os endpoints operan sobre o usuario autenticado: cada persoa ve só as súas fichaxes, as súas ausencias e o seu saldo.

3. Fichar desde a API

POST /fichar alterna automaticamente entre entrada e saída segundo a última fichaxe, igual ca o botón do panel (como funciona a fichaxe). A xeolocalización é opcional:

curl -X POST https://oteudominio/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" }.

As fichaxes gárdanse en UTC e as consultas de "hoxe" e "semana" usan a zona horaria da túa empresa. O resumo mensual calcúlase a partir das xornadas consolidadas cada noite, as mesmas que alimentan os informes.

Se a persoa queda fóra das 10 prazas activas do plan gratuíto, POST /fichar responde 403 (plans e facturación).

4. Ausencias desde a API

Podes consultar os tipos dispoñibles, o saldo e solicitar unha ausencia:

curl -X POST https://oteudominio/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": "Vacacións" }'

A API aplica as mesmas validacións ca o panel: solapamentos con outras ausencias propias, saldo dispoñible nos tipos que descontan e que o rango conteña días laborables (desconta fins de semana e festivos). Se o tipo require aprobación, a solicitude entra no fluxo de aprobacións con estado pending; se non, queda aprobada directamente. Máis detalle en ausencias e vacacións.

Os tipos de ausencia que esixen xustificante non se poden solicitar por API: a petición devolve un erro e hai que facela desde o panel web, onde si se pode achegar o documento.

E agora que?

• Se aínda non tes a conta montada, empeza polos primeiros pasos.
• Para fichar nunha tableta compartida non necesitas a API: usa o quiosco QR.