API-åtkomst
mTime tillhandahåller ett REST-API för utvecklare som vill integrera med eller automatisera systemet. Den här sidan är en översiktlig introduktion — OpenAPI-specifikationen är den auktoritativa referensen för varje endpoint, varje request/response-schema och de behörigheter som krävs. Detaljer på endpoint-nivå upprepas medvetet inte här.
Bas-URL
| Miljö | Bas-URL |
|---|---|
| Produktion | https://mtime.app/api |
| Staging | https://staging-mtime.app/api |
Varje miljö har sina egna data och sina egna nycklar — en nyckel som utfärdats i den ena fungerar aldrig i den andra. GET /ping svarar utan inloggningsuppgifter — det är den enkla anslutningskontrollen.
Autentisering
API:et autentiserar med API-nycklar som tillhör en tjänsteanvändare.
Skapa en tjänsteanvändare i och ge den en API-nyckel. Kopiera nyckeln direkt — den visas bara en gång.
Skicka nyckeln med varje begäran som en bearer-token:
Authorization: Bearer mtime_ak_...
Ge tjänsteanvändaren den roll som täcker de data din integration rör — samma roller som beskrivs under Användare och behörigheter. Tilldela den minst privilegierade som klarar uppgiften: varje endpoint skyddas av en behörighet, och en saknad behörighet är just vad en 403 betyder.
Rollen Utvecklare är inte en av dem. Den styr om API-referensen visas i appens meny för en person som loggar in, och ger ingen åtkomst till data — så den gör ingenting för en tjänsteanvändare.
En tjänsteanvändare är inte kopplad till en anställd, så behörigheter med omfattningen Managed eller Self ger den ingen åtkomst till endpoints som adresserar en enskild anställd (/employees/{employee_id}/…) — de anropen nekas. Ge en integration som arbetar för anställdas räkning omfattningen All för de resurser den använder.
Vill du kontrollera en nyckel, anropa GET /api/version: den godtar vilken giltig uppgift som helst och kräver ingen behörighet, så den svarar 200 för en nyckel som fungerar och 401 för en som inte gör det — utan att rollen påverkar.
OpenAPI-specifikation
Hela kontraktet publiceras som OpenAPI 3.1:
GET /api/openapi.yamlGET /api/openapi.json/api/docsvisar det i webbläsaren — produktion, staging
I appen ligger referensen under , och den menyposten kräver rollen Utvecklare. Ägare har den redan — Ägar-rollen innehåller Utvecklare — och ingen annan roll visar menyposten. Tilldela Utvecklare i till den som bygger integrationen: den öppnar referensen och inget annat, så den är ofarlig att dela ut.
Det beskriver exakt de endpoints en API-nyckel kan nå. En endpoint som inte finns med är inte tillgänglig för integrationer, och ett anrop till den svarar 404 utan förklaring — betrakta därför specifikationen som listan över vad som finns.
Generera en typad klient från den i stället för att skriva request-typer för hand. Varje operation anger även den behörighet den kräver (x-required-permission), så att du i förväg ser vilken roll din tjänsteanvändare behöver.
API-områden
Operationer i specifikationen är grupperade efter tagg; den grupperingen är auktoritativ. Det här är de områden API:et täcker i dag — var och en länkar in i referensen:
| Område | Sökvägsprefix | Vad det täcker |
|---|---|---|
| Organization | /employees, /org-units | Medarbetare och organisationshierarkin — läs, skapa och uppdatera |
| Settings | /settings/… | Aktiviteter, dimensioner och tidsbankskonton (läs, skapa, uppdatera) samt anställningsvillkor (läs) |
| Timesheet | /employees/{employee_id}/timesheet, /timesheet/statements | En medarbetares tidrapport och de avräkningar en period stängs till |
| Timebank | /employees/{employee_id}/timebank/balances | Aktuella saldon per konto |
| Projects | /projects | Projekt — läs, skapa och uppdatera |
| Reports | /reports/… | Registrerade timmar, kontorörelser, närvaro, frånvaro, sjukfrånvaro och efterlevnad av arbetstidsregler |
| Admin | /admin/imports, /admin/exports, /admin/jobs | Jobb för dataimport och dataexport i arbetsytan, och start av ett batchjobb som bara finns för test, på en testarbetsyta, med uppföljning av körningen |
| Misc | /ping, /version | Tillgänglighetskontroll och API-versionen |
Med en API-nyckel tillåts import bara i en arbetsyta som är märkt som testarbetsyta, oavsett läge och omfattning. Bara batchjobben för test — som Seed tidrapportmönster — kan startas. Import och export är ägarbehörigheter och en tjänsteanvändare kan inte vara ägare, så ge den en anpassad roll med behörigheterna för import och export utöver dess andra roll.
Allt annat som appen själv använder — resten av arbetsyteadministrationen, användare och API-nycklar, godkännanden, kiosker, frånvaroansökningar, händelser och webhooks — ingår inte i API:et i dag. De endpoints finns inte i specifikationen, och en nyckel som anropar någon av dem får 404.
Behörigheter
Varje endpoint skyddas av en behörighet (till exempel settings:create:*), som härleds från tjänsteanvändarens roll. Om ett anrop returnerar 403, jämför operationens nödvändiga behörighet i specifikationen med tjänsteanvändarens roll.
Domänmodellen
Några få begrepp ligger till grund för större delen av API:et:
- Anställningsvillkor (”avtalet”) bär en medarbetares arbetstidsnorm, flexkonto och godkännandeläge för tidrapporter. Helgdagskalendrar, frånvaro-, tilläggs-, arbetstids- och avstämningsregelverk samt orsaker listas inte på villkoret: vart och ett deklarerar ett
availability_scope(arbetsländer, organisationsenheter, anställningsvillkor) och gäller för varje anställning som det matchar. - Aktiviteter är de kategorier som tid registreras på. Var och en har en typ —
work,timeoff,non-workellerallowance— och kan vara nästlad (ett barn måste dela förälderns typ). En aktivitet kan kräva ett projekt och/eller anpassade dimensioner. - Projekt är arbets-/faktureringsenheter som registreringar kan bokföras på, och kan kräva godkännande av en chef.
- Dimensioner är anpassade etiketter (till exempel ett fordon eller en utrustning) med en definierad uppsättning tillåtna värden. Aktiviteter kan kräva dem, vilket validerar vad användare får välja.
- Tidsbankskonton innehåller saldon — frånvaro mätt i dagar, eller flex mätt i timmar.
Två lager av tid
Tid registreras i två oberoende lager:
- Närvaro — in-/utstämplingar. Ett närvarointervall bär en orsak (och eventuellt en anteckning och en aktivitet). Regelmotorn utvärderar närvarointervall.
- Registreringar — registreringar i rutnätet som fördelar tid på en aktivitet, ett projekt och dimensionsvärden.
Som standard är dessa lager oberoende; en arbetstidsbegränsning kan kräva att de stäms av. Tumregel: när och varför hör till närvaro; vad och var hör till registreringar.
Regelmotorn
Tillägg, övertid, beredskapstillägg och flex beräknas av policyer byggda av plugins:
- Tilläggspolicyer omvandlar arbetad tid till ett utbetalbart belopp — antingen via en norm-medveten veckoräknare (övertid, flex/norm-delta, …) eller via ordnade regler (filter som väljer ut intervall + en kalkylator som skalar dem), eventuellt utlösta av specifika orsaker och registrerade på en mål-tilläggsaktivitet.
- Arbetstidspolicyer aktiverar flex-spårning (med ett kopplat flexkonto), automatiska registreringar (som ett lunchavdrag) och arbetstidsbegränsningar.
- Regleringspolicyer är den pipeline vid periodavslut som bokför räknare till ett tidsbankskonto och avgör utbetalning kontra flex.
Filter, kalkylatorer, räknare, intjäningar, utgångar, användningsregler, helgdagsgeneratorer och de olika arbetstids- och regleringsstegen är alla plugins. Hitta tillgängliga plugins och konfigurationsschemat för var och en här:
GET /api/descriptor/plugins/GET /api/descriptor/plugins/{registry}/{plugin_id}/schema
Dessa descriptor-endpoints svarar utan nyckel, men de beskrivs inte i specifikationen — själva policyerna konfigureras i appen.
Konfigurationsordning
Bara en del av konfigurationen går att skriva via API:et i dag — aktiviteter, dimensioner, tidsbankskonton, medarbetare, organisationsenheter och projekt; kalendrar, orsaker, policyer och anställningsvillkor ställs in i appen. Eftersom objekt refererar till varandra skapar du dem grund-först: dimensioner och tidsbankskonton → aktiviteter → organisationsenheter → medarbetare → projekt.
Versionshantering med ikraftträdandedatum
Konfigurationsobjekt och medarbetarposter är versionerade. En ändring träder i kraft från sitt ikraftträdandedatum, och ett nyskapat objekt gäller inte före sitt skapandedatum. För att ändra en tidigare period lägger du till en retroaktiv version i stället för att redigera den nuvarande.
Hur resultat skapas
Arbetade summor, tillägg, flex och utbetalning beräknas inte i realtid på den dagliga tidrapporten — de materialiseras när en redovisning genereras och därefter skickas in och godkänns (reglering). Generering av redovisningar körs som ett schemalagt batchjobb; beloppet utbetalning-kontra-flex väljs vid inskick. Bygg integrationer som läser reglerade siffror från redovisningar och kontorörelserapporter i enlighet med detta.
Listor och omfattning
Samlingar är paginerade och filtrerbara (se varje operation i specifikationen). Vissa användarcentrerade listor är som standard begränsade till anroparens egna data — till exempel är redovisningar som standard begränsade till anroparens omfattning; begär uttryckligen hela arbetsytans omfattning när din integration behöver det.
En listas limit ligger mellan 1 och 1000; utelämna den för att få standardvärdet. Ett värde utanför intervallet avvisas med 422. /timesheet/statements returnerar högst 500 avräkningar: om fler matchar har svaret headern MTime-Truncated: true, så begränsa perioden eller filtret.
Referenslistorna (konton, aktiviteter, dimensioner, anställningsvillkor, organisationsenheter och projekt) har en svag ETag. Skicka tillbaka den i If-None-Match så svarar en oförändrad lista 304 Not Modified utan innehåll, och du slipper ladda ned den igen vid varje synkronisering.
Gränser för antal anrop
Varje API-nyckel får göra 300 anrop per minut, och alla nycklar i en arbetsyta tillsammans 600, så fler nycklar höjer inte gränsen. Varje svar har RateLimit-Limit, RateLimit-Remaining och RateLimit-Reset. Ett anrop över gränsen får 429 Too Many Requests med headern Retry-After, som anger hur många sekunder du ska vänta. Vänta och försök igen efter det.