Fichajes

Fichar escribe en un ledger de solo apéndice: fichar entrada, pausar, reanudar y fichar salida apéndican cada uno una entrada nueva que jamás se edita ni se borra. Cada entrada se encadena a la anterior con una huella SHA-256 (cadena por empresa), de modo que cualquier manipulación es detectable. El estado de la jornada en vivo —not_started, working, paused, finished— se deriva del ledger, no se guarda en una columna.

Todos los endpoints viven bajo https://api.factuarea.com/v1 y usan los scopes time_entries:read / time_entries:write, el mismo envoltorio de error y paginación por cursor que el resto de la API.

Fichar entrada, pausar, reanudar, salir

Cuatro operaciones de escritura gobiernan la jornada. Cada una acepta un occurred_at opcional (por defecto, ahora) y un source, y devuelve la entrada apéndicada.

Dos reglas rigen la secuencia. Una jornada abierta a la vez: fichar entrada dos veces devuelve 422 ("Ya has fichado la entrada."); pausar o fichar salida sin jornada abierta devuelve 422. Cronología monótona: un occurred_at anterior al último evento de la franja se rechaza con 422. Una jornada puede tener varias franjas (jornada partida) — volver a fichar entrada tras la salida abre una franja nueva.

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

Lee la sesión abierta actual con GET /v1/time-entries/current, lista entradas con GET /v1/time-entries y obtén una con GET /v1/time-entries/{time_entry} — todo bajo time_entries:read. Consulta los esquemas en la Referencia de API.

Fichajes retroactivos (manuales)

POST /v1/time-entries/manual registra una franja pasada completa (entrada, pausas opcionales y salida) para un empleado que olvidó fichar. El reason es obligatorio — se sella en la cadena de huellas como parte de la evidencia — y la entrada se marca is_retroactive con source: manual. A diferencia del fichaje live self-service, un fichaje manual es una acción privilegiada y se registra en el 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": "Olvidó fichar la entrada; confirmado por el responsable"
  }'

El flujo de correcciones

Un registro de jornada nunca se edita. Para enmendar un error, un empleado abre una solicitud de corrección; un manager o admin la aprueba o la rechaza. Una solicitud pasa pending → approved o pending → rejected, ambos terminales.

La aprobación apéndica una entrada nueva que referencia a la original — el error y su enmienda quedan ambos en el ledger. Dos guardas aplican: no puedes aprobar tu propia solicitud (422), y una solicitud ya resuelta no se resuelve de nuevo (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": "Verificado contra el registro de accesos" }'

Verificar la integridad de la cadena

GET /v1/time-entries/chain/validate recalcula toda la cadena de huellas e informa de si está intacta, devolviendo el id de la primera entrada rota si la hay. Es una comprobación de integridad de solo lectura (con límite de tasa) — úsala para demostrar que el registro no ha sido alterado.

Próximos pasos

• Horarios — las horas esperadas contra las que se mide el ledger.
• Cierre mensual — congelar y sellar un mes finalizado.
• Explora la referencia de fichajes y correcciones.