Presència

La presència respon a dues preguntes en viu: qui treballa ara mateix? i qui és avui a l'oficina i qui en remot? No és un CRUD sobre una taula pròpia — és un read-model derivat compost a partir de tres fonts: la plantilla d'empleats, l'estat de fitxatge derivat del ledger de jornada, i l'horari vigent. L'estat de treball en viu (working, paused, finished, away) i l'indicador d'arribada tard es computen en llegir, mai es persisteixen.

A l'API v1, la presència és de només lectura (presence:read), sota https://api.factuarea.com/v1. No existeix l'scope presence:write: declarar la presencialitat oficina/remot és una tasca només-portal que fa el mateix empleat.

El panell d'equip en viu

GET /v1/presence retorna el panell en viu: un item per empleat actiu amb el seu estat de treball actual, des de quan té oberta la franja actual, i si va arribar tard respecte a la seva hora d'entrada planificada, més comptadors agregats (treballant, en pausa, absent, en remot).

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

L'estat de treball es deriva de l'últim esdeveniment de la franja oberta de cada empleat al ledger: clock_in/pause_end → working, pause_start → paused, clock_out → finished, sense franja oberta → away. L'arribada tard compara el primer fitxatge d'entrada del dia amb l'hora planificada llegida de l'horari de l'empleat.

Presencialitat diària oficina/remot

GET /v1/presence/daily llista la presencialitat diària —oficina enfront de remot— amb filtres per empleat, data o rang i paginació per cursor. GET /v1/presence/{employee} retorna la presència d'un sol empleat pel seu id (UUID v7); un empleat d'una altra empresa retorna 404.

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

La presencialitat diària (oficina o remot) és l'únic dada que la presència desa de veritat: un registre per empleat i dia. Declarar-la de nou per al mateix dia canvia la localització en comptes de crear un duplicat. Consulta els esquemes a la Referència d'API.

Flux típic

1. Sondeja GET /v1/presence per a un tauler en viu de qui treballa, està en pausa o absent.
2. Llegeix GET /v1/presence/daily per veure el repartiment oficina/remot d'una data.
3. Aprofundeix en una persona amb GET /v1/presence/{employee}.

Com que la presència és derivada, les xifres sempre reflecteixen l'estat actual del ledger i dels horaris — mai necessites mantenir una taula de presència a part sincronitzada.

Pròxims passos

• Fitxatges — el ledger del qual es deriva l'estat en viu.
• Horaris — l'hora planificada que usa l'indicador d'arribada tard.