API de misfichajes

API REST en JSON para consultar los datos de tu empresa desde otros sistemas (nóminas, ERP, paneles de BI…). Cada empresa genera y controla sus propias claves, con los permisos justos para cada integración.

Estado actual: la API pública es de solo lectura y cubre empleados y centros. Se irán añadiendo recursos y permisos; los que ya existan no cambiarán de forma incompatible dentro de la versión v1.

Introducción

Todas las peticiones se hacen por HTTPS, se autentican con una clave de API en la cabecera Authorization y devuelven JSON codificado en UTF-8. Las fechas usan formato ISO 8601 (2025-03-14, o 2025-03-14T09:30:00+01:00 si llevan hora).

URL base

Cada empresa tiene su propio subdominio, y es el que identifica a qué empresa se refiere la petición:

https://{empresa}.misfichajes.eu/api/v1

Por ejemplo, para la empresa acme: https://acme.misfichajes.eu/api/v1/employees. Una clave solo funciona en el subdominio de la empresa que la creó; en cualquier otro devuelve 401.

Autenticación

1. Crear una clave

Un administrador de la empresa entra en Integraciones (API) en el menú de administración y pulsa Nueva clave. Hay que indicar:

Nombre: para qué se usa («Nóminas», «Panel BI»…).
Permisos: qué puede hacer, ver Permisos. Marca solo los necesarios.
Caducidad opcional: fecha a partir de la cual deja de funcionar.
Direcciones IP permitidas opcional: IPs o rangos CIDR (203.0.113.7, 10.0.0.0/24) desde los que se puede usar.

La clave (empieza por mfk_) se muestra una sola vez, al crearla. Guárdala en un gestor de secretos: misfichajes solo conserva un resumen irreversible y no puede volver a mostrártela. Si se pierde, se revoca y se crea otra.

2. Enviarla en cada petición

curl https://acme.misfichajes.eu/api/v1/employees \
  -H "Authorization: Bearer mfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Una clave puede revocarse en cualquier momento desde la misma pantalla y deja de funcionar al instante. El panel muestra cuándo y desde qué IP se usó por última vez.

Nunca pongas la clave en una aplicación que se ejecute en el navegador o en el móvil del usuario, ni en repositorios de código. Debe usarse solo desde un servidor tuyo.

Permisos (scopes)

Cada clave lleva una lista de permisos. Hay uno por recurso y nivel (read, y más adelante write y delete donde proceda). Si llamas a un recurso para el que la clave no tiene permiso, recibes 403 forbidden.

Permiso	Permite
`employees:read`	Ver empleados: `GET /employees`, `GET /employees/{id}`
`centers:read`	Ver centros: `GET /centers`

Hay un perfil predefinido, Solo lectura, que marca todos los permisos de lectura disponibles.

Por diseño, la API no expone usuarios y roles, facturación, ajustes de la empresa ni el registro de auditoría.

Respuestas y paginación

Un recurso individual se devuelve dentro de data:

{ "data": { "id": 12, "full_name": "Ana García", … } }

Los listados largos llevan además meta y se paginan con page (desde 1) y per_page (por defecto 50, máximo 200):

{
  "data": [ … ],
  "meta": { "page": 1, "per_page": 50, "total": 137 }
}

Hay más páginas mientras page × per_page < total.

Errores

Los errores usan el código HTTP correspondiente y siempre el mismo cuerpo JSON:

{ "error": { "code": "not_found", "message": "Empleado no encontrado." } }

Si el error es de validación, puede incluir además details con información adicional. El message está pensado para personas (en español); para programar lógica usa code.

HTTP	`code`	Cuándo
401	`unauthorized`	Falta la clave, no es válida, está caducada o revocada, se usa desde una IP no permitida o pertenece a otra empresa. Incluye `WWW-Authenticate: Bearer`.
403	`forbidden`	La clave es válida pero no tiene el permiso necesario.
403	`module_not_available`	El recurso pertenece a un módulo que la empresa no tiene contratado.
404	`not_found`	El recurso no existe (o no es de tu empresa).
422	`invalid_request`	Parámetros incorrectos.
5xx	`server_error`	Error nuestro. Reintenta con espera creciente; si persiste, avísanos.

Versiones

La versión va en la URL (/api/v1). Dentro de una versión consideramos compatibles, y por tanto pueden aparecer sin aviso: nuevos recursos, nuevos campos en las respuestas y nuevos permisos. Tu integración debe ignorar los campos que no conozca. Un cambio incompatible solo llegaría en una versión nueva (v2), con un plazo de convivencia anunciado.

Empleados

Permiso: employees:read

Listar empleados

GET/employees

Parámetro	Tipo	Descripción
`active`	booleano	`true` solo activos, `false` solo dados de baja. Sin indicar, todos.
`page`	entero	Página, desde 1.
`per_page`	entero	Resultados por página (1–200, por defecto 50).

curl "https://acme.misfichajes.eu/api/v1/employees?active=true&per_page=100" \
  -H "Authorization: Bearer $MISFICHAJES_KEY"

{
  "data": [
    {
      "id": 12,
      "employee_number": "E-0012",
      "first_name": "Ana",
      "last_name": "García",
      "full_name": "Ana García",
      "email": "ana@acme.com",
      "active": true,
      "hire_date": "2022-09-01",
      "center_id": 3,
      "department": "Administración",
      "manager_id": 5
    }
  ],
  "meta": { "page": 1, "per_page": 100, "total": 1 }
}

Obtener un empleado

GET/employees/{id}

Devuelve { "data": { … } } con los mismos campos. 404 si no existe o es de otra empresa.

Campos del empleado

Campo	Tipo	Descripción
`id`	entero	Identificador interno estable.
`employee_number`	texto \| null	Número de empleado.
`first_name`, `last_name`, `full_name`	texto	Nombre, apellidos y nombre completo.
`email`	texto \| null	Correo de acceso.
`active`	booleano	`false` si está dado de baja.
`hire_date`	fecha \| null	Fecha de alta (`AAAA-MM-DD`).
`center_id`	entero \| null	Centro de trabajo, ver Centros.
`department`	texto \| null	Nombre del departamento.
`manager_id`	entero \| null	`id` de su responsable.

Centros

Permiso: centers:read

Listar centros

GET/centers

Devuelve todos los centros de la empresa ordenados por nombre, sin paginar.

curl https://acme.misfichajes.eu/api/v1/centers \
  -H "Authorization: Bearer $MISFICHAJES_KEY"

{
  "data": [
    {
      "id": 3,
      "name": "Oficina Vigo",
      "address": "Rúa do Príncipe 1, Vigo",
      "timezone": "Europe/Madrid",
      "geofence": { "latitude": 42.2406, "longitude": -8.7207, "radius_m": 150 }
    }
  ]
}

Campo	Tipo	Descripción
`id`	entero	Identificador del centro.
`name`, `address`	texto \| null	Nombre y dirección.
`timezone`	texto	Zona horaria IANA.
`geofence`	objeto \| null	Zona de fichaje (centro y radio en metros), o `null` si el centro no tiene geovalla.

Buenas prácticas

Una clave por integración, con el mínimo de permisos. Así puedes revocar una sin tocar las demás.
Limita por IP y pon caducidad siempre que puedas, y renueva las claves de forma periódica.
Guarda la clave en variables de entorno o un gestor de secretos, nunca en el código.
Si sospechas que se ha filtrado, revócala y crea otra.
Cachea lo que cambie poco (centros, empleados) en lugar de consultarlo en cada operación, y pagina con per_page razonable.
Trata los datos de empleados como datos personales (RGPD): úsalos solo para la finalidad de la integración.

App móvil

La API contiene además rutas bajo /api/v1/auth y /api/v1/me que usa la aplicación móvil de misfichajes con la sesión de cada empleado. No forman parte de la API pública: no se pueden usar con claves de API (devuelven 403), no están documentadas aquí y pueden cambiar con cada versión de la app.

¿Necesitas un recurso o un permiso que no existe todavía? Pídelo desde el soporte de tu empresa en misfichajes.