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

L’API se trouve sous le préfixe /api de l’hôte de votre espace de travail — par exemple https://votre-espace.example/api. La racine de l’API (GET /api/) renvoie un identifiant simple, utilisable comme contrôle d’état.

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_...

Le point de terminaison /me représente un utilisateur connecté de façon interactive et n’accepte pas les clés d’utilisateur de service. Pour vérifier qu’une clé fonctionne, appelez un point de terminaison de données tel que GET /api/employees.

Spécification OpenAPI

Le contrat complet est publié au format OpenAPI 3.1 :

• GET /api/openapi.yaml
• GET /api/openapi.json

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 autorité. Les principaux domaines et leurs préfixes de chemin :

Les domaines Settings et Admin sont ceux où se déroule l’essentiel du travail de configuration et d’automatisation ; Me et Auth sont orientés vers les sessions interactives plutôt que vers les clés d’utilisateur de service.

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. Certaines actions administratives — comme les exports complets de données — requièrent un rôle plus élevé que la configuration ordinaire. 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 ») relient tout ce qui s’applique à un employé : la norme de temps de travail, le calendrier de jours fériés, les politiques de congés, les politiques de primes, une politique de temps de travail, une politique de règlement, les motifs disponibles et le mode d’approbation des relevés. Affecter un employé à une condition lui attribue l’ensemble.
• 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

Lisez toujours le descriptor avant de configurer une politique — il vous indique les clés de configuration exactes et les types de valeurs.

Ordre de configuration

Comme les objets se référencent mutuellement, créez-les en commençant par les fondations : calendriers de jours fériés, dimensions, comptes de banque de temps et motifs → activités (activités de prime cibles avant les politiques de primes qui les référencent) → politiques de primes, de temps de travail et de règlement → conditions d’emploi → 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.