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
API:et finns under prefixet /api på din arbetsytas värd — till exempel https://din-arbetsyta.example/api. API-roten (GET /api/) returnerar en enkel identifierare som du kan använda som hälsokontroll.
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_...
Endpointen /me representerar en interaktiv, inloggad användare och accepterar inte tjänsteanvändarnycklar. Bekräfta att en nyckel fungerar genom att anropa en data-endpoint som GET /api/employees.
OpenAPI-specifikation
Hela kontraktet publiceras som OpenAPI 3.1:
GET /api/openapi.yamlGET /api/openapi.json
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 grupperas efter tagg; den grupperingen är auktoritativ. De viktigaste områdena och deras sökvägsprefix:
| Område | Sökvägsprefix | Vad det täcker |
|---|---|---|
| Settings | /settings/…, /descriptor/plugins/… | Konfiguration: aktiviteter, orsaker, dimensioner, tidsbankskonton, helgdagskalendrar, anställningsvillkor och policyer för tillägg / arbetstid / reglering / frånvaro — samt descriptor-endpoints som listar regelmotorns plugins och deras konfigurationsscheman |
| Admin | /admin/… | Administration av arbetsytan: inställningar, dataexporter och -importer, batchjobb, HR-systemintegrationer, massåtgärder över flera medarbetare, återställning av borttagna objekt |
| Organization | /employees, /org-units | Medarbetare, anställningar och organisationshierarkin |
| Users | /users, /service-users | Användarkonton, roller, tjänsteanvändare och API-nycklar |
| Timesheet | /employees/{id}/timesheet/…, /timesheet/statements/… | In-/utstämpling, tidsregistreringar och redovisningar (skicka in / godkänn / exportera) |
| Time off & timebank | /employees/{id}/timeoffs, /employees/{id}/timebank | Frånvaroansökningar, saldon och justeringar |
| Approvals | /approvals/… | Godkännandeinkorg och delegeringar |
| Projects | /projects/… | Projekt och deras medlemmar |
| Reports | /reports/… | Registrerade timmar, kontorörelser, närvaro, aktivitetsrapporter |
| Kiosks | /kiosks, /kiosk/… | Delade instämplingsterminaler |
| Me | /me/… | Den inloggade användarens panel, inställningar och aviseringar |
| Auth | /auth/… | Interaktiv inloggning, OAuth, passkeys, sessioner — används inte med API-nycklar |
| Events & webhooks | /events, /sse, /webhooks/… | Händelseflöde / streaming och inkommande webhooks |
Områdena Settings och Admin är där det mesta av konfigurations- och automatiseringsarbetet sker; Me och Auth är inriktade på interaktiva sessioner snarare än tjänsteanvändarnycklar.
Behörigheter
Varje endpoint skyddas av en behörighet (till exempel settings:create:*), som härleds från tjänsteanvändarens roll. Vissa administrativa åtgärder — som fullständiga dataexporter — kräver en högre roll än vanlig konfiguration. 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”) binder samman allt som gäller för en medarbetare: arbetstidsnormen, helgdagskalendern, frånvaropolicyer, tilläggspolicyer, en arbetstidspolicy, en regleringspolicy, tillgängliga orsaker och godkännandeläget för redovisningar. Att koppla en medarbetare till ett villkor ger dem hela paketet.
- 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
Läs alltid descriptorn innan du konfigurerar en policy — den anger de exakta konfigurationsnycklarna och värdetyperna.
Konfigurationsordning
Eftersom objekt refererar till varandra, skapa dem grund-först: helgdagskalendrar, dimensioner, tidsbankskonton och orsaker → aktiviteter (mål-tilläggsaktiviteter före de tilläggspolicyer som pekar på dem) → tilläggs-, arbetstids- och regleringspolicyer → anställningsvillkor → 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.