Teknisk vejledning for Regnskab 2.0 - System til system-løsning: XBRL Webservice Klient Eksempel - Java

Beskrivelsen tager udgangspunkt i et eksempel på en webservice klient, der derved kan anvendes som udgangspunkt/inspiration.

Dokumentet beskriver dels generelle forhold omkring denne udvikling og dernæst specifikke forhold om udvikling i Java.

Ændringer til version 3.7 af dokumentet:

• Fejlkode 75 ang. Grønland udgår som følge af at indberetning for Grønlandske virksomheder bliver muligt

Ændringer til version 3.8 af dokumentet:

• Fejl i URL til hentning af testcertifikater rettet
• Afsnit om testdata tilrettet med information om hvor de kan hentes
• Tilføjet information om ændringer til TLS og kryptering. Da Erhvervsstyrelsen ikke længere tillader TLS 1.0 og 1.1 eller kryptering med 128 bit, er der krav om  visse minimumsversioner af Java. Det angivne afspejler de versioner vi har testet med.

Der er i denne beskrivelse anvendt følgende udviklingsværktøjer:

Java:

• Eclipse version 3.5
• OpenJDK 1.7.0_191 eller OpenJDK 1.8.0_152
• OpenOCES 1.8.0 ( www.openoces.org/opensign/download.html )

For at kunne anvende den integrerede XBRL løsning er det nødvendigt at have certifikater til rådighed, dels for at kunne anvende disse til signering af det indsendte XBRL regnskab, og dels for at kunne indgå i SSL kommunikation med webservicen.

Løsningen anvender de fælles offentlige OCES certifikater til virksomheder. Læs mere om anskaffelse af certifikater og digitale signaturer på: 

https://service.nemid.nu/dkda/bestil_nemid/bestil_offentlig_digital_signatur_til_dit_nemid/index.html?execution=e1s1

Testcertifikater kan hentes på:

https://www.nets.eu/dk-da/kundeservice/nemidtjenesteudbyder/ NemID-tjenesteudbyderpakken/Pages/OCES-II-certifikat-eksempler.aspx.

Kaldet af webservices foregår som en HTTP POST mod webservicens URL med et XML dokument og et PDF dokument afhægig af modtager, hvor argumenterne til webservicen er pakket ind i en SOAP envelope struktur.

Da det kan være vanskeligt at arbejde direkte med denne XML/SOAP struktur, indeholder de fleste udviklingsværktøjer en kodegenerering, der på baggrund af webservicens publicerede WSDL, kan generere klasser der gør det nemmere, dels at opbygge argument strukturen, og dels at udføre selve kaldet med  argumenterne til webservicen.

Fælles for disse kodegenereringsværktøjer er, at de skal have en URL til WSDL’en for den publicerede webservice.

For XBRL webservicen er URL’en til WSDL’en

http://erst<env>.virk.dk/ri/s2s/RegisterXbrlEksternWS?wsdl eller

https://erst<env>.virk.dk/ri/s2s/RegisterXbrlEksternWS?wsdl hvor <env> er hhv. dev, test eller preprod.

URL’en til prod WSDL’en er: https://erst.virk.dk/ri/s2s/RegisterXbrlEksternWS?wsdl

Eksempel klienterne har følgende struktur:

En simpel grænseflade til at prompte brugeren for de nødvendige data der skal anvendes som argumenter til kaldet af webservicen. Disse nødvendige data er:

• Et XBRL regnskab
• Regnskabet som PDF (for destination ERST).
• Afsender certifikat i form af PKCS#12 fil inkl. password til generering af digitale signaturer for XBRL dokumentet.
• Destination for data – Erhvervsstyrelsen (ERST), Danmarks Statistik (DST), og SKAT (SKAT)

En angivelse af om transporten skal foregå via HTTP eller HTTPS. En egentlig produktions implementering vil altid anvende HTTPS til kaldet af webservicen, men i eksempel klienterne kan man vælge begge former for transport.

• Valg af webservice der kaldes – der kan kaldes webservice lokalt eller på preprod miljøet (med mindre man er på styrelsens eget netværk hvor dev og test også er tilgængelige..

2.1.1 En klasse til indpakning af de indsamlede argumenter.

En klasse der anvender de genererede klasser til at opbygge den nødvendige argument struktur og derefter kalder webservicen med argument strukturen via en genereret webservice stub.

Når der skal laves en produktionsklar implementering, der anvender webservicen, skal denne naturligvis anvende produktionsversionen af webservicen.

URL’en for produktionsversionen er:

https://erst.virk.dk/ri/s2s/RegisterXbrlEksternWS

2.1.2 Klasser til generering af digitale signaturer.

Webservicens API kræver, at XBRL regnskabet pakkes ind i et XML dokument der er signeret med afsenderens certifikat, jf. XML Digitale Signaturer ( www.w3.org/TR/xmldsigcore ).

Den digitale signatur der skal medsendes, er en OpenOCES ( www.openoces.org ) signatur med namespace “http://www.openoces.org/2006/07/signature#”.

Der er i eksempel-klienten inkluderet klasser, der sikrer at der genereres en sådan signatur. Dette er uddybet under beskrivelsen af klienten.
I det efterfølgende gennemgås Java klienten.

Denne sektion beskriver hvorledes Java Eksempel Klienten kan anvendes og hvordan den er lavet.

Klasse navne etc. refererer til specifikke klasser, der kan findes i zip filen der indeholder Java Eksempel Klienten

Denne zip fil indeholder et Eclipse projekt, der kan importeres til et lokalt Eclipse workspace.

Java eksempel klienten installeres og køres ved at

• Pakke zip filen "s2s_xbrl_eksempel_java_klient_Maj2019.zip" ud i en passende folder
• Afvikle filen run_klient.bat (windows) eller run_klient.sh (MacOS/Linux).

Testfiler kan hentes på følgende steder

• XBRL regnskaber kan downloades via https://datacvr.virk.dk/data/ vi kan dog ikke garantere at alle CVR numre er tilgængelige i preprodution. Desuden kan man modtage fejlbeskeden at der allerede er registreret et regnskab for dette CVR nummer og periode hvis andre tester på dette CVR nummer.
• regnskabets pdf (dette er blot en tilfældig pdf fil som ikke er password-beskyttet)
• Testcertifikat kan downloades fra Nets, jævnfør afsnittet ”Værktøjer”.

Først oprettes et nyt Java projekt i Eclipse. Vælg derefter projektet, højreklik og vælg ”New →Other ...” for at vælge den rigtige wizard.

Vælg ”Web Service Client” og tryk ”Next >”

Dette vil bringe en dialog hvori webservicen skal vælges

Vælg ”Ok” for at komme tilbage til den forrige dialog, nu med webservicen valgt:

Træk i ”slideren” så man blot opretter klienten (Develop Client) og klik ”Finish”. Dette vil generere stubs og hjælpeklasser til at kalde webservicen.
 

Java implementeringen anvender funktionaliteten fra OpenOCES – OpenSign til at generere det Digitalt Signerede XML dokument i OpenOCES formatet.

De nødvendige klasser findes ikke som en selvstændig jar fil der kan downloades, men findes i stedet som en del af de plugin klasser der er tiltænkt anvendelse ved brug af OpenSign appletten.

For at lette pakningen af Java eksempel klienten, er de nødvendige klasser samlet og pakket sammen i en openoces-1.8.0.jar fil.

Proceduren i signatur genereringen er følgende:

Opret en "Pkcs12CertificateHandler" på baggrund af den valgte PKCS#12 fil samt det tilhørende password

Modificer CallBackHandleren på den oprettede "Pkcs12CertificateHandler" – dette er nødvendigt, da den normale "CallBackHandler" er lavet til at få password’et via en bruger interaktion – hvilket ikke sker her.

Generer det signerede XML dokument via metoden "SignatureGenerator.sign" – denne metode returnerer en Enveloping signatur, dvs. at det signerede dokument er indeholdt i signaturen.

XML prologen fjernes og den resterende XML Signatur er nu klar til at blive brugt som argument til webservicen.
 

Hvert kald til webservicen returnerer en status kode, tekst og evt. detaljer, der beskriver resultatet af behandlingen af det foretagne kald.

Kode 0 betyder OK, øvrige koder er fejlkoder. Ved kode 0 kan tekst og detaljer indeholder advis.

Siden version 3.2 af dette dokument blev udsendt, er den tekniske platform for webservicen blevet opdateret og en del af fejlkoderne er ikke længere relevante. Disse er derfor fjernet fra oversigten.

Bemærk at fejlkode 73 tidligere fejlagtigt var angivet som “CVR-nummer ikke fundet”.

Fejlkode 75 er tilføjet som følge af overgangen fra Grønlandske registreringsnumre til CVR numre.

Erhvervsstyrelsen indfører fra 23/8 2016 et nyt niveau i sin modtagekontrol kaldet 'Advis'. En advis adskiller sig fra en fejl ved at indberetter har mulighed for at fortsætte indberetningen efter at have accepteret den.

Fremover vil alle indberetninger i system-til-system som har fået en advis få et svar tilbage indeholdende en ”token”. Såfremt brugeren vælger at indberette trods advis’en da gentages indberetningen, sammen med den modtage token.

Token kan kun anvendes hvis der er tale om en indberetning der er identisk med den indberetning der adstedkom advis’en. Tilsvarende løsningen indarbejdes i styrelsens løsninger på virk.dk.

6.1.1 Skal eksisterende løsninger lave deres kode om til at bruge en ny service?

Nej, Erhvervsstyrelsen har haft som mål at bevare den eksisterende service, derfor er der kun tale om et ekstra valgfrit felt i det der sendes frem og tilbage. Indtil en indberetninger får en advis, vil der ikke kunne mærkes forskel.

6.1.2 En ny opdateret WSDL

Til formålet er der tilføjet en linje i WSDL’en; i henholdsvist registerXbrlEkstern og registerXbrlEksternResponse og begge ser sådan her ud:

<xs:element minOccurs="0" name="token" type="xs:string" />

Det nye element er et token; en streng som løsningen sender til dig og som du kan sende tilbage. Men den behøver ikke at være der.

6.1.3 Kodeeksempel

Det efterfølgende kodeeksempel tager udgangspunkt i den eksisterende eksempel-klient til Java, hvor vi har brugt wsdl2java til at lave en java-klasse ud af vores WSDL. Derfra kan man finde sit token hvis der er blevet sendt et med tilbage:

RegisterXbrlEksternWS stub = stubLocator.getRegisterXbrlEksternWSPort();
WsReturnRegister returnStatus;

returnStatus = stub.registerXbrlEkstern(registerXbrlInput.getSignedXbrl(), registerXbrlInput.getPdf(),

String result = invocationTime+
"Code: "+returnStatus.getStatusCode()+
"\nText: "+returnStatus.getStatusText()+
"\nDetail:\n"+returnStatus.getStatusDetail() + skatKvitMsg +
"\nToken: " + returnStatus.getToken() +
"\nSagsnummer: " + returnStatus.getUniqueReportIdentifier();

Tilsvarende hvis man vil acceptere sin advis, så skal token bare tilføjes til det indsendte:

// Saml input
RegisterXBRLInput input = new RegisterXBRLInput();
input.setSendDst(dstBox.isSelected() ? "Y" : "N");
input.setSendEogS(eogsBox.isSelected() ? "Y" : "N");
input.setSendSkat(skatBox.isSelected() ? "Y" : "N");
input.setPdf(pdf);
input.setSignedXbrl(xmlDSigSender);
input.setToken(token.getText());

Da det ikke er muligt at omgøre og berigtige regnskaber via via System-til-system servicen skal udviklere og testere som anvender klienten være opmærksom på at når der er indberettet korrekt på et CVR-nummer for en periode vil det ikke være muligt at indberette igen på samme CVR-nummer og regnskabsperiode.

Da Erhvervsstyrelsen anvender preproduktions-miljøet til forskellige andre tests af systemet kan der forekomme løbende ændringer i testdata.