Presencia

La presencia responde a dos preguntas en vivo: ¿quién trabaja ahora mismo? y ¿quién está hoy en oficina y quién en remoto? No es un CRUD sobre una tabla propia — es un read-model derivado compuesto a partir de tres fuentes: la plantilla de empleados, el estado de fichaje derivado del ledger de jornada, y el horario vigente. El estado de trabajo en vivo (working, paused, finished, away) y el indicador de llegada tarde se computan al leer, nunca se persisten.

En la API v1, la presencia es de solo lectura (presence:read), bajo https://api.factuarea.com/v1. No existe el scope presence:write: declarar la presencialidad oficina/remoto es una tarea solo-portal que realiza el propio empleado.

El panel de equipo en vivo

GET /v1/presence devuelve el panel en vivo: un item por empleado activo con su estado de trabajo actual, desde cuándo lleva abierta la franja actual, y si llegó tarde respecto a su hora de entrada planificada, más contadores agregados (trabajando, en pausa, ausente, en remoto).

curl https://api.factuarea.com/v1/presence \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

El estado de trabajo se deriva del último evento de la franja abierta de cada empleado en el ledger: clock_in/pause_end → working, pause_start → paused, clock_out → finished, sin franja abierta → away. La llegada tarde compara el primer fichaje de entrada del día con la hora planificada leída del horario del empleado.

Presencialidad diaria oficina/remoto

GET /v1/presence/daily lista la presencialidad diaria —oficina frente a remoto— con filtros por empleado, fecha o rango y paginación por cursor. GET /v1/presence/{employee} devuelve la presencia de un solo empleado por su id (UUID v7); un empleado de otra empresa devuelve 404.

curl -G https://api.factuarea.com/v1/presence/daily \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "date=2026-02-03"

La presencialidad diaria (oficina o remoto) es el único dato que la presencia guarda de verdad: un registro por empleado y día. Declararla de nuevo para el mismo día cambia la localización en vez de crear un duplicado. Consulta los esquemas en la Referencia de API.

Flujo típico

1. Sondea GET /v1/presence para un tablero en vivo de quién trabaja, está en pausa o ausente.
2. Lee GET /v1/presence/daily para ver el reparto oficina/remoto de una fecha.
3. Profundiza en una persona con GET /v1/presence/{employee}.

Como la presencia es derivada, las cifras siempre reflejan el estado actual del ledger y de los horarios — nunca necesitas mantener una tabla de presencia aparte sincronizada.

Próximos pasos

• Fichajes — el ledger del que se deriva el estado en vivo.
• Horarios — la hora planificada que usa el indicador de llegada tarde.