Fitxatges

Fitxar escriu en un ledger de només apèndix: fitxar entrada, pausar, reprendre i fitxar sortida apendixen cadascun una entrada nova que mai s'edita ni s'esborra. Cada entrada s'encadena a l'anterior amb una empremta SHA-256 (cadena per empresa), de manera que qualsevol manipulació és detectable. L'estat de la jornada en viu —not_started, working, paused, finished— es deriva del ledger, no es desa en una columna.

Tots els endpoints viuen sota https://api.factuarea.com/v1 i usen els scopes time_entries:read / time_entries:write, el mateix embolcall d'error i paginació per cursor que la resta de l'API.

Fitxar entrada, pausar, reprendre, sortir

Quatre operacions d'escriptura governen la jornada. Cadascuna accepta un occurred_at opcional (per defecte, ara) i un source, i retorna l'entrada apendixada.

Dues regles regeixen la seqüència. Una jornada oberta alhora: fitxar entrada dos cops retorna 422 ("Ya has fichado la entrada."); pausar o fitxar sortida sense jornada oberta retorna 422. Cronologia monòtona: un occurred_at anterior a l'últim esdeveniment de la franja es rebutja amb 422. Una jornada pot tenir diverses franges (jornada partida) — tornar a fitxar entrada després de la sortida obre una franja nova.

curl -X POST https://api.factuarea.com/v1/time-entries/clock-in \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": "web" }'

Llegeix la sessió oberta actual amb GET /v1/time-entries/current, llista entrades amb GET /v1/time-entries i obtén-ne una amb GET /v1/time-entries/{time_entry} — tot sota time_entries:read. Consulta els esquemes a la Referència d'API.

Fitxatges retroactius (manuals)

POST /v1/time-entries/manual registra una franja passada completa (entrada, pauses opcionals i sortida) per a un empleat que va oblidar fitxar. El reason és obligatori — es segella a la cadena d'empremtes com a part de l'evidència — i l'entrada es marca is_retroactive amb source: manual. A diferència del fitxatge live self-service, un fitxatge manual és una acció privilegiada i es registra a l'audit log.

curl -X POST https://api.factuarea.com/v1/time-entries/manual \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b",
    "started_at": "2026-02-03T09:00:00+01:00",
    "ended_at": "2026-02-03T17:00:00+01:00",
    "reason": "Va oblidar fitxar; confirmat pel responsable"
  }'

El flux de correccions

Un registre de jornada mai s'edita. Per esmenar un error, un empleat obre una sol·licitud de correcció; un manager o admin l'aprova o la rebutja. Una sol·licitud passa pending → approved o pending → rejected, tots dos terminals.

L'aprovació apendixa una entrada nova que referencia l'original — l'error i la seva esmena queden tots dos al ledger. Dues guardes apliquen: no pots aprovar la teva pròpia sol·licitud (422), i una sol·licitud ja resolta no es resol de nou (422).

curl -X POST https://api.factuarea.com/v1/time-corrections/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/approve \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Verificat amb el registre de fitxatges" }'

Verificar la integritat de la cadena

GET /v1/time-entries/chain/validate recalcula tota la cadena d'empremtes i informa de si està intacta, retornant l'id de la primera entrada trencada si n'hi ha. És una comprovació d'integritat de només lectura (amb límit de taxa) — fes-la servir per demostrar que el registre no ha estat alterat.

Pròxims passos

• Horaris — les hores esperades contra les quals es mesura el ledger.
• Tancament mensual — congelar i segellar un mes finalitzat.
• Explora la referència de fitxatges i correccions.