Time tracking overview
The workforce system over the v1 API — the immutable time-record ledger (RD-ley 8/2019), the portal-only employee role, the per-seat add-on and the eight domains that make it up.
Factuarea's time tracking (control horario) covers the legal duty of Spanish employers under RD-ley 8/2019 (art. 34.9 of the Workers' Statute): keep an objective, reliable and unalterable daily record of every employee's working day, retain it for four years and make it available to the Labour Inspectorate (ITSS). The record is built on an append-only ledger sealed by a per-company SHA-256 hash chain — the same tamper-evidence pattern Factuarea uses for VeriFactu invoicing. It is, in short, the VeriFactu of attendance: nothing is ever edited or deleted, and any manipulation breaks the chain.
Every operation lives under https://api.factuarea.com/v1 and shares the same
error envelope, cursor pagination and
scopes as the rest of the API. The whole
surface is gated by the control_horario module; a company without it gets a
403 on these routes.
The employee, a portal-only role
An employee is the worker who clocks in, has a schedule, requests absences and
accrues day balances. It is a portal-only role: employees operate their own
data from the portal and are never counted against the plan users seat
limit. Adding employees is instead billed through a dedicated per-seat add-on —
see Employee seat billing.
The eight domains
The system is split into eight API domains. Start with the guide for the task at hand; each links to its endpoints in the API Reference.
| Domain | What it does | Guide | Scope |
|---|---|---|---|
| Employees | The staff roster: create, update, deactivate, reactivate. | — | employees:read / employees:write |
| Work schedules | Expected weekly hours and effective-dated assignments. | Work schedules | work_schedules:read / work_schedules:write |
| Time entries | Clock in/out, pauses, retroactive entries, corrections. | Time clock | time_entries:read / time_entries:write |
| Monthly closes | Freeze, seal, report and export the monthly register. | Monthly close | time_entries:read / time_entries:write |
| Payroll exports | Incidents file for A3, Sage or NominaSOL. | Monthly close | payroll_exports:read |
| Absences | Types, policies, requests, balances and calendar. | Absences | absences:read / absences:write |
| Presence | Who is working now, in office or remote. | Presence | presence:read |
| Public holidays | National, regional and local calendar per region. | — | holidays:read |
Two domains are read-only over the API: presence and public
holidays expose only reads (presence:read, holidays:read). Declaring
office/remote presence and creating custom local holidays are portal-only tasks —
there is no presence:write nor holidays:write scope.
Employees and their roster
The employee is the anchor entity the rest of the system depends on. Each employee
carries a name, a company-unique email, an optional tax_id and job_title,
contracted weekly hours, a hire date and the autonomous community (ccaa) that
drives which public holidays apply. Deactivation is a soft termination: the
employee keeps their ledger history (the four-year retention forbids destroying
it) and can be reactivated later.
curl -X POST https://api.factuarea.com/v1/employees \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ana Ruiz",
"email": "ana.ruiz@acme.example",
"employment_type": "full_time",
"contract_hours": 40,
"hire_date": "2026-01-07",
"ccaa": "ES-MD"
}'See the full employee schemas in the API Reference.
Scopes and MCP
Every domain maps to a fine-grained scope from the closed catalogue
(employees:*, time_entries:*, work_schedules:*, absences:*,
presence:read, holidays:read, payroll_exports:read), all gated behind the
control_horario module. Review the full list on the
scopes page and the
MCP scopes catalogue. Each v1 route mirrors a public
MCP tool, so an agent can drive the same operations.
The time-record ledger is compliance data, isolated by design: it never references clients, invoices or projects. It answers one question — how many hours each employee worked — and keeps that evidence intact.
Where to go next
- Time clock — clock in/out, pauses and the correction workflow.
- Monthly close — freeze, seal and export the register.
- Absences — types, policies, requests, balances and carryover.
- Work schedules — weekly patterns and assignments.
- Presence — the live team panel and daily office/remote view.
- Employee seat billing — the per-seat add-on and its cycle.