Importspecifikation för XML-fil

📄 Om specifikationen

Uppgift	Värde
Version	1.3 (april 2024)
Schema	https://api.dicomkontera.se/Schemas/Dicom.Expense.Import.1.3.xsd
Teckenkodning	UTF-8
Datum	ÅÅÅÅ-MM-DD, till exempel 2015-08-14
Tid	hh:mm:ss, till exempel 06:01:23
Datum och tid	ÅÅÅÅ-MM-DDThh:mm:ss, till exempel 2015-08-14T06:01:23

👉 Gäller: administratörer och utvecklare som bygger en automatisk import till Expense. Användaruppgifter och token får ni av Expense, se sist i artikeln.

🧩 Filens uppbyggnad

Filen består av ett filhuvud och sedan de objekt som ska importeras.

Filhuvud

Tagg	Innehåll
FileHeader fileId	Ett unikt id per fil, till exempel en GUID
Token	Hemlig token som ni får av Expense
DeliveryId	Unikt id för företaget, till exempel momsregistreringsnummer
CompanyName	Företagets namn
SchemaVersion	dicom_expense_1.3
DateGenerated	När filen skapades
Sender senderId	Avsändarens id och namn

🔑 Grundregler

Synkroniseringsnycklar

Alla objekt utom relationer behöver en unik nyckel, till exempel en GUID eller primärnyckeln i ert system. Nyckeln används för att hitta rätt objekt vid nästa import.

✅ Behåll samma nyckel vid varje import
⚠️ Ändras nyckeln skapas ett nytt objekt i Expense
⚠️ Återanvänd aldrig en nyckel för ett annat objekt
🚫 Använd inte e-postadress som nyckel, eftersom den kan återanvändas av någon annan längre fram

👉 Nycklarna i exemplen nedan, till exempel P23, ska bytas mot era egna.

fullSync

Värde	Vad händer
false	Bara objekten i filen uppdateras
true	Tidigare importerade objekt som inte finns med i filen inaktiveras

Objekt som har skapats manuellt i Expense påverkas aldrig. Undantaget är personer: Expense försöker matcha en person som inte är synkroniserad via e-postadressen.

Specialtecken

Lägg text som kan innehålla tecken som mindre än, större än och & i en CDATA-tagg:

📊 Objekt som kan importeras

Interna konton

internalAccountPrimaryKey är den numeriska nyckeln för det interna kontot i Expense, till exempel Projekt eller Avdelning. internalAccountDataId är er egen unika nyckel för varje värde.

Personroller

personRoleId är er egen unika nyckel för varje personroll.

Personer

personId är er egen unika nyckel för varje person. Finns ingen person med det id:t letar Expense efter en osynkroniserad person med samma e-postadress innan en ny skapas. EmployeeNumber, EmployeeCode och SsoTokens är valfria.

SsoTokens används för enkel inloggning (SAML). Attributet idp tillhandahålls av Acubiz AB och nameId är användarens id i SAML-svaret. Sätt state="inactive" för att stänga av en token.

Kontoplan

number är kontonumret. vat är momskoden och är valfri. Utelämnas den väljs momsen manuellt, och en momskod som inte finns skapas. Taggen lägger till eller uppdaterar konton men tar aldrig bort några.

Arbetstider (bara med modulen restidsersättning)

Anger arbetstiden per veckodag för en person från och med fromDate. toDate används bara för tillfälliga scheman. recurrenceFactor och recurrenceOffset används för att växla tider mellan veckor. Taggen lägger till eller uppdaterar men tar aldrig bort.

Lön (bara med modulen restidsersättning)

Anger personens lön från och med fromDate. amount är hela beloppet inklusive förmåner och bonus. salaryType är monthly eller hourly. Taggen lägger till eller uppdaterar men tar aldrig bort.

🔗 Relationer

Alla relationer ligger i taggen Relations:

Relation	Tagg	Kommentar
Internt konto – personroll	InternalAccountData_PersonRole	–
Kontoplan – personroll	ChartOfAccount_PersonRole	Saknas kontot skapas det med namnet (Okänt)
Person – personroll	Person_PersonRole	–
Kontoplan – person	ChartOfAccount_Person	Saknas kontot skapas det med namnet (Okänt)
Internt konto – person	InternalAccountData_Person	–
Person – attestant	Person_AttestPerson	Attestbehörighet läggs till automatiskt om den saknas
Person – granskare	Person_Reviewer	Granskarbehörighet läggs till automatiskt om den saknas
Person – standardvärde för internt konto	Person_InternalAccountDataDefault	locked="false" ger ett förslag som kan ändras, locked="true" låser värdet

📤 Ladda upp filen

Skicka filen med en vanlig POST till https://api.dicomkontera.se/File/Import.
Autentisera med HTTP Basic Authentication.
Döp gärna filen till företagsnamn.xml. En fil som heter test.txt ignoreras och kan användas för att testa anslutningen.

Exempel med cURL:

⚠️ Använd inte flaggan -k, som gör att cURL ignorerar certifikatfel.

🔐 Användaruppgifter och inställningar

För att få användarnamn, lösenord och token, eller för att sätta upp importen, kontakta Expense Support.

📋 Versionshistorik

Version	Ändring
1.0	Första versionen
1.1	Datum och tid i ISO 8601. Nya taggar: Person_InternalAccountDataDefault, WorkingHours, AllowableAmounts, ChartOfAccounts, Person_Reviewer
1.2	Ny tagg: SsoToken
1.3	Nya personfält: AddressLine1, AddressLine2, PostalCode, City, Country och SSN

❓ Vanliga frågor (FAQ)

Vad händer om vi ändrar en nyckel?
Expense ser det som ett nytt objekt och skapar en ny post. Behåll därför samma nyckel vid varje import.

Tas konton bort om de saknas i filen?
Nej. Kontoplan, arbetstider och lön läggs bara till eller uppdateras. För objekt med fullSync="true" inaktiveras tidigare importerade objekt som saknas i filen.

Påverkas sådant vi har lagt upp manuellt i Expense?
Nej, bara objekt som tidigare har importerats. Undantaget är personer, som kan matchas via e-postadressen.

Hur testar vi anslutningen?
Ladda upp en fil som heter test.txt. Den ignoreras av importen.

✅ Sammanfattning

📄 XML-filen är kodad i UTF-8 och följer schemat version 1.3
🔑 Varje objekt behöver en unik nyckel som aldrig ändras
🔄 fullSync styr om saknade objekt ska inaktiveras
📤 Filen laddas upp med POST och Basic Authentication