API REST v1

La API REST de AccessTime es la misma que usa nuestra app móvil: todo lo que hace la app pasa por aquí. También puedes usarla para pequeñas integraciones propias, por ejemplo consultar los fichajes del día desde un script o solicitar una ausencia desde otra herramienta.

La URL base es https://tudominio/api/v1, todas las peticiones y respuestas son JSON y las rutas protegidas requieren la cabecera Authorization: Bearer {token}.

1. Consigue un token

La autenticación usa tokens personales (Laravel Sanctum), sin cookies ni sesión. El token se obtiene con el email y la contraseña del empleado, los mismos con los que entra al panel web:

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

La respuesta incluye el token y los datos básicos del usuario:

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

Guarda el token en un lugar seguro y no lo compartas: da acceso a los datos de esa persona. Si las credenciales no son válidas recibirás un 422, y el endpoint está limitado a 10 intentos por minuto.

Para cerrar sesión, POST /api/v1/logout (autenticado) revoca el token actual.

2. Endpoints disponibles

Todos los endpoints operan sobre el usuario autenticado: cada persona ve solo sus fichajes, sus ausencias y su saldo.

3. Fichar desde la API

POST /fichar alterna automáticamente entre entrada y salida según el último fichaje, igual que el botón del panel (cómo funciona el fichaje). La geolocalización es 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 }'

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

Los fichajes se guardan en UTC y las consultas de "hoy" y "semana" usan la zona horaria de tu empresa. El resumen mensual se calcula a partir de las jornadas consolidadas cada noche, las mismas que alimentan los informes.

Si la persona queda fuera de las 10 plazas activas del plan gratuito, POST /fichar responde 403 (planes y facturación).

4. Ausencias desde la API

Puedes consultar los tipos disponibles, el saldo y solicitar una ausencia:

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

La API aplica las mismas validaciones que el panel: solapamientos con otras ausencias propias, saldo disponible en los tipos que descuentan y que el rango contenga días laborables (descuenta fines de semana y festivos). Si el tipo requiere aprobación, la solicitud entra en el flujo de aprobaciones con estado pending; si no, queda aprobada directamente. Más detalle en ausencias y vacaciones.

Los tipos de ausencia que exigen justificante no se pueden solicitar por API: la petición devuelve un error y hay que hacerla desde el panel web, donde sí se puede adjuntar el documento.

¿Y ahora qué?

• Si aún no tienes la cuenta montada, empieza por primeros pasos.
• Para fichar en una tablet compartida no necesitas la API: usa el kiosco QR.