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

L’API si trova sotto il prefisso /api dell’host dell’area di lavoro — ad esempio https://your-workspace.example/api. La radice dell’API (GET /api/) restituisce un semplice identificatore utilizzabile come health check.

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

L’endpoint /me rappresenta un utente interattivo con sessione attiva e non accetta chiavi di utenti di servizio. Per verificare il funzionamento di una chiave, chiamare un endpoint dati come GET /api/employees.

Specifiche OpenAPI

Il contratto completo è pubblicato come OpenAPI 3.1:

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

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 è quello di riferimento. Le aree principali e i relativi prefissi di percorso:

Le aree Impostazioni e Amministrazione sono quelle in cui si svolge la maggior parte del lavoro di configurazione e automazione; Me e Auth sono orientati alle sessioni interattive piuttosto che alle chiavi degli utenti di servizio.

Autorizzazioni

Ogni endpoint è protetto da un’autorizzazione (ad esempio settings:create:*), determinata dal ruolo dell’utente di servizio. Alcune azioni amministrative — come le esportazioni complete dei dati — richiedono un ruolo superiore rispetto alla configurazione ordinaria. 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”) raggruppano tutto ciò che si applica a un dipendente: la norma orario di lavoro, il calendario festività, le policy assenze, le policy indennità, una policy orario di lavoro, una policy di liquidazione, i motivi disponibili e la modalità di approvazione del foglio presenze. Assegnare un dipendente a delle condizioni di impiego gli conferisce l’intero insieme.
• 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

È essenziale leggere il descriptor prima di configurare una policy — indica le chiavi di configurazione esatte e i tipi di valore.

Ordine di configurazione

Poiché le entità si riferiscono le une alle altre, è necessario crearle a partire dalle fondamenta: calendari festività, dimensioni, conti ore e motivi → attività (le attività target di indennità prima delle policy indennità che le referenziano) → policy indennità, orario di lavoro e liquidazione → condizioni di impiego → 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.