Integrera med JSON- eller XML-API

Integrationer · Steg-för-steg-guide

Modul:

Tillvalsmodul: Importmodulen

För integrationsansvariga och administratörer

Uppdaterad 2026-11-12 10:50

Kort svar

Bestäm först vilken uppgift integrationen ska skapa eller ändra. Välj sedan det API-anrop och det JSON- eller XML-format som hör till just uppgiften. Prova med ett begränsat underlag och kontrollera både API-svaret och resultatet i Timeplan.

Förberedelse

Innan du börjar

Importmodulen måste vara aktiverad för importfunktionerna i den här guiden. Utse en integrationsansvarig och en person som ansvarar för de berörda uppgifterna i Timeplan. Ett API är gränssnittet som låter ett annat system lämna eller hämta uppgifter genom ett anrop. JSON och XML beskriver hur uppgifterna skrivs i anropet; de avgör inte i sig vilken behörighet eller funktion som används.

Ta fram den aktuella dokumentationen för det anrop ni har valt. Där behöver ni kontrollera adressen, vilka uppgifter som ska skickas, deras format och vilken åtkomst som krävs. Den här guiden ersätter inte den beskrivningen eller ett färdigt exempel för just er funktion.

Prova inte mot skarpa uppgifter utan en återställningsplan

Vissa importer uppdaterar befintliga anställningar eller ersätter schema och saldon för ett datum. Kontrollera vilken uppgift som ändras och hur en felaktig körning ska rättas innan integrationen startas.

Steg för steg

Välj rätt API

Beskriv uppgiften som ska överförasBestäm om ni ska föra över budget, enheter, arbetspass, personuppgifter eller semestersaldon.

JSON används i det dokumenterade underlaget bland annat för budgetvärden, skapande eller uppdatering av enheter samt planerade arbetspass och heldagsfrånvaro. De här anropen har olika fält och olika konsekvenser.
XML används bland annat för Hogias person- och semestersaldouppgifter samt SD Worx uppgifter om anställning och semester. En XML-fil som följer en leverantörs struktur ska inte skickas till en annan leverantörs anrop.
Filändelsen avgör inte API-valet. Läs beskrivningen av datainnehållet för det anrop som faktiskt ska användas och kontrollera vilka externa identifierare som måste finnas i förväg. Ett format som går att läsa är inte tillräckligt om anropet avser en annan uppgift än den ni vill ändra.

Ordna behörighet och identifierareKontrollera vilka rättigheter integrationen behöver och hur externa företag, medarbetare, konton och enheter identifieras.

JSON-anropen /v1/dataimport/forenadebudget, /v1/dataimport/budget och /v1/dataimport/createorupdatecostdivision kräver en autentiserad Timeplan-användare. Det innebär att anropet behöver använda en verifierad användaridentitet. Kontrollera att integrationen använder rätt konto och rätt Timeplan-miljö för det valda anropet.
JSON-importen av arbetspass via /integration/shifts/json kräver superadministratörsbehörighet eller behörighetsnivån Timeplan Support. Kontot behöver dessutom ha fullständig åtkomst till alla företag eller till alla arbetsuppgifter. Det räcker att ett av de två åtkomstalternativen gäller; båda krävs inte samtidigt. Blanda inte ihop arbetsuppgifter med organisationens överordnade avdelningar när åtkomsten kontrolleras.
Hogias person- och anställningsimport via /v1/dataimport/hogiapersonimport kräver en autentiserad Timeplan-användare. Den har inte samma behörighetskrav som SD Worx-anropen, även om båda tar emot XML.
SD Worx-anropen /v1/integrations/sdworx/import/employment_update och /v1/integrations/sdworx/import/staff_vacation kräver superadministratörsbehörighet eller behörighetsnivån Timeplan Support. Kontrollera den behörigheten innan ni provar något av dessa anrop; åtkomst till Hogias personimport räcker inte som kontroll.
Hogias separata import av semestersaldon via /payroll/balances/hogia kräver både en autentiserad användare och den sidåtkomst som anropets public-API-kontroll kräver. Att kontot kan köra Hogias personimport visar därför inte att det också får uppdatera semestersaldon. Låt ansvarig administratör kontrollera åtkomsten för just detta anrop innan integrationen används.
En extern identifierare ska peka på rätt medarbetare, konto eller enhet. Om ett nummer inte går att matcha behöver kopplingen rättas innan testet fortsätter. Använd inte ett internt databas-ID som en gissad ersättning; ett till synes giltigt nummer kan annars avse en annan uppgift än den ni tänkte ändra.
Vid Hogia XML behöver särskilt personnummer, kollektivavtal och arbetsuppgift kontrolleras mot Timeplan innan personuppgifter lämnas. Ett okänt värde för kollektivavtal kan i den nuvarande importen välja ett annat avtal i stället för att ge fel. Flera personer med samma identifierare kan också ge en första träff utan dubblettfel, och för en redan registrerad person kan arbetsuppgiften från det tidigare avtalet användas trots ett annat värde i XML-filen. Jämför därför den faktiskt ändrade personen, avtalet och arbetsuppgiften efter provet; tolka inte ett lyckat svar som bevis för rätt matchning.
Lösenord, token och fullständiga person- eller löneuppgifter ska inte kopieras till felrapporter eller vanliga supportmeddelanden. Dela endast den information som behövs för felsökningen via godkänd kanal.

Steg för steg

Prova integrationen

Skicka ett avgränsat testAnvänd dokumenterat format, rätt innehållstyp och ett litet testunderlag för det valda anropet. > [!WARNING] > Kontrollera befintliga värden innan ett anrop skickas om > Ett fel från SD Worx XML-import betyder inte säkert att alla ändringar uteblev: giltiga poster kan redan ha sparats trots svaret HTTP 400. En lyckad Budget-import med JSON ersätter dessutom tidigare budgetvärden för berört konto och berörda arbetsuppgifter under hela det valda datumintervallet. Budget-anropet multiplicerar också varje skickat belopp med 3 600 utan att först kontrollera om kontot avser tid, antal eller pengar. Prova därför inte ett belopp på ett konto med annan enhet än tid som om mottagarens värde vore fastställt. Be integrationsansvarig kontrollera vad som redan finns i Timeplan och hur en omkörning påverkar det innan ni skickar samma underlag igen.

Ett JSON-anrop behöver de fält och datumformat som beskrivs för den valda funktionen. Ett XML-anrop behöver motsvarande struktur för rätt leverantör. Kontrollera innehållet mot dokumentationen innan testet skickas; ett lyckat tekniskt svar visar inte ensamt att den avsedda uppgiften har ändrats.
När ni importerar Budget med JSON räcker det inte att granska datumen som finns i den nya filen. För kontot och varje arbetsuppgift som ingår i leveransen ersätts gamla budgetvärden på alla datum i intervallet, även om ett datum saknas i de nya posterna. Kontrollera därför hela intervallet och behåll ett underlag som visar vilka värden som ska finnas kvar efter importen.
Budget-JSON omvandlar varje skickat Amount genom att multiplicera med 3 600 oavsett kontots enhet. För ett tidskonto behöver ni jämföra mot den avsedda tidsenheten; för konton som gäller pengar eller antal är den avsedda externa enheten ännu inte fastställd. Använd inte ett lyckat anrop som bevis för att belopp eller antal har fått rätt storlek.
Schemaimport kan ersätta befintliga arbetspass eller heldagsfrånvaro för importerade dagar. Välj därför testdatum och medarbetare där ni kan kontrollera både vad som tillkom och vad som eventuellt ersattes på sidan Veckoöversikt.
Spara tidpunkt, anropstyp och svaret från testet. Om svaret innehåller ett referens- eller korrelationsnummer för körningen ska det också antecknas. Då kan integrationsansvarig hitta rätt försök utan att ni behöver sprida hela innehållet i anropet.

Kontrollera resultatet i TimeplanJämför testets förväntade värde med den faktiska posten på rätt företag, datum och medarbetare eller konto.

En import av budgetvärden ska följas upp på rätt konto och datum. Det sparade dagsvärdet betyder inte att vecko-, månads- eller andra periodrapporter redan är uppdaterade: Budget-JSON begär ingen säker omräkning som täcker hela det importerade intervallet. Kontrollera därför rapporterna först efter en bekräftad beräkning som omfattar rätt datum, och skilj ett ännu gammalt rapportvärde från ett saknat dagsvärde. En person- eller semesterimport behöver följas upp på rätt medarbetare och anställning, bland annat via sidan Personuppgifter.
Om anropet avvisas behöver ni följa felbeskrivningen till den uppgift som orsakade felet. Kontrollera datainnehåll, behörighet eller extern identifierare beroende på vad svaret visar. För SD Worx XML ska ni även kontrollera vilka giltiga poster som redan sparats trots HTTP 400. Rätta orsaken och planera en omkörning först när ni vet hur redan sparade uppgifter ska hanteras; jämför därefter både svaret och resultatet i Timeplan innan fler uppgifter skickas.

Avslutning

Kontrollera resultatet

Förväntat resultat

Integrationen är redo för återkommande användning när ett dokumenterat test har visat rätt behörighet, korrekt format och rätt ändring i Timeplan. Dokumentera även hur ni upptäcker och hanterar misslyckade eller dubbla leveranser.

Hjälp

Vanliga frågor

Kan samma behörighet användas för alla API-importer?

Nej. Varje anrop har egna krav på autentisering och åtkomst. Kontrollera den aktuella API-dokumentationen för den valda funktionen innan ni sätter upp integrationen.