Para desarrolladores

API de Tiemio

Lee los registros de jornada de tu empresa desde tus propias herramientas: una hoja de nóminas, un informe, un asistente de IA. La API es de solo lectura, así que nada fuera de la aplicación puede cambiar el registro.

Qué hace y qué no hace

Lee tu equipo, las horas de cada persona por día, los fichajes de cada día, las correcciones y la cadena de hashes.
No puede fichar, cambiar ni aprobar nada. El fichaje lo hace el trabajador y cada cambio lo aprueba una persona: eso es lo que da valor de prueba al registro.
No puede descargar hojas de registro: cada descarga queda anotada como prueba de a quién se entregó qué, así que se hace en la aplicación.
Una clave nunca ve el DNI/NIE, el email ni el teléfono de una persona, ni el texto de las notas de horas. Sí ve los motivos de las correcciones, porque forman parte del registro.
No hay webhooks. Para ver los cambios, vuelve a leer.

Consigue una clave

Entra como titular de la empresa y abre la página Empresa.
En Claves de API, ponle un nombre a la clave y créala.
Cópiala en ese momento: se muestra una sola vez. Solo guardamos un hash.
Envíala en cada llamada como Authorization: Bearer <clave>. Guárdala en tu servidor, nunca en una página web ni en una aplicación: quien la tenga puede leer los registros de tus empleados.
Puedes revocar una clave cuando quieras. El titular recibe un email por cada clave nueva.

Tu primera llamada

curl -H "Authorization: Bearer tmk_your_key" \
  "https://tiemio.com/api/employer/month?month=2026-09"

La respuesta da los milisegundos trabajados por persona y día, con las correcciones aprobadas ya aplicadas. El índice 0 es el día 1 del mes.

{
  "month": "2026-09",
  "today": "2026-10-30",
  "timeZone": "Europe/Madrid",
  "days": 30,
  "people": [
    {
      "employmentId": "emp_01",
      "personId": "usr_01",
      "name": "Ana García",
      "from": "2026-01-12",
      "until": null,
      "workedMs": [28800000, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "flagged": [false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false]
    }
  ]
}

Las cinco rutas

GET /api/employer: La empresa y su gente, con el fichaje actual de cada persona activa. Usa aquí el id de la relación laboral (employment) para las rutas siguientes.
GET /api/employer/month?month=YYYY-MM: El tiempo trabajado por persona y día en un mes, y qué días quedan fuera del horario de la persona.
GET /api/employer/employments/{id}/day?date=YYYY-MM-DD: Un día de una persona: cada fichaje, con la hora del dispositivo, la de recepción, si esperó sin conexión, y las correcciones resueltas ese día.
GET /api/employer/corrections: Las correcciones de la empresa: quién las pidió, quién decidió, cuándo y por qué. Añade ?status=pending o ?employment=<id> para acotar.
GET /api/employer/employments/{id}/chain: Cada fichaje tal como se calculó su hash, 500 por página, para que tu herramienta recalcule la cadena. Añade ?after=<next> para la página siguiente y ?kind=corrections para las filas de correcciones.

Leer un mes sin llegar al límite

Para los totales, una llamada a month cubre todo el equipo.
Las horas de entrada y salida necesitan una llamada a day por persona y día. Con 20 personas y 31 días son 620 llamadas, unos 11 minutos al límite, así que espácialas.
Los días se cortan en la zona horaria de la empresa, que viene en cada respuesta. Los instantes van en UTC.
Hazlo una vez, cuando el mes haya cerrado, en lugar de consultar continuamente.

Límites y errores

60 peticiones por minuto, por clave y por dirección del cliente. Por encima: 429 con el código rate_limited y Retry-After: 60. Espera y vuelve a intentarlo.
401 bad_api_key: la clave es desconocida o está revocada.
400 bad_request: un mes, una fecha o un parámetro mal formados, o una fecha futura.
404, en las rutas day y chain: esa persona no es de tu empresa. En corrections, un id que no es tuyo devuelve una lista vacía.
500: algo ha fallado de nuestro lado, y la respuesta puede venir sin código. Vuelve a intentarlo.
Los errores son { error, code }. Usa el código: el texto puede cambiar.
Una clave sigue leyendo aunque tu plan caduque. Deja de funcionar cuando se revoca, cuando se cierra el negocio o cuando quien la creó deja de ser el titular.

Qué se mantiene estable

Solo se garantizan los campos de la referencia. Las rutas devuelven otros campos; no te apoyes en ellos.
Un campo documentado no se elimina ni se cambia. Pueden aparecer otros nuevos, así que ignora los que no conozcas.

Pruébala sin cuenta

La prueba abre una empresa de demostración con personas ficticias y semanas de historial. La respuesta te da un token de titular que funciona en las mismas cinco rutas, en el servidor de prueba, durante 24 horas.

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

Una diferencia: el token de titular de la prueba es una sesión, no una clave de API, así que también ve datos de contacto y notas que una clave no ve.