Accesso API

mTime espone un’API REST per gli sviluppatori che desiderano integrare o automatizzare il sistema. Questa pagina offre un orientamento di alto livello — le specifiche OpenAPI rappresentano il riferimento autorevole per ogni endpoint, schema di richiesta/risposta e autorizzazione richiesta. I dettagli a livello di endpoint non vengono ripetuti qui intenzionalmente.

URL di base

Ogni ambiente ha dati e chiavi propri: una chiave emessa in uno non funziona mai nell’altro. GET /ping risponde senza credenziali: è il semplice controllo di connettività.

Autenticazione

L’API si autentica tramite chiavi API appartenenti a un utente di servizio.

1. In Amministrazione › Utenti, creare un utente di servizio e assegnargli una chiave API. Copiare immediatamente la chiave — viene visualizzata una sola volta.

2. Inviare la chiave in ogni richiesta come bearer token:

   Authorization: Bearer mtime_ak_...

Per verificare una chiave, chiamare GET /api/version: accetta qualsiasi credenziale valida e non richiede autorizzazioni, quindi risponde 200 per una chiave funzionante e 401 per una non valida, senza che il ruolo interferisca.

Specifiche OpenAPI

Il contratto completo è pubblicato come OpenAPI 3.1:

• GET /api/openapi.yaml
• GET /api/openapi.json
• /api/docs lo visualizza nel browser — produzione, staging

Nell’applicazione il riferimento si trova in Risorse › Riferimento API e quella voce di menu richiede il ruolo Sviluppatore. I Proprietari lo hanno già — il ruolo Proprietario include Sviluppatore — e nessun altro ruolo mostra la voce. Assegnare Sviluppatore in Amministrazione › Utenti a chi realizza l’integrazione: apre il riferimento e nient’altro, quindi può essere concesso senza rischi.

Descrive esattamente gli endpoint raggiungibili da una chiave API. Un endpoint assente non è disponibile per le integrazioni, e chiamarlo restituisce 404 senza spiegazioni: considerare quindi le specifiche come l’elenco di ciò che esiste.

Si raccomanda di generare un client tipizzato a partire da esso, anziché scrivere manualmente i tipi di richiesta. Ogni operazione dichiara anche l’autorizzazione richiesta (x-required-permission), in modo da poter verificare in anticipo il ruolo necessario per l’utente di servizio.

Aree API

Le operazioni nelle specifiche sono raggruppate per tag; tale raggruppamento è autorevole. Queste sono le aree coperte oggi dall’API — ciascuna rimanda al riferimento:

Con una chiave API, le importazioni sono consentite solo in un’area di lavoro contrassegnata come area di lavoro di test, qualunque siano la modalità e l’ambito. Possono essere avviati solo i batch job riservati ai test, come Genera schema di foglio ore. Importazione ed esportazione sono autorizzazioni del proprietario e un utente di servizio non può essere proprietario: assegnagli quindi un ruolo personalizzato con le autorizzazioni di importazione ed esportazione, in aggiunta al suo altro ruolo.

Tutto il resto di ciò che usa l’applicazione — il resto dell’amministrazione dell’area di lavoro, utenti e chiavi API, approvazioni, chioschi, richieste di assenza, eventi e webhook — oggi non fa parte dell’API. Quegli endpoint sono assenti dalle specifiche e una chiave che ne chiama uno riceve 404.

Autorizzazioni

Ogni endpoint è protetto da un’autorizzazione (ad esempio settings:create:*), determinata dal ruolo dell’utente di servizio. Se una chiamata restituisce 403, verificare l’autorizzazione richiesta dall’operazione nelle specifiche rispetto al ruolo dell’utente di servizio.

Il modello di dominio

Alcuni concetti sono alla base della maggior parte dell’API:

• Le condizioni di impiego (l’“accordo”) contengono la norma orario di lavoro, il conto flessibilità e la modalità di approvazione del foglio presenze di un dipendente. Calendari festività, policy assenze, indennità, orario di lavoro e di liquidazione e motivi non sono elencati nelle condizioni di impiego: ciascuno dichiara un availability_scope (paesi di lavoro, unità organizzative, condizioni di impiego) e si applica a ogni impiego che vi corrisponde.
• Le attività sono le categorie rispetto alle quali vengono registrate le ore. Ciascuna ha un tipo — work, timeoff, non-work o allowance — e può essere annidata (un’attività figlia deve condividere il tipo del genitore). Un’attività può richiedere un progetto e/o dimensioni personalizzate.
• I progetti sono contenitori di lavoro/fatturazione su cui possono essere registrate le ore e possono richiedere l’approvazione di un responsabile.
• Le dimensioni sono tag personalizzati (ad esempio un veicolo o un’attrezzatura) con un insieme definito di valori consentiti. Le attività possono richiederle, il che convalida ciò che gli utenti possono selezionare.
• I conti ore conservano i saldi — le assenze misurate in giorni o la flessibilità misurata in ore.

Due livelli di tempo

Il tempo viene registrato in due livelli indipendenti:

• Presenza — registrazioni di ingresso/uscita. Un intervallo di presenza comprende un motivo (e facoltativamente una nota e un’attività). Il motore regole valuta gli intervalli di presenza.
• Voci — registrazioni nella griglia che attribuiscono il tempo a un’attività, un progetto e valori di dimensione.

Per impostazione predefinita questi livelli sono indipendenti; un vincolo orario può richiedere che si riconcilino. Come regola generale: quando e perché appartengono alla presenza; cosa e dove appartengono alle voci.

Il motore regole

Premi, straordinari, indennità di reperibilità e flessibilità vengono calcolati da policy costruite con plugin:

• Le policy indennità trasformano il tempo lavorato in un importo pagabile — tramite un contatore settimanale basato sulla norma (straordinari, delta flex/norma, …) oppure tramite regole ordinate (filtri che selezionano gli intervalli + un calcolatore che li scala), attivabili facoltativamente da motivi specifici e registrate su un’attività indennità di destinazione.
• Le policy orario di lavoro abilitano il monitoraggio della flessibilità (collegando un conto flessibilità), le registrazioni automatiche (come la detrazione del pranzo) e i vincoli sull’orario di lavoro.
• Le policy di liquidazione costituiscono il processo di chiusura del periodo che accumula i contatori in un conto ore e stabilisce il pagamento rispetto alla flessibilità.

Filtri, calcolatori, contatori, maturazioni, scadenze, regole di utilizzo, generatori di festività e le varie fasi orario di lavoro e liquidazione sono tutti plugin. Per scoprire i plugin disponibili e lo schema di configurazione di ciascuno:

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

Questi endpoint descriptor rispondono senza chiave, ma non sono descritti nelle specifiche: le policy si configurano nell’applicazione.

Ordine di configurazione

Oggi solo una parte della configurazione è scrivibile tramite API — attività, dimensioni, conti ore, dipendenti, unità organizzative e progetti; calendari, motivi, policy e condizioni di impiego si impostano nell’applicazione. Poiché le entità si riferiscono le une alle altre, è necessario crearle a partire dalle fondamenta: dimensioni e conti ore → attività → unità organizzative → dipendenti → progetti.

Versionamento con data di validità

Le entità di configurazione e i record dei dipendenti sono versionati. Una modifica ha effetto a partire dalla sua data di validità e un’entità appena creata non è valida prima della data di creazione. Per modificare un periodo passato, aggiungere una versione retroattiva anziché modificare quella corrente.

Come vengono prodotti i risultati

I totali lavorati, le indennità, la flessibilità e i pagamenti non vengono calcolati in tempo reale sul foglio presenze giornaliero — si materializzano quando viene generato un rendiconto del foglio presenze e successivamente inviato e approvato (liquidazione). La generazione del rendiconto viene eseguita come job batch pianificato; l’importo pagamento rispetto a flessibilità viene scelto al momento dell’invio. Le integrazioni devono essere progettate per leggere i valori liquidati dai rendiconti e dai report dei movimenti del conto.

Elenchi e ambito

Le collezioni sono paginate e filtrabili (consultare ogni operazione nelle specifiche). Alcuni elenchi orientati all’utente predefiniscono i dati del chiamante — ad esempio i rendiconti del foglio presenze hanno come scope predefinito quello del chiamante; richiedere esplicitamente lo scope dell’intera area di lavoro quando l’integrazione ne ha bisogno.

Il parametro limit di un elenco è compreso tra 1 e 1000; ometterlo per ottenere il valore predefinito. Un valore fuori da questo intervallo viene rifiutato con 422. /timesheet/statements restituisce al massimo 500 prospetti: se ne corrispondono di più, la risposta contiene l’intestazione MTime-Truncated: true, quindi restringere il periodo o il filtro.

Gli elenchi di riferimento (conti, attività, dimensioni, condizioni di impiego, unità organizzative e progetti) hanno un ETag debole. Rimandarlo in If-None-Match: un elenco invariato risponde 304 Not Modified senza corpo, evitando di riscaricarlo a ogni sincronizzazione.

Limiti di frequenza

Ogni chiave API può effettuare 300 richieste al minuto e tutte le chiavi di un workspace insieme 600, quindi creare altre chiavi non aumenta il limite. Ogni risposta contiene RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Una richiesta oltre il limite riceve 429 Too Many Requests con l’intestazione Retry-After, che indica i secondi da attendere. Attendere e riprovare dopo quel tempo.