API de FichMe para desarrolladores

Qué es

La API de FichMe da acceso, con una clave, a los datos de tu empresa: plantilla, centros de trabajo, fichajes, jornadas calculadas, ausencias y sus saldos, balance de horas, turnos y festivos, y las mismas exportaciones que genera el panel.

• Jornadas ya calculadas

  Una fila por empleado y día, con las pulsaciones emparejadas en tramos y las horas trabajadas, previstas y el balance calculados con el mismo motor que el panel. No tienes que reimplementar el emparejamiento de entradas, salidas y pausas.

• Escritura con garantías

  Fichar en tiempo real, pedir correcciones, dar de alta empleados y gestionar ausencias. Los fichajes entran en la misma cadena de integridad que los demás canales y el pasado solo se corrige con solicitudes aprobadas.

• Convenciones sencillas

  JSON en camelCase, fechas de jornada YYYY-MM-DD en la zona horaria de la empresa, instantes en ISO 8601 UTC, paginación con page y limit (hasta 500) y errores con un código estable y un requestId.

• Versionada en la URL

  Todo cuelga de /v1. Añadir campos no rompe nada: ignora los que no conozcas. Un cambio incompatible irá en una versión nueva y la anterior se mantendrá 12 meses desde el anuncio.

Para quién

Cómo obtener una clave

Las claves las crea un administrador de la empresa desde el panel; no hace falta pedirlas a soporte. Si eres una gestoría o un proveedor, pídesela a tu cliente.

1. 1

   Entra en el panel de FichMe como administrador y ve a Ajustes → API.

2. 2

   Pulsa Crear clave de API: ponle nombre, elige los permisos (hay combinaciones preparadas para gestorías, BI, terminales, RR. HH. y Zapier o Make), la caducidad y, si quieres, las IPs desde las que se podrá usar.

3. 3

   La primera vez, acepta las Condiciones de uso de la API en nombre de la empresa.

4. 4

   Copia la clave: empieza por fm_live_ y solo se muestra una vez. Guárdala en un gestor de secretos.

La API está incluida en los planes Pro, Business y Enterprise. Una empresa en su periodo de prueba puede probarla antes de contratar. Ver planes y precios.

Guía rápida

La clave viaja en la cabecera x-api-key o, si tu herramienta lo prefiere, en Authorization: Bearer <clave>. La empresa sale de la propia clave: no hay que indicarla.

export FICHME_API_KEY="fm_live_…"

curl https://api.fichme.com/v1/me -H "x-api-key: $FICHME_API_KEY"

curl "https://api.fichme.com/v1/employees?page=1&limit=100" \
  -H "x-api-key: $FICHME_API_KEY"

curl "https://api.fichme.com/v1/work-sessions?from=2026-09-01&to=2026-09-30" \
  -H "x-api-key: $FICHME_API_KEY"

curl -X POST https://api.fichme.com/v1/exports \
  -H "x-api-key: $FICHME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"clocking","format":"xlsx","from":"2026-09-01","to":"2026-09-30"}'

{
  "error": {
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope clock:write.",
    "param": null,
    "requestId": "req_01J9N6Q0K3W2M8Z7X5V4T3R2P1"
  }
}

Seguridad

• Permisos por clave. Cada clave lleva solo los permisos que elija la empresa. Los datos sensibles (el DNI, el número de la Seguridad Social y los datos de salud, como las bajas médicas) exigen un permiso propio que nunca viene marcado por defecto. La geolocalización de los fichajes no sale en esta versión, y los PIN de terminal y las credenciales no salen nunca por la API.
• Caducidad. 30, 90 o 365 días (365 por defecto), con aviso al responsable 30 y 7 días antes. En Enterprise se pueden emitir claves sin caducidad.
• IPs permitidas. Cada clave se puede limitar a una lista de IPs o rangos CIDR. Si tu servidor sale a internet por un proxy o con IP variable, compruébalo antes de restringir.
• Nunca en el navegador. La clave da acceso a los datos de toda la empresa: úsala solo desde un servidor, nunca en el código de una web o de una app que se ejecute en el dispositivo de alguien.
• Rotación y revocación. Si una clave se filtra, rótala desde el panel: la anterior se revoca al momento, o tras un solape de hasta 7 días si lo eliges. Cuando termine la relación con quien la usa, revócala.
• Trazabilidad. Guardamos el uso diario de cada clave por ruta, y cada escritura queda en el registro de auditoría con la clave que la hizo.

Límites

• 120 peticiones por minuto por clave. Al superarlo respondemos 429 con la cabecera Retry-After; cada respuesta trae además RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset.
• Cuota diaria por clave según el plan (ver la tabla de arriba). Se renueva a las 00:00 UTC, que en la España peninsular son las 01:00 en invierno y las 02:00 en verano.
• 1 petición pesada a la vez por clave: jornadas calculadas, balance de horas, saldos de ausencias y exportaciones. La siguiente simultánea recibe un 429 al instante.
• Consultas acotadas. Hasta 500 resultados por página y rangos de fechas limitados por endpoint (93 días en fichajes y jornadas, 366 en balance y ausencias). Para más, usa las exportaciones.
• Ante un 429 o un 503, reintenta respetando Retry-After y con espera creciente.

Webhooks

En los planes Business y Enterprise, FichMe avisa a tu sistema en cuanto algo cambia: fichajes nuevos o corregidos, solicitudes de corrección, ausencias (creadas, aprobadas, rechazadas o canceladas) y altas, cambios y bajas de empleados. Se configuran en Ajustes → API o por la propia API, con el permiso webhooks:manage.

• Cada envío es un POST JSON a una URL HTTPS pública, firmado con la cabecera FichMe-Signature: t=<unix>,v1=<hex>, donde v1 = HMAC-SHA256(secreto, "<t>.<cuerpo>") con el secreto whsec_… del endpoint.
• Comprueba la firma sobre el cuerpo en crudo, compárala en tiempo constante y descarta envíos con más de 5 minutos de antigüedad.
• Responde con un 2xx en menos de 10 segundos. Si no, reintentamos a 1 min, 5 min, 30 min, 2 h y 12 h; tras 72 horas sin una sola respuesta correcta desactivamos el endpoint y avisamos a los administradores.
• Un mismo evento puede llegar más de una vez: usa la cabecera FichMe-Event-Id para descartar duplicados.

Documentación y soporte

¿Algo no cuadra? Escríbenos a api@fichme.com con el requestId del error. Atendemos en horario laboral, de lunes a viernes; no hay servicio de guardia. El uso de la API se rige por las Condiciones de uso de la API.