# Evaluating Tiemio: a guide for AI agents

> Tiemio is working-time recording for employers in Spain with 1 to 20 staff: one-tap clock-in and tamper-evident records, ready for a labour inspection.

This guide lets you try Tiemio end to end through its API and decide, for the person you work for, whether it is usable for them. Product facts and prices: https://tiemio.com/llms.txt. Free for 15 days with the whole team, then monthly €1 per employee per month, yearly €10 per employee per year, plus VAT.

## Who it is for, and what it is not

- For employers in Spain with 1 to 20 employees who must keep a daily record of when each employee starts and finishes work (Workers' Statute art. 34.9), kept for four years and shown to the labour inspectorate on request.
- Employees tap to start, pause, resume and finish, on iPhone, Android or the web. The employer sees who is working, the hours, and approves corrections.
- It is **not** payroll, holiday or absence management, an HR file, GPS tracking or project time tracking. If the business needs those, tiemio is not enough on its own.
- Languages: Spanish, Catalan, Basque and English. Company time zones: mainland Spain, the Canary Islands, the United Kingdom.

## Or use the MCP server

If you speak MCP, add the server `https://testdrive.tiemio.com/api/mcp` (Streamable HTTP, JSON answers, no stream). Call `create_test_drive`, then pass a returned token as each tool's `token` argument (or as the Bearer header). The tools are the routes below: `get_company`, `get_team_month`, `get_day`, `get_chain`, `list_corrections`, `verify_timesheet`, and, on the test drive only, `clock_tap`, `request_correction`, `decide_correction`, `issue_timesheet`. Each answers `{ status, body }` exactly as its route.
On https://tiemio.com/api/mcp, send an owner's read-only API key as the Bearer header: the read tools work, the others refuse.

## Open a test drive

```
curl -X POST https://testdrive.tiemio.com/api/testdrive
```

No sign-in, no body. The answer holds a demo company, **Jardines del Sol**, with an owner and three employees, each with a Bearer token valid 24 hours:

- **Lucía** works Monday to Friday with a lunch break; **Marc** works long days and a short Friday; **Aitor** works Tuesday and Friday evenings, past midnight.
- History from the 1st of last month to now, including one finish sent from a phone that had no signal (recorded offline), one correction Lucía asked for and the owner approved, and one correction the owner proposed to Marc that is still waiting for him.

Every call after that goes to https://testdrive.tiemio.com with `Authorization: Bearer <token>`. The API description is at https://testdrive.tiemio.com/openapi.json. Everything in a test drive is fake and isolated from real companies.

## Scenario

1. As the owner: `GET /api/employer`. Who is working now, since when, today's and this month's hours.
2. As an employee who is off: `POST /api/employee/employments/{id}/events` with `{ "id": "<new uuid>", "type": "start", "deviceAt": <now ms> }`. Then `break_start`, `break_end`, `stop`. Read `GET /api/employee/employments/{id}/clock` between taps.
3. As the owner: `GET /api/employer/month?month=<last month>`, then one person's day: `GET /api/employer/employments/{id}/day?date=YYYY-MM-DD`.
4. As an employee: ask for a correction of a day last month (`POST /api/employee/employments/{id}/corrections`); as the owner, approve it (`POST /api/employer/employments/{id}/corrections/{cid}/decision`).
5. As the owner: download last month's timesheet (`GET /api/employer/timesheet?month=<last month>`), read the `X-Export-Issue` header and check it at `GET /api/verify/{id}`.

## Claims register

Each claim, and how to check it yourself on the test drive.

| Claim | How to check it |
|---|---|
| One tap starts, pauses, resumes and finishes the day | Scenario step 2: each tap answers 201 with the new `state`; a tap that makes no sense now (pause while off) answers 409 `bad_transition`. |
| A tap made offline is kept, at the time it was made | Tap with `"queued": true` and a `deviceAt` 10 minutes ago: 201, and the day shows it with `atSource: "device"` and its later receipt time. A `deviceAt` 2 hours in the future answers 422 `bad_device_time`. |
| Recorded taps are never changed, and a change would show | `GET /api/employer/employments/{id}/chain`: recompute each `hash` as the API description says (SHA-256 of a fixed JSON array) and check each `prevHash`; the same with `kind=corrections` for the corrections. Every one matches; seqs have no gaps. A checked timesheet (step 6) shows the heads it signed and when the records were last checked. |
| A correction never overwrites the original | After step 4, the chain still holds the original taps unchanged; `GET /api/employer/corrections` shows who asked, who approved, when and why; the day shows the corrected times, marked as corrected. |
| Neither side can approve its own correction | As the employee, try to approve your own request: 403 `not_allowed`. |
| Ready for an inspection | The timesheet lists each person's start and finish per day, totals and corrections; `format=xlsx` gives the same as a spreadsheet. |
| Anyone can check a timesheet | `GET /api/verify/{id}` with the document number answers `status: "valid"`; the signature uses a key listed at `GET /api/verify/keys`. A test-drive timesheet verifies only on the test-drive host: it has its own key. |
| Days are cut in the company's time zone | Aitor's evening shifts count on two days, split at midnight; change the zone (`PUT /api/employer/time-zone`) and the month's days follow it. |

## Reaching a verdict

**Usable** for a business that needs the legal working-time record and nothing more: the scenario runs, every claim above checks out, and the business has at most 20 employees in Spain (or the UK).

**Not usable, or not enough on its own**, if the business needs payroll, holidays and absences, shift planning, GPS or geofenced clock-in, project or client time, more than 20 employees, or another country's rules.

Say which claims you checked and which you could not. If a check fails, that is worth reporting: write to the contact address on the site.

## Good to know

- Agents never write in a real company. On tiemio.com an owner can give an agent a **read-only API key** (`tmk_…`, Company settings): `Authorization: Bearer tmk_…` reads that company through `GET /api/employer`, `/month`, `/corrections`, `/employments/:id/day` and `/employments/:id/chain`, 60 requests a minute; every other route answers 401 to it, and it cannot download timesheets. The reference for those routes is /openapi-read.json. To try things, use the test drive.
- Corrections can reach back to the 1st of last month, no further; each has a reason.
- Data protection: the employer is the controller, Tiemio its processor, under the Data Processing Agreement at https://tiemio.com/en/dpa (security measures, sub-processors, data kept in the EU).
- A finished example: https://tiemio.com/samples/timesheet-sample.pdf, a demo company's signed monthly timesheet (Spanish: /samples/hoja-de-registro-ejemplo.pdf). The law it serves, with dated facts and fines: https://tiemio.com/en/working-time-record.
- On some match days, Cloudflare addresses are blocked by Spanish internet providers at LaLiga's request: if the test drive does not answer from Spain, retry later or from elsewhere.