Acceso a la API
mTime ofrece una API REST para desarrolladores que quieran integrarse con el sistema o automatizarlo. Esta página es una orientación general: la especificación OpenAPI es la referencia de autoridad para cada endpoint, esquema de petición y respuesta y permiso necesario. El detalle de cada endpoint no se repite aquí a propósito.
URL base
| Entorno | URL base |
|---|---|
| Producción | https://mtime.app/api |
| Staging | https://staging-mtime.app/api |
Cada entorno tiene sus propios datos y sus propias claves: una clave emitida en uno nunca
funciona en el otro. GET /ping responde sin
credenciales: es la comprobación básica de conectividad.
Autenticación
La API se autentica con claves de API que pertenecen a un usuario de servicio.
En , crea un usuario de servicio y dale una clave de API. Copia la clave en ese mismo momento: solo se muestra una vez.
Envía la clave en cada petición como token de portador (bearer):
Authorization: Bearer mtime_ak_...
Da al usuario de servicio el rol que cubre los datos que usa tu integración: los mismos roles que se describen en usuarios y permisos. Concede el de menos privilegios que haga el trabajo: cada endpoint está protegido por un permiso, y un 403 significa precisamente que falta uno.
El rol Desarrollador no es uno de ellos. Controla si la referencia de la API aparece en el menú de la aplicación para una persona que inicia sesión, y no da acceso a ningún dato, así que no sirve de nada para un usuario de servicio.
Un usuario de servicio no está vinculado a un empleado, así que los permisos con alcance Gestionados o Propio no le conceden nada en los endpoints que se refieren a un solo empleado (/employees/{employee_id}/…): esas peticiones se rechazan. A una integración que trabaja en nombre de los empleados, dale el alcance Todos para los recursos que usa.
Para comprobar una clave, llama a GET /api/version: acepta cualquier credencial válida y no requiere ningún permiso, así que responde 200 para una clave que funciona y 401 para una incorrecta, sin que intervenga ningún rol.
Especificación OpenAPI
El contrato completo se publica como OpenAPI 3.1:
GET /api/openapi.yamlGET /api/openapi.json/api/docslo muestra en el navegador: producción, staging
En la aplicación, la referencia está en , y esa entrada necesita el rol Desarrollador. Los Propietarios ya lo tienen —el rol de Propietario incluye el de Desarrollador— y ningún otro rol muestra la entrada. Asigna el rol Desarrollador en a quien construya la integración: abre la referencia y nada más, así que es seguro concederlo.
Describe exactamente los endpoints a los que puede acceder una clave de API. Un endpoint que no aparece no está disponible para las integraciones, y llamarlo devuelve 404 en lugar de una explicación; así que considera la especificación como la lista de lo que existe.
Genera a partir de ella un cliente tipado en lugar de escribir a mano los tipos de las peticiones. Cada operación declara además el permiso que necesita (x-required-permission), para que sepas de antemano qué rol necesita tu usuario de servicio.
Áreas de la API
Las operaciones de la especificación se agrupan por etiqueta (tag); esa agrupación es la de referencia. Estas son las áreas que cubre la API actualmente, cada una con un enlace a la referencia:
| Área | Prefijo de ruta | Qué cubre |
|---|---|---|
| Organization | /employees, /org-units | Empleados y la jerarquía de unidades organizativas: lectura, creación y actualización |
| Settings | /settings/… | Actividades, dimensiones y cuentas de tiempo (lectura, creación, actualización) y condiciones laborales (lectura) |
| Timesheet | /employees/{employee_id}/timesheet, /timesheet/statements | La hoja de horas de un empleado y los resúmenes en los que se cierra un periodo |
| Timebank | /employees/{employee_id}/timebank/balances | Saldos actuales por cuenta |
| Projects | /projects | Proyectos: lectura, creación y actualización |
| Reports | /reports/… | Horas registradas, movimientos de cuentas, presencia, ausencias, bajas por enfermedad y cumplimiento de jornada |
| Admin | /admin/imports, /admin/exports, /admin/jobs | Tareas de importación y exportación de datos del espacio de trabajo, y lanzar una tarea por lotes solo de prueba en un espacio de trabajo de prueba y consultar su ejecución |
| Misc | /ping, /version | Comprobación de disponibilidad y versión de la API |
Con una clave de API, las importaciones solo se permiten en un espacio de trabajo marcado como de prueba, sea cual sea el modo o el alcance. Solo se pueden lanzar las tareas por lotes de prueba, como Seed timesheet pattern. Importar y exportar son permisos de propietario y un usuario de servicio no puede ser propietario, así que dale un rol personalizado con los permisos de importación y exportación además de su otro rol.
Todo lo demás que usa la propia aplicación —el resto de la administración del espacio de trabajo, usuarios y claves de API, aprobaciones, quioscos, solicitudes de ausencia, eventos y webhooks— no forma parte de la API actualmente. Esos endpoints no aparecen en la especificación, y una clave que llame a uno recibe 404.
Permisos
Cada endpoint está protegido por un permiso (por ejemplo, settings:create:*), que se resuelve a partir del rol del usuario de servicio. Si una llamada devuelve 403, compara el permiso que exige la operación en la especificación con el rol del usuario de servicio.
El modelo de dominio
Unos pocos conceptos sostienen la mayor parte de la API:
- Las condiciones laborales (el «convenio») contienen los ajustes contractuales de un contrato: la jornada teórica, la cuenta flex, la actividad de pago por horas, el motivo predeterminado y el modo de aprobación de la hoja de horas. Los calendarios de festivos, las políticas (de ausencias, de complementos, de jornada y de liquidación) y los motivos no se asocian a unas condiciones: cada uno declara una disponibilidad (
availability_scope) que decide a qué contratos se aplica, por país de trabajo, unidad organizativa y condiciones laborales. - Las actividades son las categorías en las que se registra el tiempo. Cada una tiene un tipo —
work,timeoff,non-workoallowance— y pueden anidarse (una hija debe tener el mismo tipo que su madre). Una actividad puede exigir un proyecto o dimensiones personalizadas. - Los proyectos son agrupaciones de trabajo o facturación en las que se pueden registrar horas, y pueden requerir la aprobación de un responsable.
- Las dimensiones son etiquetas personalizadas (por ejemplo, un vehículo o un equipo) con un conjunto definido de valores permitidos. Las actividades pueden exigirlas, lo que valida lo que pueden elegir los usuarios.
- Las cuentas de tiempo contienen saldos: ausencias medidas en días o flex medida en horas.
Dos capas de tiempo
El tiempo se registra en dos capas independientes:
- Presencia: los fichajes de entrada y salida. Un intervalo de presencia lleva un motivo (y, opcionalmente, una nota y una actividad). El motor de reglas evalúa los intervalos de presencia.
- Registros: las entradas de la cuadrícula que asignan tiempo a una actividad, un proyecto y valores de dimensión.
De forma predeterminada estas capas son independientes; una restricción de jornada puede exigir que cuadren. Como regla general: el cuándo y el porqué están en la presencia; el qué y el dónde, en los registros.
El motor de reglas
Los pluses, las horas extra, los complementos de guardia y la flex se calculan mediante políticas formadas por plugins:
- Las políticas de complementos convierten el tiempo trabajado en una cantidad pagable, ya sea mediante un contador semanal que tiene en cuenta la jornada (horas complementarias, horas extra, horas en negativo, horas trabajadas) o mediante reglas ordenadas (filtros que seleccionan intervalos + una calculadora que los convierte en una cantidad), opcionalmente activadas por motivos concretos, y se registran en una actividad de complemento de destino.
- Las políticas de jornada contienen las restricciones de jornada y los registros automáticos (como el descuento de la pausa para comer). La cuenta flex en sí se define en las condiciones laborales.
- Las políticas de liquidación son el proceso de cierre de periodo que abona los contadores en una cuenta de tiempo y decide entre pago y flex.
Los filtros, calculadoras, contadores, devengos, caducidades, reglas de uso, generadores de festivos y los distintos pasos de jornada y de liquidación son todos plugins. Consulta los plugins disponibles y el esquema de configuración de cada uno en:
GET /api/descriptor/plugins/GET /api/descriptor/plugins/{registry}/{plugin_id}/schema
Estos endpoints descriptores responden sin clave, pero no se describen en la especificación: las políticas en sí se configuran en la aplicación.
Orden de configuración
Actualmente solo una parte de la configuración se puede escribir a través de la API: actividades, dimensiones, cuentas de tiempo, empleados, unidades organizativas y proyectos; los calendarios, motivos, políticas y condiciones laborales se configuran en la aplicación. Como los elementos se referencian entre sí, créalos empezando por la base: dimensiones y cuentas de tiempo → actividades → unidades organizativas → empleados → proyectos.
Versiones con fecha de efecto
Los elementos de configuración y los registros de empleados están versionados. Un cambio entra en vigor a partir de su fecha de efecto, y un elemento recién creado no está en vigor antes de su fecha de creación. Para cambiar un periodo pasado, añade una versión retroactiva en lugar de editar la actual.
Cómo se generan los resultados
Los totales trabajados, los complementos, la flex y el pago no se calculan en directo en la hoja de horas diaria: se materializan cuando se genera un resumen de la hoja de horas y después se envía y se aprueba (liquidación). La generación de resúmenes se ejecuta como una tarea por lotes programada; la cantidad que va a pago o a flex se elige en el envío. Diseña tus integraciones para que lean las cifras liquidadas de los resúmenes y de los informes de movimientos de cuentas.
Listados y alcance
Las colecciones están paginadas y se pueden filtrar (consulta cada operación en la especificación). Algunas listas centradas en el usuario devuelven de forma predeterminada los datos de quien llama; por ejemplo, los resúmenes de hojas de horas usan por defecto el alcance de quien llama. Pide explícitamente el alcance de todo el espacio de trabajo cuando tu integración lo necesite.
El limit de una lista está entre 1 y 1000; omítelo para obtener el valor predeterminado. Un valor fuera de ese intervalo se rechaza con 422. /timesheet/statements devuelve como máximo 500 resúmenes: cuando hay más coincidencias, la respuesta lleva el encabezado MTime-Truncated: true, así que acota el periodo o el filtro.
Las listas de referencia (cuentas, actividades, dimensiones, condiciones laborales, unidades organizativas y proyectos) llevan un ETag débil. Devuélvelo en If-None-Match y, si la lista no ha cambiado, la respuesta es 304 Not Modified sin cuerpo, lo que evita volver a descargarla en cada sincronización.
Límites de peticiones
Cada clave de API puede hacer 300 peticiones por minuto, y todas las claves de un mismo espacio de trabajo juntas 600, así que crear más claves no aumenta el límite. Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Una petición por encima del límite recibe 429 Too Many Requests con un encabezado Retry-After que indica los segundos que hay que esperar. Espera y vuelve a intentarlo pasado ese tiempo.