API-adgang

mTime stiller et REST-API til rådighed for udviklere, der vil integrere med systemet eller automatisere det. Denne side giver et overblik — OpenAPI-specifikationen er den gældende reference for hvert endpoint, hvert request/response-skema og de påkrævede tilladelser. Detaljer om de enkelte endpoints gentages bevidst ikke her.

Base-URL

Hvert miljø har sine egne data og sine egne nøgler — en nøgle, der er udstedt i det ene, virker aldrig i det andet. GET /ping svarer uden loginoplysninger og er den enkle kontrol af, om der er forbindelse.

Autentificering

API’et autentificerer med API-nøgler, der tilhører en servicebruger.

1. Opret en servicebruger i Admin › Brugere, og giv den en API-nøgle. Kopiér nøglen med det samme — den vises kun én gang.

2. Send nøglen med hver forespørgsel som et bearer-token:

   Authorization: Bearer mtime_ak_...

Vil du tjekke en nøgle, kan du kalde GET /api/version: det accepterer alle gyldige loginoplysninger og kræver ingen tilladelse, så det svarer 200 for en nøgle, der virker, og 401 for en, der ikke gør — uden at rollen spiller ind.

OpenAPI-specifikation

Hele kontrakten er publiceret som OpenAPI 3.1:

• GET /api/openapi.yaml
• GET /api/openapi.json
• /api/docs viser den i browseren — produktion, staging

I appen ligger referencen under Ressourcer › API-reference, og det menupunkt kræver rollen Udvikler. Ejere har den allerede — Ejer-rollen indeholder Udvikler — og ingen anden rolle viser menupunktet. Tildel rollen Udvikler i Admin › Brugere til den, der bygger integrationen: den giver adgang til referencen og intet andet, så den er ufarlig at uddele.

Den beskriver præcis de endpoints, en API-nøgle kan nå. Et endpoint, der ikke står der, er ikke tilgængeligt for integrationer, og et kald til det giver 404 uden forklaring — så betragt specifikationen som listen over, hvad der findes.

Generér en typet klient ud fra den i stedet for at skrive request-typer i hånden. Hver operation angiver også den tilladelse, den kræver (x-required-permission), så du på forhånd kan se, hvilken rolle din servicebruger har brug for.

API-områder

Operationerne i specifikationen er grupperet efter tag, og det er den gruppering, der gælder. Det er de områder, API’et dækker i dag — hvert af dem linker ind i referencen:

Med en API-nøgle er import kun tilladt i et arbejdsområde, der er markeret som testarbejdsområde, uanset tilstand og omfang. Kun de batchjob, der er beregnet til test — f.eks. Udfyld tidsregistrering efter mønster — kan startes. Import og eksport kræver ejerens tilladelser, og en servicebruger kan ikke være ejer, så giv den en brugerdefineret rolle med tilladelserne til import og eksport ud over dens anden rolle.

Alt andet, som appen selv bruger — resten af administrationen af arbejdsområdet, brugere og API-nøgler, godkendelser, kiosker, fraværsanmodninger, hændelser og webhooks — er ikke en del af API’et i dag. De endpoints står ikke i specifikationen, og en nøgle, der kalder et af dem, får 404.

Tilladelser

Hvert endpoint er beskyttet af en tilladelse (for eksempel settings:create:*), som udledes af servicebrugerens rolle. Hvis et kald returnerer 403, skal du sammenholde operationens påkrævede tilladelse i specifikationen med servicebrugerens rolle.

Domænemodellen

Nogle få begreber ligger til grund for det meste af API’et:

• Ansættelsesvilkår (“overenskomsten”) rummer de indstillinger for en ansættelse, der hører til kontrakten: arbejdstidsnormen, flexkontoen, aktiviteten for timeløn, standardårsagen og godkendelsestilstanden for opgørelser. Helligdagskalendere, politikker (fraværs-, tillægs-, arbejdstids- og afregningspolitikker) og årsager er ikke knyttet til ansættelsesvilkårene — hver af dem angiver sin egen tilgængelighed (availability_scope), der afgør, hvilke ansættelser den gælder for, ud fra arbejdsland, organisationsenhed og ansættelsesvilkår.
• Aktiviteter er de kategorier, tid registreres på. Hver har en type — work, timeoff, non-work eller allowance — og kan ligge i et hierarki (en underaktivitet skal have samme type som sin overordnede aktivitet). En aktivitet kan kræve et projekt og/eller brugerdefinerede dimensioner.
• Projekter er arbejds- eller faktureringsenheder, som registreringer kan bogføres på, og de kan kræve en leders godkendelse.
• Dimensioner er brugerdefinerede tags (for eksempel et køretøj eller et stykke udstyr) med et defineret sæt tilladte værdier. Aktiviteter kan kræve dem, og så kontrolleres det, hvad brugerne må vælge.
• Tidskonti indeholder saldi — fravær målt i dage eller flex målt i timer.

To lag af tid

Tid registreres i to uafhængige lag:

• Tilstedeværelse — check-ind- og check-ud-registreringer. Et tilstedeværelsesinterval har en årsag (og eventuelt et notat og en aktivitet). Regelmotoren evaluerer tilstedeværelsesintervaller.
• Posteringer — registreringer i gitteret, der fordeler tid på en aktivitet, et projekt og dimensionsværdier.

Som standard er disse lag uafhængige; en arbejdstidsbegrænsning kan kræve, at de afstemmes. Tommelfingerregel: hvornår og hvorfor hører til tilstedeværelse; hvad og hvor hører til posteringerne.

Regelmotoren

Tillæg, overarbejde, rådighedstillæg og flex beregnes af politikker, der er bygget af plugins:

• Tillægspolitikker omsætter arbejdstid til noget, der kan udbetales — enten via en ugetæller, der tager højde for normen (merarbejde, overarbejde, minustimer, arbejdede timer) eller via ordnede regler (filtre, der udvælger intervaller + en beregner, der omsætter dem til et antal), eventuelt udløst af bestemte årsager og registreret på en tillægsaktivitet.
• Arbejdstidspolitikker rummer arbejdstidsbegrænsninger og automatiske registreringer (såsom et frokosttræk). Selve flexkontoen angives på ansættelsesvilkårene.
• Afregningspolitikker er de trin ved periodeafslutning, der indsætter tællernes tid på en tidskonto og afgør, hvad der udbetales, og hvad der går til flex.

Filtre, beregnere, tællere, optjeninger, udløb, forbrugsregler, helligdagsgeneratorer og de forskellige arbejdstids- og afregningstrin er alle plugins. Du kan se de tilgængelige plugins og hvert plugins konfigurationsskema her:

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

Disse descriptor-endpoints svarer uden en nøgle, men de er ikke beskrevet i specifikationen — selve politikkerne konfigureres i appen.

Konfigurationsrækkefølge

Kun en del af konfigurationen kan skrives via API’et i dag — aktiviteter, dimensioner, tidskonti, medarbejdere, organisationsenheder og projekter; kalendere, årsager, politikker og ansættelsesvilkår sættes op i appen. Da objekterne henviser til hinanden, skal du oprette dem nedefra og op: dimensioner og tidskonti → aktiviteter → organisationsenheder → medarbejdere → projekter.

Versionering med ikrafttrædelsesdato

Konfigurationsobjekter og medarbejderdata er versionerede. En ændring træder i kraft på sin ikrafttrædelsesdato, og et nyoprettet objekt gælder ikke før sin oprettelsesdato. Vil du ændre en tidligere periode, skal du tilføje en tilbagevirkende version i stedet for at redigere den nuværende.

Hvordan resultater bliver til

Arbejdstid i alt, tillæg, flex og udbetaling beregnes ikke løbende i den daglige tidsregistrering — tallene dannes først, når en opgørelse genereres og derefter indsendes og godkendes (afregning). Opgørelserne genereres af et planlagt batchjob, og fordelingen mellem udbetaling og flex vælges ved indsendelsen. Byg derfor integrationer, så de læser de afregnede tal fra opgørelser og rapporter over kontobevægelser.

Lister og scope

Lister returneres side for side og kan filtreres (se de enkelte operationer i specifikationen). Nogle lister, der tager udgangspunkt i brugeren, viser som standard kun kalderens egne data — for eksempel er opgørelser som standard afgrænset til kalderens scope. Bed udtrykkeligt om hele arbejdsområdet som scope, når din integration har brug for det.

En listes limit skal være mellem 1 og 1000; udelad den for at få standardværdien. En værdi uden for intervallet afvises med 422. /timesheet/statements returnerer højst 500 opgørelser: matchede flere, har svaret headeren MTime-Truncated: true, så indsnævr perioden eller filteret.

Referencelisterne (konti, aktiviteter, dimensioner, ansættelsesvilkår, organisationsenheder og projekter) har et svagt ETag. Send det tilbage i If-None-Match, så svarer en uændret liste 304 Not Modified uden indhold, og du slipper for at hente den igen ved hver synkronisering.

Grænser for antal kald

Hver API-nøgle må lave 300 kald i minuttet, og alle nøgler i et workspace tilsammen 600, så flere nøgler giver ikke mere plads. Hvert svar har RateLimit-Limit, RateLimit-Remaining og RateLimit-Reset. Et kald over grænsen får 429 Too Many Requests med headeren Retry-After, der angiver, hvor mange sekunder der skal ventes. Vent, og prøv igen derefter.