API-toegang

mTime biedt een REST API voor ontwikkelaars die het systeem willen integreren of automatiseren. Deze pagina biedt een globale oriëntatie — de OpenAPI-specificatie is de gezaghebbende referentie voor elk endpoint, elk aanvraag-/antwoordschema en de vereiste machtigingen. Gedetailleerde informatie per endpoint wordt hier niet herhaald.

Basis-URL

De API is beschikbaar via het prefix /api van uw werkruimtehost — bijvoorbeeld https://uw-werkruimte.voorbeeld/api. De API-root (GET /api/) retourneert een eenvoudige identificatie die u als statuscontrole kunt gebruiken.

Authenticatie

De API verifieert de identiteit via API-sleutels die toebehoren aan een servicegebruiker.

1. Maak via Beheer › Gebruikers een servicegebruiker aan en geef deze een API-sleutel. Kopieer de sleutel direct — deze wordt slechts eenmalig getoond.

2. Stuur de sleutel mee bij elk verzoek als bearer-token:

   Authorization: Bearer mtime_ak_...

Het endpoint /me vertegenwoordigt een interactief ingelogde gebruiker en accepteert geen servicegebruikerssleutels. Roep een data-endpoint aan, zoals GET /api/employees, om te controleren of een sleutel werkt.

OpenAPI-specificatie

Het volledige contract is gepubliceerd als OpenAPI 3.1:

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

Genereer een getypeerde client op basis hiervan in plaats van verzoektypes handmatig te schrijven. Elke operatie geeft ook de vereiste machtiging aan (x-required-permission), zodat u vooraf kunt zien welke rol uw servicegebruiker nodig heeft.

API-gebieden

De operaties in de specificatie zijn gegroepeerd per tag; die groepering is leidend. De belangrijkste gebieden en hun padprefixen:

De gebieden Instellingen en Beheer zijn waar de meeste configuratie- en automatiseringsactiviteiten plaatsvinden; Mijn gegevens en Authenticatie zijn gericht op interactieve sessies in plaats van servicegebruikerssleutels.

Machtigingen

Elk endpoint is beveiligd met een machtiging (bijvoorbeeld settings:create:*), afgeleid van de rol van de servicegebruiker. Sommige beheertaken — zoals volledige gegevensexports — vereisen een hogere rol dan gewone configuratie. Als een aanroep 403 retourneert, vergelijk dan de vereiste machtiging van de operatie in de specificatie met de rol van de servicegebruiker.

Het domeinmodel

Een aantal concepten vormt de basis van het grootste deel van de API:

• Arbeidsvoorwaarden (de “overeenkomst”) bundelen alles wat van toepassing is op een medewerker: de werktijdnorm, de feestdagenkalender, het verlofbeleid, het vergoedingenbeleid, een werktijdbeleid, een verrekeningsbeleid, beschikbare redenen en de goedkeuringsmodus voor de urenstaat. Door een medewerker aan arbeidsvoorwaarden te koppelen, ontvangt deze het volledige pakket.
• Activiteiten zijn de categorieën waarop tijd wordt geregistreerd. Elke activiteit heeft een type — work, timeoff, non-work of allowance — en kan worden genest (een onderliggende activiteit moet hetzelfde type hebben als de bovenliggende). Een activiteit kan een project en/of aangepaste dimensies vereisen.
• Projecten zijn werk-/facturatiegroepen waaraan registraties kunnen worden geboekt, en kunnen goedkeuring van een manager vereisen.
• Dimensies zijn aangepaste tags (bijvoorbeeld een voertuig of stuk gereedschap) met een vastgestelde reeks toegestane waarden. Activiteiten kunnen deze vereisen, waardoor wordt gevalideerd wat gebruikers mogen kiezen.
• Tijdaccounts bevatten saldi — verlof gemeten in dagen, of flex gemeten in uren.

Twee tijdlagen

Tijd wordt vastgelegd in twee onafhankelijke lagen:

• Aanwezigheid — inchecken/uitchecken-records. Een aanwezigheidsinterval bevat een reden (en optioneel een notitie en activiteit). De regelengine evalueert aanwezigheidsintervallen.
• Registraties — rasterregistraties die tijd toewijzen aan een activiteit, een project en dimensiewaarden.

Standaard zijn deze lagen onafhankelijk; een werktijdbeperking kan vereisen dat ze op elkaar worden afgestemd. Als vuistregel geldt: wanneer en waarom worden vastgelegd in aanwezigheid; wat en waar worden vastgelegd in registraties.

De regelengine

Toeslagen, overuren, bereikbaarheidsvergoedingen en flex worden berekend via beleidsregels die zijn opgebouwd uit plugins:

• Vergoedingenbeleid zet gewerkte tijd om in een uitbetaalbaar bedrag — via een norm-bewuste weekteller (overuren, flex/norm-delta, …) of via geordende regels (filters die intervallen selecteren en een berekening die ze schaalt), optioneel geactiveerd door specifieke redenen, en geregistreerd op een doelvergoedingsactiviteit.
• Werktijdbeleid schakelt flexregistratie in (door een flexrekening te koppelen), automatische registraties (zoals een lunchaftrek) en werktijdbeperkingen.
• Verrekeningsbeleid vormt de afsluitingspijplijn die tellers naar een tijdaccount overhevelt en de keuze tussen uitbetaling en flex verwerkt.

Filters, berekeningen, tellers, opbouwen, vervalregels, gebruiksregels, feestdaggeneratoren en de diverse werktijd- en verrekeningsstappen zijn allemaal plugins. Ontdek de beschikbare plugins en het configuratieschema van elke plugin via:

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

Lees altijd de descriptor voordat u een beleid configureert — deze geeft de exacte configuratiesleutels en waardetypes aan.

Configuratievolgorde

Omdat entiteiten naar elkaar verwijzen, maakt u ze aan van fundament naar boven: feestdagenkalenders, dimensies, tijdaccounts en redenen → activiteiten (vergoedingsdoelactiviteiten vóór het vergoedingenbeleid dat ernaar verwijst) → vergoedingen-, werktijd- en verrekeningsbeleid → arbeidsvoorwaarden → organisatie-eenheden → medewerkers → projecten.

Versies met ingangsdatum

Configuratie-entiteiten en medewerkersrecords zijn geversioneerd. Een wijziging gaat in op de ingangsdatum en een nieuw aangemaakte entiteit is niet van kracht vóór de aanmaakdatum. Om een verleden periode te wijzigen, voegt u een retroactieve versie toe in plaats van de huidige te bewerken.

Hoe resultaten worden berekend

Gewerkte totalen, vergoedingen, flex en uitbetaling worden niet live berekend in de dagelijkse urenstaat — ze komen beschikbaar wanneer een urenstaatoverzicht wordt gegenereerd en vervolgens ingediend en goedgekeurd (verrekening). Het genereren van overzichten wordt uitgevoerd als een geplande batchtaak; het bedrag voor uitbetaling versus flex wordt gekozen bij het indienen. Bouw integraties die verrekende cijfers lezen uit overzichten en accountbewegingsrapporten dienovereenkomstig.

Lijsten en bereik

Collecties zijn gepagineerd en filterbaar (zie elke operatie in de specificatie). Sommige gebruikersgerichte lijsten tonen standaard de gegevens van de aanroeper zelf — zo tonen urenstaat-overzichten standaard het bereik van de aanroeper; vraag expliciet het werkruimte-brede bereik op wanneer uw integratie dat nodig heeft.