API-adgang
mTime stiller et REST-API til rådighed for udviklere, der vil integrere med eller automatisere systemet. Denne side er en overordnet introduktion — OpenAPI-specifikationen er den autoritative reference for hvert endpoint, hvert request/response-skema og de påkrævede tilladelser. Detaljer på endpoint-niveau gentages bevidst ikke her.
Base-URL
API’et ligger under /api-præfikset på din workspace-vært — for eksempel https://din-workspace.example/api. API-roden (GET /api/) returnerer en simpel identifikator, du kan bruge som health-check.
Godkendelse
API’et godkender med API-nøgler, der tilhører en service-bruger.
Opret en service-bruger i , og giv den en API-nøgle. Kopiér nøglen med det samme — den vises kun én gang.
Send nøglen med hver forespørgsel som et bearer-token:
Authorization: Bearer mtime_ak_...
Endpointet /me repræsenterer en interaktiv, indlogget bruger og accepterer ikke service-bruger-nøgler. Bekræft, at en nøgle virker, ved at kalde et data-endpoint som GET /api/employees.
OpenAPI-specifikation
Hele kontrakten udgives som OpenAPI 3.1:
GET /api/openapi.yamlGET /api/openapi.json
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 service-bruger har brug for.
API-områder
Operationer i specifikationen er grupperet efter tag; den gruppering er autoritativ. De vigtigste områder og deres sti-præfikser:
| Område | Sti-præfiks | Hvad det dækker |
|---|---|---|
| Settings | /settings/…, /descriptor/plugins/… | Konfiguration: aktiviteter, årsager, dimensioner, tidsbankkonti, helligdagskalendere, ansættelsesvilkår og policyer for tillæg / arbejdstid / afregning / fravær — samt descriptor-endpoints, der lister regelmotorens plugins og deres konfigurationsskemaer |
| Admin | /admin/… | Workspace-administration: workspace-indstillinger, dataeksporter og -importer, batchjob, HR-systemintegrationer, massehandlinger på tværs af medarbejdere, gendannelse af slettede objekter |
| Organization | /employees, /org-units | Medarbejdere, ansættelser og organisationshierarkiet |
| Users | /users, /service-users | Brugerkonti, roller, service-brugere og API-nøgler |
| Timesheet | /employees/{id}/timesheet/…, /timesheet/statements/… | Tjek ind/ud, tidsregistreringer og opgørelser (indsend / godkend / eksportér) |
| Time off & timebank | /employees/{id}/timeoffs, /employees/{id}/timebank | Fraværsanmodninger, saldi og justeringer |
| Approvals | /approvals/… | Godkendelsesindbakke og delegeringer |
| Projects | /projects/… | Projekter og deres medlemmer |
| Reports | /reports/… | Registrerede timer, kontobevægelser, tilstedeværelse, aktivitetsrapporter |
| Kiosks | /kiosks, /kiosk/… | Delte indtjekningsterminaler |
| Me | /me/… | Den indloggede brugers dashboard, præferencer og notifikationer |
| Auth | /auth/… | Interaktiv login, OAuth, passkeys, sessioner — bruges ikke med API-nøgler |
| Events & webhooks | /events, /sse, /webhooks/… | Begivenhedsfeed / streaming og indgående webhooks |
Områderne Settings og Admin er der, hvor det meste konfigurations- og automatiseringsarbejde foregår; Me og Auth er rettet mod interaktive sessioner snarere end service-bruger-nøgler.
Tilladelser
Hvert endpoint er beskyttet af en tilladelse (for eksempel settings:create:*), som udledes af service-brugerens rolle. Visse administrative handlinger — såsom fulde dataeksporter — kræver en højere rolle end almindelig konfiguration. Hvis et kald returnerer 403, så sammenhold operationens påkrævede tilladelse i specifikationen med service-brugerens rolle.
Domænemodellen
Nogle få begreber ligger til grund for det meste af API’et:
- Ansættelsesvilkår (“overenskomsten”) binder alt det sammen, der gælder for en medarbejder: arbejdstidsnormen, helligdagskalenderen, fraværspolitikker, tillægspolitikker, en arbejdstidspolitik, en afregningspolitik, tilgængelige årsager og godkendelsestilstanden for opgørelser. At tilknytte en medarbejder til et vilkår giver dem hele pakken.
- Aktiviteter er de kategorier, tid registreres på. Hver har en type —
work,timeoff,non-workellerallowance— og kan være indlejret (et barn skal dele sin forælders type). En aktivitet kan kræve et projekt og/eller brugerdefinerede dimensioner. - Projekter er arbejds-/faktureringsenheder, registreringer kan bogføres på, og 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, hvilket validerer, hvad brugere må vælge.
- Tidsbankkonti 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 — tjek ind/ud-registreringer. Et tilstedeværelsesinterval bærer en årsag (og eventuelt en note og en aktivitet). Regelmotoren evaluerer tilstedeværelsesintervaller.
- Registreringer — 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 registreringer.
Regelmotoren
Tillæg, overarbejde, rådighedstillæg og flex beregnes af policyer bygget af plugins:
- Tillægspolitikker omsætter arbejdet tid til et udbetalbart beløb — enten via en norm-bevidst uge-tæller (overarbejde, flex/norm-delta, …) eller via ordnede regler (filtre, der udvælger intervaller + en beregner, der skalerer dem), eventuelt udløst af bestemte årsager og registreret på en mål-tillægsaktivitet.
- Arbejdstidspolitikker aktiverer flex-sporing (med en tilknyttet flexkonto), automatiske registreringer (såsom et frokosttræk) og arbejdstidsbegrænsninger.
- Afregningspolitikker er den pipeline ved periodeafslutning, der bogfører tællere ind på en tidsbankkonto og afgør udbetaling kontra flex.
Filtre, beregnere, tællere, optjeninger, udløb, forbrugsregler, helligdagsgeneratorer og de forskellige arbejdstids- og afregningstrin er alle plugins. Find de tilgængelige plugins og hvert enkelt plugins konfigurationsskema her:
GET /api/descriptor/plugins/GET /api/descriptor/plugins/{registry}/{plugin_id}/schema
Læs altid descriptoren, før du konfigurerer en policy — den fortæller dig de præcise konfigurationsnøgler og værdityper.
Konfigurationsrækkefølge
Da objekter refererer til hinanden, skal du oprette dem fundament-først: helligdagskalendere, dimensioner, tidsbankkonti og årsager → aktiviteter (mål-tillægsaktiviteter før de tillægspolitikker, der peger på dem) → tillægs-, arbejdstids- og afregningspolitikker → ansættelsesvilkår → organisationsenheder → medarbejdere → projekter.
Versionering med ikrafttrædelsesdato
Konfigurationsobjekter og medarbejderdata er versionerede. En ændring træder i kraft fra dens ikrafttrædelsesdato, og et nyoprettet objekt er ikke i kraft før dets oprettelsesdato. For at ændre en tidligere periode skal du tilføje en tilbagevirkende version i stedet for at redigere den nuværende.
Hvordan resultater bliver til
Arbejdede totaler, tillæg, flex og udbetaling beregnes ikke løbende i den daglige tidsregistrering — de materialiseres, når en opgørelse genereres og derefter indsendes og godkendes (afregning). Generering af opgørelser kører som et planlagt batchjob; udbetalings-kontra-flex-beløbet vælges ved indsendelse. Byg integrationer, der læser afregnede tal fra opgørelser og kontobevægelsesrapporter i overensstemmelse hermed.
Lister og scope
Samlinger er pagineret og kan filtreres (se hver operation i specifikationen). Nogle bruger-centrerede lister er som standard afgrænset til kalderens egne data — for eksempel er opgørelser som standard afgrænset til kalderens scope; anmod eksplicit om hele workspacets scope, når din integration har brug for det.