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

Hvert miljø har sine egne data og sine egne nøkler — en nøkkel utstedt i det ene virker aldri i det andre. GET /ping svarer uten legitimasjon — det er den enkle tilkoblingssjekken.

Autentisering

API-et autentiserer med API-nøkler som tilhører en tjenestebruker.

1. Opprett en tjenestebruker i Admin › Brukere, og gi den en API-nøkkel. Kopier nøkkelen med en gang — den vises bare én gang.

2. Send nøkkelen med hver forespørsel som et bearer-token:

   Authorization: Bearer mtime_ak_...

Vil du sjekke en nøkkel, kall GET /api/version: den godtar enhver gyldig legitimasjon og krever ingen tillatelse, så den svarer 200 for en nøkkel som fungerer, og 401 for en som ikke gjør det — uten at rollen spiller inn.

OpenAPI-spesifikasjon

Hele kontrakten er publisert som OpenAPI 3.1:

• GET /api/openapi.yaml
• GET /api/openapi.json
• /api/docs viser den i nettleseren — produksjon, staging

I appen ligger referansen under Ressurser › API-referanse, og det menypunktet krever rollen Utvikler. Eiere har den allerede — Eier-rollen inneholder Utvikler — og ingen annen rolle viser menypunktet. Tildel Utvikler i Admin › Brukere til den som bygger integrasjonen: den åpner referansen og ingenting annet, så den er ufarlig å gi.

Den beskriver nøyaktig de endepunktene en API-nøkkel kan nå. Et endepunkt som ikke står der, er ikke tilgjengelig for integrasjoner, og et kall til det svarer 404 uten en forklaring — så se på spesifikasjonen som listen over hva som finnes.

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. Dette er områdene API-et dekker i dag — hvert av dem lenker inn i referansen:

Med en API-nøkkel er import bare tillatt i et arbeidsområde som er merket som testarbeidsområde, uansett modus og omfang. Bare batchjobbene for test — som Seed timelistemønster — kan startes. Import og eksport er eiertillatelser, og en tjenestebruker kan ikke være eier, så gi den en egendefinert rolle med tillatelsene for import og eksport i tillegg til den andre rollen.

Alt annet appen selv bruker — resten av arbeidsområdeadministrasjonen, brukere og API-nøkler, godkjenninger, kiosker, fraværssøknader, hendelser og webhooks — er ikke en del av API-et i dag. De endepunktene står ikke i spesifikasjonen, og en nøkkel som kaller et av dem, får 404.

Tillatelser

Hvert endepunkt er beskyttet av en tillatelse (for eksempel settings:create:*), som utledes fra tjenestebrukerens rolle. 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») inneholder en ansatts arbeidstidsnorm, flekskonto og godkjenningsmodus for timelisten. Helligdagskalendere, fraværs-, tilleggs-, arbeidstids- og avregningsregelverk og årsaker står ikke på vilkåret: hvert av dem angir et availability_scope (arbeidsland, organisasjonsenheter, ansettelsesvilkår) og gjelder for alle ansettelser det samsvarer med.
• Aktiviteter er kategoriene tid registreres på. Hver har en type — work, timeoff, non-work eller allowance — 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

Disse descriptor-endepunktene svarer uten en nøkkel, men de er ikke beskrevet i spesifikasjonen — selve policyene konfigureres i appen.

Konfigurasjonsrekkefølge

Bare deler av konfigurasjonen kan skrives via API-et i dag — aktiviteter, dimensjoner, tidsbankkontoer, ansatte, organisasjonsenheter og prosjekter; kalendere, årsaker, policyer og ansettelsesvilkår settes opp i appen. Siden objekter refererer til hverandre, opprett dem fundament-først: dimensjoner og tidsbankkontoer → aktiviteter → 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.

En listes limit er mellom 1 og 1000; utelat den for å få standardverdien. En verdi utenfor dette området avvises med 422. /timesheet/statements returnerer maksimalt 500 oppgjør: hvis flere samsvarer, har svaret headeren MTime-Truncated: true, så snevre inn perioden eller filteret.

Referanselistene (kontoer, aktiviteter, dimensjoner, ansettelsesvilkår, organisasjonsenheter og prosjekter) har en svak ETag. Send den tilbake i If-None-Match, så svarer en uendret liste 304 Not Modified uten innhold, og du slipper å laste den ned på nytt ved hver synkronisering.

Grenser for antall kall

Hver API-nøkkel kan gjøre 300 kall i minuttet, og alle nøklene i et arbeidsområde til sammen 600, så flere nøkler gir ikke høyere grense. Hvert svar har RateLimit-Limit, RateLimit-Remaining og RateLimit-Reset. Et kall over grensen får 429 Too Many Requests med headeren Retry-After, som angir hvor mange sekunder du må vente. Vent, og prøv igjen etterpå.