Implementeringsvejledning for B2B webservices

Hvis du ønsker at bruge B2B webservices, så kan du finde info på denne side.

Implementeringsvejledningen forklarer, hvordan virksomheder kan integrere egne systemer med EMCS via business-to-business (B2B) webservices. Integrationen til Skattestyrelsen gennem B2B webservices er rettet mod de virksomheder, som medvirker i mange forsendelser enten som vareafsender eller varemodtager eller i begge roller.

Vejledningen beskriver, hvordan de B2B webservices, som EMCS stiller til rådighed, skal anvendes. Implementeringsvejledningen beskriver hvilke B2B webservices der findes, i hvilke scenarier disse skal anvendes og hvordan de kaldes rent teknisk.

Målgruppe

Implementeringsvejledningens indhold henvender sig primært til en læser med en IT baggrund, som minimum har et overordnet kendskab til, hvordan webservices fungerer. Viden omkring de lovmæssige krav og procedurer, der findes omkring afsendelse og modtagelse af punktafgiftspligtige varer, er også en fordel.

Introduktion til vejledningen

EMCS kan tilgås via den tilgængelige web portal, men også via såkaldte business-to-business (B2B) webservices. Disse B2B webservices giver en virksomhed muligheden for at integrere deres nuværende it-systemer direkte til EMCS. Denne integration kan være en fordel for en virksomhed, som eksporterer og/eller importerer en betydelig mængde punktafgiftspligtige varer inden for EU, da data kan sendes direkte mellem virksomhedens IT-system og EMCS. Dette åbner muligheden for at kunne se information fra EMCS i virksomhedens IT-system og at tilføje funktionalitet til virksomhedens IT-system til at kunne sende information omkring en forsendelse direkte til EMCS.

Nuværende version 3.19 er gældende fra 13. februar 2023. Ny version 3.20 er gældende fra 13. februar 2024 Se ændringsloggen her.

Hvis du bruger B2B-løsningen, skal du udskifte de nuværende skemaer til de nye skemaer, så du kan sende og modtage beskeder i det nye format fra den 13. februar 2024. 

De nye B2B-skemaer ligger allerede klar, og du finder dem på github.com:

• Nye skemaer til B2B
• Nuværende skemaer til B2B
• Sammenligning af de nuværende skemaer og de nye skemaer (de røde linjer bliver grønne i de nye skemaer)
• Opdateret testdata

Nuværende version 3.19 er gældende fra 13. februar 2023. Ny version 3.20 er gældende fra 13. februar 2024 Se ændringsloggen her.

 

EU har defineret et antal funktionelle beskeder kaldt "Information Exchange" (IE) som beskriver de data som udveksles med EMCS. Hver IE-besked har fået tildelt et nummer. Fx når en virksomhed ønsker at sende data for et udkast til et ledsagedokument, skal den indsende den information som svarer til den funktionelle besked med navnet IE815. Hver IE-beskeds struktur og indhold er defineret i en XSD fil. Dataindholdet som er specificeret i de forskellige XSD filer er de data som bliver udvekslet i de forskellige B2B webservices. Fx når en virksomhed ønsker at oprette et udkast til et ledsagedokument, så skal den kalde B2B webservicen med navnet OIOLedsageDokumentOpret, og de data OIOLedsageDokumentOpret forventer at modtage, skal overholde det den funktionelle besked IE815 specificerer. Indholdet af SOAP-beskeden sendes til B2B webservicen.

Scenariebeskrivelser (PDF) Dokumentet beskriver i hvilke scenarier de forskellige B2B webservices skal kaldes samt hvilke IE beskeder de forventer at modtage eller de anvender som svar. Felter som ligger ud over IE beskederne er også forklaret i dette dokument. 

Indholdet af de forskellige funktionelle beskeder og hvordan disse er bygget op er beskrevet i de følgende tre dokumenter:

• Beskrivelse af struktur og design (engelsk) Dette dokument indeholder generel information omkring hvordan de funktionelle beskeder er bygget op samt hvilke krav der er til indholdet af beskederne. Indholdet er på engelsk, da det stammer fra EU’s dokumentation.
• Oversigt over beskedstruktur Dette regneark indeholder alle de funktionelle beskeder og giver en oversigt over alle de felter som hvert enkel besked indeholder. For hvert felt er der også en tilhørende dansk oversættelse samt en beskrivelse af feltets indhold.
• Tekniske kodeliste og Forretningskodeliste Kodelisterne kan slås op i disse to dokumenter. I oversigten over beskedstruktur er der en kolonne med navnet CODELIST. De felter, som har et nummer stående i den kolonne, kan kun indeholde et prædefineret sæt af værdier. Nummeret refererer til en såkaldt kodeliste, som indeholder listen af de prædefinerede værdier. Nummeret kan enten starte med TC eller BC. Hvis nummeret starter med TC, kan værdien findes i dokumentet med de tekniske kodelister. Hvis nummeret starter med BC skal nummeret først slås op i en tabel i den tekniske kodeliste, hvor navnet på kodelisten kan findes. Navnet på kodelisten kan så slås op i dokumentet med forretnings kodelister. Fx hvis der står "BC66", så kan der ved at slå op i tabellen på side fem i dokumentet med de tekniske kodelister ses, at "BC66" svarer til "Excise Product Categories". Derefter kan man slå "Excise Product Categories" op i dokumentet med forrentningskodelisterne.

B2B-webservicen er tilgængelig i to miljøer. Det ene er et testmiljø hvor kald af B2B webservices kan foretages uden at dette resulterer i, at reelle ledsagedokumenter bliver oprettet. Det andet er produktionsmiljøet, der indeholder de B2B webservices som virksomhedens endelig system skal anvende.  

Den tekniske vejleding består af følgende referencer, der alle henviser til dokumentation og kildekode, der udstilles på Skattestyrelsens GitHub-konto:

 emcs-b2b-ws som indeholder:

• WSDL-filer - Dette afsnit indeholder WSDL filer for de 23 web services
• XSD-filer - Alle de nødvendige XSD filer for at kunne forme korrekte IE beskeder. Der findes én XSD fil per IE besked
• Fejlkoder - De fejl som man kan modtage i HovedOplysningSvar
• Beskrivelse af sikkerhedsregler for anvendelse af services, herunder gyldigt SOAP request og response
• Server-certifikater for test- og produktionssystemet
• Information om test- og produktionscertifikater.

emcs-b2b-ws-test-data som indeholder information om det testdata, som er tilgængeligt og kan anvendes til test.

Skattestyrelsen har udviklet denne sample klient, som viser hvorledes det kan gøres i Java (klienten vises kun som eksempel, og der ydes ikke support på den):

Java

For at kunne køre klienten er det nødvendigt med en "Systems Integrator"-pakke, som udleveres af Toldstyrelsens Servicedesk.