API-tilgang
mTime tilbyr et REST-API for utviklere som vil integrere med eller automatisere systemet. Denne siden er en overordnet introduksjon — OpenAPI-spesifikasjonen er den autoritative referansen for hvert endepunkt, hvert request/response-skjema og de påkrevde tillatelsene. Detaljer på endepunktnivå gjentas bevisst ikke her.
Basis-URL
API-et ligger under /api-prefikset på din arbeidsområdevert — for eksempel https://ditt-arbeidsomrade.example/api. API-roten (GET /api/) returnerer en enkel identifikator du kan bruke som helsesjekk.
Autentisering
API-et autentiserer med API-nøkler som tilhører en tjenestebruker.
Opprett en tjenestebruker i , og gi den en API-nøkkel. Kopier nøkkelen med en gang — den vises bare én gang.
Send nøkkelen med hver forespørsel som et bearer-token:
Authorization: Bearer mtime_ak_...
Endepunktet /me representerer en interaktiv, innlogget bruker og godtar ikke tjenestebrukernøkler. Bekreft at en nøkkel fungerer ved å kalle et data-endepunkt som GET /api/employees.
OpenAPI-spesifikasjon
Hele kontrakten publiseres som OpenAPI 3.1:
GET /api/openapi.yamlGET /api/openapi.json
Generer en typet klient ut fra den i stedet for å skrive request-typer for hånd. Hver operasjon angir også tillatelsen den krever (x-required-permission), slik at du på forhånd ser hvilken rolle tjenestebrukeren din trenger.
API-områder
Operasjoner i spesifikasjonen er gruppert etter tag; den grupperingen er autoritativ. De viktigste områdene og prefiksene deres:
| Område | Sti-prefiks | Hva det dekker |
|---|---|---|
| Settings | /settings/…, /descriptor/plugins/… | Konfigurasjon: aktiviteter, årsaker, dimensjoner, tidsbankkontoer, helligdagskalendere, ansettelsesvilkår og policyer for tillegg / arbeidstid / oppgjør / fravær — samt descriptor-endepunktene som lister regelmotorens plugins og konfigurasjonsskjemaene deres |
| Admin | /admin/… | Administrasjon av arbeidsområdet: innstillinger, dataeksporter og -importer, batchjobber, HR-systemintegrasjoner, masseoperasjoner på tvers av ansatte, gjenoppretting av slettede objekter |
| Organization | /employees, /org-units | Ansatte, ansettelser og organisasjonshierarkiet |
| Users | /users, /service-users | Brukerkontoer, roller, tjenestebrukere og API-nøkler |
| Timesheet | /employees/{id}/timesheet/…, /timesheet/statements/… | Inn-/utstempling, tidsregistreringer og oppgjør (send inn / godkjenn / eksporter) |
| Time off & timebank | /employees/{id}/timeoffs, /employees/{id}/timebank | Fraværssøknader, saldoer og justeringer |
| Approvals | /approvals/… | Godkjenningsinnboks og delegeringer |
| Projects | /projects/… | Prosjekter og medlemmene deres |
| Reports | /reports/… | Registrerte timer, kontobevegelser, tilstedeværelse, aktivitetsrapporter |
| Kiosks | /kiosks, /kiosk/… | Delte innstemplingsterminaler |
| Me | /me/… | Den innloggede brukerens dashbord, preferanser og varsler |
| Auth | /auth/… | Interaktiv innlogging, OAuth, passkeys, økter — brukes ikke med API-nøkler |
| Events & webhooks | /events, /sse, /webhooks/… | Hendelsesstrøm / streaming og innkommende webhooks |
Områdene Settings og Admin er der mesteparten av konfigurasjons- og automatiseringsarbeidet skjer; Me og Auth er rettet mot interaktive økter snarere enn tjenestebrukernøkler.
Tillatelser
Hvert endepunkt er beskyttet av en tillatelse (for eksempel settings:create:*), som utledes fra tjenestebrukerens rolle. Enkelte administrative handlinger — som fulle dataeksporter — krever en høyere rolle enn vanlig konfigurasjon. Hvis et kall returnerer 403, sammenlign operasjonens påkrevde tillatelse i spesifikasjonen med tjenestebrukerens rolle.
Domenemodellen
Noen få begreper ligger til grunn for det meste av API-et:
- Ansettelsesvilkår («avtalen») binder sammen alt som gjelder en ansatt: arbeidstidsnormen, helligdagskalenderen, fraværspolicyer, tilleggspolicyer, en arbeidstidspolicy, en oppgjørspolicy, tilgjengelige årsaker og godkjenningsmodusen for oppgjør. Å knytte en ansatt til et vilkår gir dem hele pakken.
- Aktiviteter er kategoriene tid registreres på. Hver har en type —
work,timeoff,non-workellerallowance— og kan være nestet (et barn må dele forelderens type). En aktivitet kan kreve et prosjekt og/eller egendefinerte dimensjoner. - Prosjekter er arbeids-/faktureringsenheter registreringer kan føres på, og kan kreve godkjenning fra en leder.
- Dimensjoner er egendefinerte etiketter (for eksempel et kjøretøy eller utstyr) med et definert sett av tillatte verdier. Aktiviteter kan kreve dem, noe som validerer hva brukere kan velge.
- Tidsbankkontoer inneholder saldoer — fravær målt i dager, eller flex målt i timer.
To lag av tid
Tid registreres i to uavhengige lag:
- Tilstedeværelse — inn-/utstemplinger. Et tilstedeværelsesintervall bærer en årsak (og eventuelt et notat og en aktivitet). Regelmotoren evaluerer tilstedeværelsesintervaller.
- Registreringer — registreringer i rutenettet som fordeler tid på en aktivitet, et prosjekt og dimensjonsverdier.
Som standard er disse lagene uavhengige; en arbeidstidsbegrensning kan kreve at de avstemmes. Tommelfingerregel: når og hvorfor hører til tilstedeværelse; hva og hvor hører til registreringer.
Regelmotoren
Tillegg, overtid, beredskapstillegg og flex beregnes av policyer bygget av plugins:
- Tilleggspolicyer gjør arbeidet tid om til et utbetalbart beløp — enten via en norm-bevisst ukesteller (overtid, flex/norm-delta, …) eller via ordnede regler (filtre som velger intervaller + en kalkulator som skalerer dem), eventuelt utløst av bestemte årsaker og registrert på en mål-tilleggsaktivitet.
- Arbeidstidspolicyer aktiverer flex-sporing (med en tilknyttet flexkonto), automatiske registreringer (som et lunsjtrekk) og arbeidstidsbegrensninger.
- Oppgjørspolicyer er pipelinen ved periodeavslutning som fører tellere inn på en tidsbankkonto og avgjør utbetaling kontra flex.
Filtre, kalkulatorer, tellere, opptjeninger, utløp, forbruksregler, helligdagsgeneratorer og de ulike arbeidstids- og oppgjørstrinnene er alle plugins. Finn tilgjengelige plugins og konfigurasjonsskjemaet til hver enkelt her:
GET /api/descriptor/plugins/GET /api/descriptor/plugins/{registry}/{plugin_id}/schema
Les alltid descriptoren før du konfigurerer en policy — den forteller deg de nøyaktige konfigurasjonsnøklene og verditypene.
Konfigurasjonsrekkefølge
Siden objekter refererer til hverandre, opprett dem fundament-først: helligdagskalendere, dimensjoner, tidsbankkontoer og årsaker → aktiviteter (mål-tilleggsaktiviteter før tilleggspolicyene som peker på dem) → tilleggs-, arbeidstids- og oppgjørspolicyer → ansettelsesvilkår → organisasjonsenheter → ansatte → prosjekter.
Versjonering med ikrafttredelsesdato
Konfigurasjonsobjekter og ansattdata er versjonert. En endring trer i kraft fra ikrafttredelsesdatoen, og et nyopprettet objekt er ikke i kraft før opprettelsesdatoen. For å endre en tidligere periode må du legge til en tilbakevirkende versjon i stedet for å redigere den nåværende.
Hvordan resultater blir til
Arbeidede totaler, tillegg, flex og utbetaling beregnes ikke løpende i den daglige timelisten — de materialiseres når et oppgjør genereres og deretter sendes inn og godkjennes (oppgjør). Generering av oppgjør kjøres som en planlagt batchjobb; utbetaling-kontra-flex-beløpet velges ved innsending. Bygg integrasjoner som leser oppgjorte tall fra oppgjør og kontobevegelsesrapporter i samsvar med dette.
Lister og omfang
Samlinger er paginert og kan filtreres (se hver operasjon i spesifikasjonen). Noen brukersentrerte lister er som standard avgrenset til kallerens egne data — for eksempel er oppgjør som standard avgrenset til kallerens omfang; be eksplisitt om hele arbeidsområdets omfang når integrasjonen din trenger det.