Accès API

mTime expose une API REST destinée aux développeurs qui souhaitent intégrer ou automatiser le système. Cette page est une présentation de haut niveau — la spécification OpenAPI fait autorité pour chaque point de terminaison, chaque schéma de requête/réponse et les permissions requises. Le détail au niveau des points de terminaison n’est volontairement pas répété ici.

URL de base

Chaque environnement a ses propres données et ses propres clés — une clé émise dans l’un ne fonctionne jamais dans l’autre. GET /ping répond sans authentification : c’est le simple contrôle de connectivité.

Authentification

L’API s’authentifie avec des clés API appartenant à un utilisateur de service.

1. Dans Admin › Utilisateurs, créez un utilisateur de service et donnez-lui une clé API. Copiez la clé immédiatement — elle n’est affichée qu’une seule fois.

2. Envoyez la clé à chaque requête sous forme de jeton bearer :

   Authorization: Bearer mtime_ak_...

Pour vérifier une clé, appelez GET /api/version : il accepte toute authentification valide et ne requiert aucune permission, donc il renvoie 200 pour une clé qui fonctionne et 401 pour une clé invalide, sans que le rôle n’intervienne.

Spécification OpenAPI

Le contrat complet est publié au format OpenAPI 3.1 :

• GET /api/openapi.yaml
• GET /api/openapi.json
• /api/docs l’affiche dans le navigateur — production, staging

Dans l’application, la référence se trouve sous Ressources › Référence API, et cette entrée requiert le rôle Développeur. Les Propriétaires l’ont déjà — le rôle Propriétaire inclut Développeur — et aucun autre rôle n’affiche l’entrée. Attribuez Développeur dans Admin › Utilisateurs à la personne qui construit l’intégration : il ouvre la référence et rien d’autre, il peut donc être accordé sans risque.

Elle décrit exactement les endpoints qu’une clé API peut atteindre. Un endpoint absent n’est pas accessible aux intégrations, et l’appeler renvoie 404 sans explication — considérez donc la spécification comme la liste de ce qui existe.

Générez un client typé à partir de celle-ci plutôt que d’écrire les types de requête à la main. Chaque opération déclare également la permission qu’elle requiert (x-required-permission), ce qui vous permet de voir d’emblée le rôle nécessaire pour votre utilisateur de service.

Domaines de l’API

Les opérations de la spécification sont regroupées par tag ; ce regroupement fait foi. Voici les domaines couverts par l’API aujourd’hui — chacun renvoie vers la référence :

Avec une clé API, les imports ne sont autorisés que dans un espace de travail marqué comme espace de test, quels que soient le mode et le périmètre. Seules les tâches par lots réservées aux tests — comme Générer un motif de feuille de temps — peuvent être déclenchées. L’import et l’export sont des permissions du propriétaire, et un utilisateur de service ne peut pas être propriétaire : donnez-lui donc un rôle personnalisé avec les permissions d’import et d’export, en plus de son autre rôle.

Tout le reste de ce qu’utilise l’application — le reste de l’administration de l’espace de travail, utilisateurs et clés API, approbations, bornes, demandes d’absence, événements et webhooks — ne fait pas partie de l’API aujourd’hui. Ces endpoints sont absents de la spécification, et une clé qui en appelle un reçoit 404.

Permissions

Chaque point de terminaison est protégé par une permission (par exemple settings:create:*), résolue à partir du rôle de l’utilisateur de service. Si un appel renvoie 403, comparez la permission requise de l’opération dans la spécification avec le rôle de l’utilisateur de service.

Le modèle de domaine

Quelques concepts sous-tendent la majeure partie de l’API :

• Les conditions d’emploi (la « convention ») portent la norme de temps de travail d’un employé, son compte flex et le mode d’approbation de ses relevés. Les calendriers de jours fériés, les politiques d’absences, de primes, de temps de travail et de décompte ainsi que les motifs n’y sont pas listés : chacun déclare un availability_scope (pays de travail, unités organisationnelles, conditions d’emploi) et s’applique à tous les emplois qui y correspondent.
• Les activités sont les catégories sur lesquelles le temps est enregistré. Chacune a un type — work, timeoff, non-work ou allowance — et peut être imbriquée (un enfant doit partager le type de son parent). Une activité peut exiger un projet et/ou des dimensions personnalisées.
• Les projets sont des unités de travail/facturation sur lesquelles les enregistrements peuvent être imputés, et peuvent exiger l’approbation d’un manager.
• Les dimensions sont des étiquettes personnalisées (par exemple un véhicule ou un équipement) avec un ensemble défini de valeurs autorisées. Les activités peuvent les exiger, ce qui valide ce que les utilisateurs peuvent choisir.
• Les comptes de banque de temps contiennent des soldes — congés mesurés en jours, ou flex mesuré en heures.

Deux couches de temps

Le temps est enregistré sur deux couches indépendantes :

• Présence — enregistrements de pointage entrée/sortie. Un intervalle de présence porte un motif (et éventuellement une note et une activité). Le moteur de règles évalue les intervalles de présence.
• Saisies — enregistrements dans la grille qui répartissent le temps sur une activité, un projet et des valeurs de dimension.

Par défaut, ces couches sont indépendantes ; une contrainte de temps de travail peut exiger leur réconciliation. Règle générale : le quand et le pourquoi relèvent de la présence ; le quoi et le où relèvent des saisies.

Le moteur de règles

Les primes, les heures supplémentaires, les indemnités d’astreinte et le flex sont calculés par des politiques composées de plugins :

• Les politiques de primes transforment le temps travaillé en un montant payable — soit via un compteur hebdomadaire tenant compte de la norme (heures supplémentaires, flex/écart-norme, …), soit via des règles ordonnées (des filtres qui sélectionnent les intervalles + un calculateur qui les met à l’échelle), éventuellement déclenchées par des motifs spécifiques et enregistrées sur une activité de prime cible.
• Les politiques de temps de travail activent le suivi du flex (en liant un compte flex), les enregistrements automatiques (comme une déduction de pause déjeuner) et les contraintes de temps de travail.
• Les politiques de règlement constituent le pipeline de clôture de période qui crédite les compteurs sur un compte de banque de temps et arbitre entre paiement et flex.

Les filtres, calculateurs, compteurs, acquisitions, expirations, règles d’utilisation, générateurs de jours fériés et les diverses étapes de temps de travail et de règlement sont tous des plugins. Découvrez les plugins disponibles et le schéma de configuration de chacun ici :

• GET /api/descriptor/plugins/
• GET /api/descriptor/plugins/{registry}/{plugin_id}/schema

Ces points de terminaison descriptor répondent sans clé, mais ils ne sont pas décrits dans la spécification — les politiques elles-mêmes se configurent dans l’application.

Ordre de configuration

Seule une partie de la configuration est modifiable via l’API aujourd’hui — activités, dimensions, comptes de banque de temps, employés, unités organisationnelles et projets ; les calendriers, motifs, politiques et conditions d’emploi se configurent dans l’application. Comme les objets se référencent mutuellement, créez-les en commençant par les fondations : dimensions et comptes de banque de temps → activités → unités organisationnelles → employés → projets.

Versionnage avec date d’effet

Les objets de configuration et les fiches employé sont versionnés. Une modification prend effet à partir de sa date d’effet, et un objet nouvellement créé n’est pas en vigueur avant sa date de création. Pour modifier une période passée, ajoutez une version rétroactive plutôt que de modifier la version actuelle.

Comment les résultats sont produits

Les totaux travaillés, les primes, le flex et le paiement ne sont pas calculés en direct sur la feuille de temps quotidienne — ils se matérialisent lorsqu’un relevé est généré puis soumis et approuvé (règlement). La génération des relevés s’exécute comme une tâche par lots planifiée ; le montant paiement-contre-flex est choisi à la soumission. Construisez des intégrations qui lisent les chiffres réglés à partir des relevés et des rapports de mouvements de compte en conséquence.

Listes et portée

Les collections sont paginées et filtrables (voir chaque opération dans la spécification). Certaines listes centrées sur l’utilisateur sont par défaut limitées aux données de l’appelant — par exemple, les relevés sont par défaut limités à la portée de l’appelant ; demandez explicitement la portée de l’ensemble de l’espace de travail lorsque votre intégration en a besoin.

Le paramètre limit d’une liste est compris entre 1 et 1000 ; omettez-le pour obtenir la valeur par défaut. Une valeur hors de cet intervalle est refusée avec 422. /timesheet/statements renvoie au plus 500 relevés : si davantage correspondent, la réponse porte l’en-tête MTime-Truncated: true, alors réduisez la période ou le filtre.

Les listes de référence (comptes, activités, dimensions, conditions d’emploi, unités organisationnelles et projets) portent un ETag faible. Renvoyez-le dans If-None-Match : une liste inchangée répond 304 Not Modified sans corps, ce qui évite de la retélécharger à chaque synchronisation.

Limites de débit

Chaque clé API peut effectuer 300 requêtes par minute, et l’ensemble des clés d’un espace de travail 600, si bien que créer d’autres clés n’augmente pas la limite. Chaque réponse porte RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Une requête au-delà de la limite reçoit 429 Too Many Requests avec un en-tête Retry-After qui indique le nombre de secondes à attendre. Patientez, puis réessayez.