XBRL Webservice Klient Eksempel Java og.net Erhvervsstyrelsen Version 3.3
Indhold Indledning... 3 Generering af webservice stubs... 4 Java Eksempel Klient... 6.Net Eksempel Klient... 11 Statusbeskeder fra webservicen... 15 Appendix: Advis håndtering i Erhvervsstyrelsens System-til-system service... 16
Indledning Nærværende dokument beskriver hvorledes man kan udvikle en applikation der anvender den publicerede webservice til at aflevere XBRL regnskaber. 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 hhv. udvikling i Java og.net. Værktøjer Der er i denne beskrivelse anvendt følgende udviklingsværktøjer Java.Net Eclipse version 3.5 JDK 1.6 OpenOCES 1.8.0 (www.openoces.org/opensign/download.html) Microsoft Visual C# 2010 Express Microsoft.NET Framework 4 DanID signatursoftware (https://www.netsdanid.dk/produkter/nemid_medarbejdersignatur/support/hent_nemid_csp/) Anskaffelse af nødvendige certifikater 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å http://virk.dk/digital_signatur. Testcertifikater kan hentes på https://www.netsdanid.dk/produkter/for_tjenesteudbydere/nemid_tjenesteudbyder/nemid_tjenesteudbyder_support/t estcertifikater/.
Generering af webservice stubs Kaldet af webservices foregår som en HTTP POST mod webservicens URL med et XML dokument og et PDF dokument afh 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://arch<env>.service.eogs.dk/webservice_xbrl/registerxbrleksternws?wsdl eller https://arch<env>.service.eogs.dk/webservice_xbrl/registerxbrleksternws?wsdl hvor <env> er hhv. dev, test, preprod eller prod. Generel struktur for eksempel klient 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å enten dev, test eller preprod miljøet. 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://archprod.service.eogs.dk/webservice_xbrl/registerxbrleksternws. 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 de to eksempel klienter inkluderet klasser, der sikrer at der genereres en sådan signatur. Dette er uddybet under beskrivelsen af de to eksempel klienter. I det efterfølgende gennemgås hhv. Java og.net eksempel klienterne.
Java Eksempel Klient 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. Installation og kørsel af eksempel klient Java eksempel klienten installeres og køres ved at Pakke zip filen XBRL_Eksempel_Klient_Java.zip ud i en passende folder Afvikle filen run_klient.bat (windows) eller run_klient.sh (MacOS/Linux). Der findes test filer i folderen testfiler xbrl eksempel i testxbrl.xml husk at ændre CVR nummer og perioden i testfilen ved gentagen brug. Ellers vil man modtage fejlbeskeden at der allerede er registreret et regnskab for dette CVR nummer og periode. regnskabets pdf i testpdf.pdf (dette er blot en tilfældig pdf fil) PKCS#12 certifikat fil i MOCES_gyldig.p12 med password Test1234 Generering af Webservice stub og klasser 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 Browse... og i den fremkomne dialog, indtast placeringen af webservicens WSDL.
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.
Følgende klasser vil blive genereret: Kald af webservice RegisterXBRLInvoker Klassen eksempel.registerxbrlinvoker foretager kaldet til webservicen, ved hjælp af de genererede klasser. Følgende detaljer kan fremhæves: Denne klasse modtager et argument der angiver om webservicen skal kaldes via http eller https. Dette påvirker justeringen af endpoint til at anvende hhv. http eller https. Ved hjælp af de generede klasser opbygges argument strukturen til kaldet af webservicen samt modtages resultatet af kaldet til webservicen. Brugergrænseflade Klassen eksempel.registerxbrlfront indeholder en simpel brugergræseflade der prompter brugeren for de nødvendige data, samler dem sammen og kalder metoden registerxbrl i eksempel.registerxbrlinvoker.
Generering af Signeret XML dokument 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. Procedureren 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.
.Net Eksempel Klient Denne sektion beskriver hvorledes.net Eksempel Klienten kan anvendes og hvordan den er lavet. Klasse navne etc. refererer til specifikke klasser der kan findes i zip filen der indeholder.net Eksempel Klienten. Denne zip fil indeholder et Visual C# 2010 projekt der kan importeres i Visual Studio. Installation og kørsel af Eksempel Klienten.Net Eksempel Klienten installeres og køres ved at Pakke zip filen XBRL_Eksempel_Klient_Net.zip ud i en passende folder. Navigere til folderen publish og kør programmet setup.exe. Dette vil installere.net eksempel klienten på maskinen inkl..net framework 4.0 (denne del kræver en genstart af maskinen). Da applikationen ikke er signeret med en godkendt nøgle, vil den advare omkring dette, og i denne dialog trykkes Install Hvis.Net Framework ikke findes på maskinen vil det blive installeret og kræve en genstart. Når XBRL klienten er installeret, vil den starte og man kan derefter anvende den. Den kan også startes fra Start menuen: Start Programmer E&S XBRL_Eksempel_Klient Der findes test filer i folderen testfiler xbrl eksempel i testxbrl.xml husk at ændre CVR nummer og perioden i testfilen ved gentagen brug regnskabets pdf i testpdf.pdf (dette er blot en tilfældig pdf fil) PKCS#12 certifikat fil i MOCES_gyldig.p12 med password Test1234 brug af certifikatet kræver at det er importeret i Windows, se nedenfor..net eksempel klienten fjernes fra maskinen ved at gå ind i Kontrolpanel Tilføj eller fjern programmer og fjerne XBRL_Eksempel_Klient. Import af certifikat Brug af et OCES certifikat forudsætter at dets CSP er installeret i Windows, den kan hentes fra https://www.nets-danid.dk/produkter/nemid_medarbejdersignatur/support/hent_nemid_csp/. Derefter skal certifikatet importeres ved at dobbeltklikke på certifikatfilen (MOCES_gyldig.p12),
således at også det udstedende CA certifikat bliver importeret og kan anvendes af eksempel klienten. Generering af Webservice stub og klasser i nyt projekt Såfremt man ønsker at starte forfra med implementering af en klient starter man med at generere klasser ud fra webservicens WSDL. Først oprettes et nyt projekt i Visual C# 2010. Vælg derefter Project Add Service Reference.... Dette vil bringe en dialog hvori webservicen skal vælges. Indtast placeringen af webservicens WSDL og tryk Go. Vælg Ok og stubs og hjælpeklasser til at kalde webservicen vil blive genereret. Følgende klasser vil blive genereret:
Eksisterende projekt Projektet XBRL_Reference_Client åbnes i Visual C# 2010 Express. Projektet indeholder klasser genereret ud fra webservicens WSDL, som beskrevet ovenfor, samt håndkodede klasser. Kald af webservice StoreXBRLInvoker Klassen XBRL_Reference_Client.StoreXBRLInvoker foretager kaldet til webservicen, ved hjælp af de genererede klasser. Følgende detaljer kan fremhæves: Denne klasse modtager et argument der angiver om webservicen skal kaldes via http eller https. Dette påvirker justeringen af endpoint (beskrevet ovenfor) til at anvende hhv. http eller https. Ved hjælp af de genererede klasser i XBRL_Example_Client.ServiceReference3 opbygges argument strukturen til kaldet af webservicen samt modtages resultatet af kaldet til webservicen. Brugergrænseflade Klassen XBRL_Reference_Client.StoreXBRLFront indeholder en simpel brugergrænseflade der prompter brugeren for de nødvendige data, samler dem sammen og kalder metoden storexbrl i XBRL_Reference_Client.StoreXBRLInvoker. Certifikatet findes ved at vælge mellem certifikater i brugerens certifkat store. Hvis der angives et password anvendes dette så længe der ikke vælges nyt certifikat. Hvis der ikke angives et password anmodes der om det i en DanID dialog box.
Generering af Digital Signatur Der findes i skrivende stund ikke nogen.net implementering af OpenOCES signatur genereringen. For at sikre at der i.net eksempel klienten bliver genereret matchende XML Signaturer, har det derfor været nødvendigt at portere dele af OpenOCES-OpenSign funktionaliteten til en.net klasse. Denne portering er i klassen XBRL_Reference_Client.OpenSignSignatureGenerator, der er opbygget på samme måde som den tilsvarende funktionalitet i Java implementeringen, så den genererer en OpenSign kompatibel XML Digital Signatur via passende streng operationer kombineret med kald til standard certifikat- og krypterings-funktionalitet i.net. Signaturen genereres ved at kalde metoden OpenSignSignatureGenerator.Sign med dokumentet der skal signeres og med X509 certifikatet der skal bruges til signeringen samt dets private nøgle. Metoden returnerer en enveloping XML Signatur der derefter kan anvendes som argument til kaldet af webservicen.
Statusbeskeder fra 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. kode tekst 10 XBRL dokumentet kan ikke valideres 23 XBRL dokumentet opfylder ikke Erhvervsstyrelsens krav 24 XBRL dokumentet er valideret med Advis 30 Årsrapportens PDF dokument kan ikke valideres 40 Det signerede XML dokuments signatur kan ikke valideres 41 Certifikatet der har signeret XML dokumentet er ikke validt 43 Det signerede XML dokument kan ikke valideres 44 Der kan kun anvendes medarbejder- eller virksomhedscertifikat ved indberetning til SKAT 50 Der er allerede registreret et regnskab for dette CVR nummer i denne periode - der kan ikke 51 Der skal angives netop een destination 55 XBRL dokumentet til Erhvervsstyrelsen skal være en Årsrapport eller Likvidationsregnskab 56 XBRL dokumentet til Danmarks Statistik skal være en Regnskabsstatistik 57 XBRL dokumentet til SKAT skal være en Selskabsselvangivelse 58 Mangler registerxbrlekstern i SOAP 59 PDF dokumentet mangler 73 Det er pt. ikke muligt at indberette til Danmarks Statistik 98 Systemet er optaget - prøv venligst senere 99 Der er opstået en fejl - kontakt venligst Erhvervs- og Selskabsstyrelsen
Appendix: Advis håndtering i Erhvervsstyrelsens System-til-system service 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. 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. 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. 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());