Frågehantering XML-produkter Bolagsverket 1 (15)
2 (15) Ändringslogg Datum Beskrivning 2011-03-08 Skapar ändringslogg i ny version av dokumentet. Infört tre nya produkter för information om kungörelser. 2012-02-29 Tagit bort information om Kungörelser 2013-02-06 Ändrat länk till informationssidan på bolagsverket.se 2013-07-02 Lagt information om nya versioner av dokumentnedladdning 2015-11-05 Ändrat url:n för web serviceanrop i produktion. 2015-12-09 Ändrat url:n för web serviceanrop i test. 2016-02-03 Ändrat tillbaka till den tidigare url:n för web serviceanrop i test 2016-05-19 Lagt till information om servernamn och certifikattyp 2016-06-13 Ändrat url:n för web serviceanrop i test. 2017-01-26 Lagt till information om FirmatecknarFråga
3 (15) ÄNDRINGSLOGG... 2 ALLMÄN FRÅGEHANTERING... 4 Tjänst... 4 Autentisering av anropare... 4 Paketindelning... 5 XMLfrågan... 5 Förklaring till frågescheman... 5 Svaret... 5 Informationshuvud... 5 Väsentliga koder i elementet svarsinformation... 6 Företag... 7 Person... 7 Ärende... 8 Dokumentfråga... 10 Dokumentbeställning... 10 Firmagranskning... 12 Företagsinteckningar... 13 Firmateckning... 14
4 (15) Allmän frågehantering Här följer en allmän beskrivning över hämtning och leverans av xml-paket från Bolagsverket. Tjänst Hämtning av information ur Bolagsverkets register i xml-format sker med hjälp av webserviceanrop. Bolagsverkets publika tjänster har url (test): https://eservice-accept2.bolagsverket.se/services/xmlprodukt och (produktion) https://eservice.bolagsverket.se/services/xmlprodukt Tjänsten tar följande parametrar i anropet: Parameter Typ Kommentar Obligatorisk userid Sträng Av bolagsverket angivet användarnamn Ja certid Sträng Ja xmlfraga Sträng Fråga i xml-format specificerat av tillhörande frågeschema. OBS!! base64-encoded Ja Tjänsten svarar med efterfrågad information i xml-format specificerat av tillhörande produktschema. Mer information om våra XML-paket finns på http://bolagsverket.se/be/sok/xml Autentisering av anropare Autentisering sker med hjälp av klientcertifikat från anropande applikation. Klientcertifikatet skickas med i anropet och med hjälp av certifikatets organisationsnummer och användarnamnet sker kontrollen av anroparens identitet. Den typ av certifikat som skall användas är Sterias serverlegitimation. Servernamn Det vanligaste är att man anger kundens namn i det fältet alternativt så anger man namnet på den server där serverlegitimation kommer att installeras. Bolagsverket använder attributet SERIALNUMBER i fältet Subject som innehåller kundens organisationsnummer som identifierare så att det är viktigast att det innehåller rätt värde. Certifikattyp När det gäller certifikattyp så rekommenderar vi 2048bit.
5 (15) Paketindelning Strukturen av XML-information från bolagsverket är uppdelad i grupper. I nuläget finns nedanstående grupper som anropas med var sin frågexml. Dessa är: Företag Ärende Person Dokumentlista Dokumentbeställning Firmagranskning Företagsinteckningar Firmateckning Under dessa grupper finns ett antal paket med logiskt grupperad information. XMLfrågan Det finns en frågexml för varje grupp. Det betyder att en fråga/begäran till Bolagsverket om ett specifikt paket för ett objekt skall ställas per grupp. Elementets sökvilkor är anpassat till vilken grupp produkten tillhör. Vissa paket ger möjlighet att utföra historiksökningar genom att ange ett ärendenummer i produktfrågan. Företag/personhuvudet visar alltid dock aktuell information. Frågan ska vara validerad att den stämmer enligt schemat med format, antal tecken m.m., innan den ställs mot Bolagsverket. Förklaring till frågescheman Heldragna elementrutor är tvingad information och streckade frivilligt eller används endast i förekommande fall. Exempelvis måste en företagsfråga innehålla en schemaversion, ett informationshuvud och en produkt. Produkten måste anges med namn och minst ett sökbegrepp. Svaret Svaret på en fråga är strukturerat på samma sätt som frågan. Schemat för respektive paket åskådliggör vilket data som måste och som kan finnas. Varje svar levereras med ett likadant informationshuvud som i frågan där en svarsinformation med en kod visar om frågan gått bra eller inte. Även en text kan levereras. Möjliga koder och texter beskrivs i schemat. Enumerationer på möjliga koder och värden finns i schemat i de fall värdet är registerspecifikt. I de fall värdet grundas på en standard såsom t.ex. länskoder eller landskoder mm strävar vi efter att inte binda upp dessa som enumerationer då dessa styrs utifrån fastslagna allmänna standarder. Informationshuvud I informationshuvudet finns möjlighet att ange information om avsändare och annan information som kan behövas för identifiering och loggning. Referens och referens2 i informationshuvudet kan användas för att märka upp frågor för vidaredebitering eller internfakturering.
6 (15) Enumerationer och utförligare information, t.ex. fältlängder och numeriska eller alfanumeriska fält angående frågexml:en finns i schemat och kompletterande dokumentation. Informationshuvudet ser likadant ut oavsett vilken produkt man hanterar Väsentliga koder i elementet svarsinformation Enligt följande: 0 : Lyckat svar 2000 : Formellt felaktig nyckel 2010 : OrganisationsNr formellt fel. 2011 : OrganisationsNr/objektnummer finns ej 2012 : Löpnummer måste anges. 2013 : Öppna ärenden saknas. 2020 : Personnummer formellt felaktigt. 2021 : Personnummer finns ej 2050 : Diarienummer formellt fel. 2030 : IDnr formellt fel 2031 : IDnr felaktigt/saknas 2050 : Diarienummer formellt fel 2051 : Diarienummer finns ej 2052 : Objektnummer saknas 2053 : Timeout 2051 : Ogiltigt sökvärde 2055 : Obligatoriskt sökord 2056 : För många träffar i sökningen 2057 : Bolaget avslutat 2058 : Bolaget saknas 2059 : Personen saknas i bolaget 9999 : Tekniskt fel
XML-utseenden 7 (15) Företag Söknyckeln kan innehålla företagsidentitet, ärendeidentitet, eller firma (används bland för ex. företagssökning). Frågexml för företag Exempel på frågexml <?xml version="1.0" encoding="iso-8859-1"?> <for:foretagsfraga SchemaVersion="1.1" xmlns:for="http://www.bolagsverket.se/schemas/foretagsinformation/foretagsfraga"> <for:informationshuvud> <com:avsandare xmlns:com="http://www.bolagsverket.se/schemas/common">peek-a-boo</com:avsandare> <com:sekvensnummer xmlns:com="http://www.bolagsverket.se/schemas/common">17</com:sekvensnummer> <com:meddelandetyp xmlns:com="http://www.bolagsverket.se/schemas/common">string</com:meddelandetyp> <com:referens xmlns:com="http://www.bolagsverket.se/schemas/common">2</com:referens> <com:meddelandedatumtid xmlns:com="http://www.bolagsverket.se/schemas/common">2009-01- 21T08:25:14.635+01:00</com:MeddelandeDatumTid> <com:sessionsid xmlns:com="http://www.bolagsverket.se/schemas/common">fbbgcndg2e5uwmqrdgsuzin</com:sessionsid> <com:referens2 xmlns:com="http://www.bolagsverket.se/schemas/common">1</com:referens2> </for:informationshuvud><for:produkt version="2.00"> <for:namn>f1grundpaket</for:namn> <for:sokbegrepp> <for:foretagsidentitet> <com:organisationsnummer xmlns:com="http://www.bolagsverket.se/schemas/common">5565535027</com:organisationsnummer> </for:foretagsidentitet> </for:sokbegrepp> </for:produkt> </for:foretagsfraga> Person Söknyckeln kan innehålla personidentitet eller namn (används för ex. personsökning).
Frågexml för person 8 (15) Exempel på frågexml <?xml version="1.0" encoding="iso-8859-1"?> <per:personfraga SchemaVersion="1.1" xmlns:per="http://www.bolagsverket.se/schemas/personinformation/personfraga"><per:informationshuvud> <com:avsandare xmlns:com="http://www.bolagsverket.se/schemas/common">peek-a-boo</com:avsandare> <com:sekvensnummer xmlns:com="http://www.bolagsverket.se/schemas/common">2</com:sekvensnummer> <com:meddelandetyp xmlns:com="http://www.bolagsverket.se/schemas/common">string</com:meddelandetyp> <com:referens xmlns:com="http://www.bolagsverket.se/schemas/common">2</com:referens> <com:meddelandedatumtid xmlns:com="http://www.bolagsverket.se/schemas/common">2009-01- 21T08:27:50.343+01:00</com:MeddelandeDatumTid> <com:sessionsid xmlns:com="http://www.bolagsverket.se/schemas/common">w4v_zmez_icwdjoplnfw100</com:sessionsid> <com:referens2 xmlns:com="http://www.bolagsverket.se/schemas/common">1</com:referens2> </per:informationshuvud><per:produkt version="2.00"> <per:namn>p1grundpaket</per:namn> <per:sokbegrepp> <per:personidentitet> <com:sekel xmlns:com="http://www.bolagsverket.se/schemas/common">19</com:sekel> <com:personnummer xmlns:com="http://www.bolagsverket.se/schemas/common">7209156939</com:personnummer> </per:personidentitet> </per:sokbegrepp> </per:produkt> </per:personfraga> Ärende Söknyckeln kan innehålla företagsidentitet, ärendeidentitet och elektroniskt identitet. Idagsläget kan man inte använda söknycklarna FromDatum eller TomDatum. Förtydligande ärendefråga För att hantera historiska frågor på ett företag används ärendeinformationsprodukten A6. Genom att ange namnet på en företagsprodukt i ärendefrågan kan man få tillbaka en lista av historiska händelser i företaget. I dokumentationen för respektive produkt framgår vilka produkter som man kan ställa historiska frågor. För att få en historisk träfflista med diarienummer och rubriceringar för ex företagsprodukten F11 anges F11ForetradareFirmateckningVakanser under elementet avgränsande produkt i frågan för hämtning av ärendeinformation, produktnamnet skall i det här fallet vara A6_Arendeforteckning. Svaret återkopplas som en lista med diarienummer etc. som behöver hanteras i ett vidare steg där man anger diarienumret som sökvärde för F11FunktionärerFirmateckningVakanser.
9 (15) Fråge-xml för ärende Exempel på frågexml <?xml version="1.0" encoding="iso-8859-1"?> <aren:arendefraga SchemaVersion="1.1" xmlns:aren="http://www.bolagsverket.se/schemas/arendeinformation/arendefraga" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://www.bolagsverket.se/schemas/arendeinformation/arendefraga file:///g:/esamverkansavdelningen/enheten%20f%c3%b6r%20tj%c3%a4nsteutveckling/n%c3%a4ringslivsregistret/xml/schema/arendeinformation/a rendefraga_1.1.xsd"> <aren:informationshuvud> <com:avsandare xmlns:com="http://www.bolagsverket.se/schemas/common">peek-a-boo</com:avsandare> <com:sekvensnummer xmlns:com="http://www.bolagsverket.se/schemas/common">2</com:sekvensnummer> <com:meddelandetyp xmlns:com="http://www.bolagsverket.se/schemas/common">string</com:meddelandetyp> <com:referens xmlns:com="http://www.bolagsverket.se/schemas/common">2</com:referens> <com:meddelandedatumtid xmlns:com="http://www.bolagsverket.se/schemas/common">2009-01- 21T08:29:29.086+01:00</com:MeddelandeDatumTid> <com:sessionsid xmlns:com="http://www.bolagsverket.se/schemas/common">exhijeeikyg-3kpht29qze_</com:sessionsid> <com:referens2 xmlns:com="http://www.bolagsverket.se/schemas/common">1</com:referens2> </aren:informationshuvud> <aren:produkt version="2.00"> <aren:namn>a7arendeinformation</aren:namn> <aren:sokbegrepp> <aren:arendeidentitet artal="2008" idnummer="1"/> </aren:sokbegrepp> </aren:produkt> </aren:arendefraga> Dokument Dokumentbeställning och dokumenthämtning Frågor efter skannade dokument sker i flera steg. Ett normalt flöde för anrop är enligt följande: 1. Hämta dokumentlista 2. Köp ett eller flera dokument 3. Hämta dokument Således blir det i normala fall normalt tre anrop för att hämta ett dokument. Om flera dokument har köpts blir steg 3 utfört för respektive dokument.
10 (15) Dokumentfråga Frågexml för dokumentfråga Exempel på frågexml <?xml version="1.0" encoding="utf-8"?> <Dokumentfraga SchemaVersion="2.01" xmlns="http://www.bolagsverket.se/schemas/dokumentinformation/dokumentfraga_201" xmlns:identitet201="http://www.bolagsverket.se/schemas/common/identitet/identitet_201" xmlns:informationshuvud200="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <informationshuvud200:informationshuvud> <informationshuvud200:avsandare>mfd</informationshuvud200:avsandare> <informationshuvud200:referens>mfd</informationshuvud200:referens> </informationshuvud200:informationshuvud> <Produkt version="2.01"> <Namn>D3Dokumentlista</Namn> <Sokbegrepp> <identitet201:foretagsidentitet bolagsverketsid="string"> <identitet201:organisationsnummer>5560125790</identitet201:organisationsnummer> </identitet201:foretagsidentitet> </Sokbegrepp> </Produkt> </Dokumentfraga> Dokumentbeställning Frågexml för dokumentbeställning version 2.01
11 (15) Exempel på frågexml för scannat dokument (dokumentbeställning version 2.01) <?xml version="1.0" encoding="utf-8"?> <dok:dokumentbestallning SchemaVersion="2.01" xmlns:dok="http://www.bolagsverket.se/schemas/dokumentinformation/dokumentbestallning_201"> <inf:informationshuvud xmlns:inf="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200"> <inf:avsandare>snr</inf:avsandare> <inf:sekvensnummer>tfjx4qfgnlta0sgp0zx3c19:1914</inf:sekvensnummer> <inf:meddelandetyp>fraga</inf:meddelandetyp> <inf:referens>logginsnr</inf:referens> <inf:meddelandedatumtid>2009-01-12t08:30:04.490+01:00</inf:meddelandedatumtid> <inf:referens2/> </inf:informationshuvud> <dok:produkt version="2.01"> <dok:namn>d4dokumentleverans</dok:namn> <dok:dokument> <dok:dokumentid>2832172</dok:dokumentid> </dok:dokument> </dok:produkt> </dok:dokumentbestallning> Exempel på frågexml för registreringsbevis (dokumentbeställning version 2.01) <?xml version="1.0" encoding="utf-8"?> <dok:dokumentbestallning SchemaVersion="2.01" xmlns:dok="http://www.bolagsverket.se/schemas/dokumentinformation/dokumentbestallning_201"> <inf:informationshuvud xmlns:inf="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200"> <inf:avsandare>snr</inf:avsandare> <inf:sekvensnummer>s0dhub3lsn8pkw2mwiyumyp:5</inf:sekvensnummer> <inf:meddelandetyp>fraga</inf:meddelandetyp> <inf:referens>bjs</inf:referens> <inf:meddelandedatumtid>2009-01-16t08:27:56.154+01:00</inf:meddelandedatumtid> <inf:referens2/> </inf:informationshuvud> <dok:produkt version="2.01"> <dok:namn>d4dokumentleverans</dok:namn> <dok:regbevis> <iden:foretagsidentitet xmlns:iden="http://www.bolagsverket.se/schemas/common/identitet/identitet_201"> <iden:organisationsnummer>5565535027</iden:organisationsnummer> </iden:foretagsidentitet> </dok:regbevis> </dok:produkt> </dok:dokumentbestallning> Frågexml för dokumentbeställning version 2.03
Exempel på frågexml för scannat dokument (dokumentbeställning version 2.03) 12 (15) <?xml version="1.0" encoding="utf-8"?> <dok:dokumentbestallning SchemaVersion="2.03" xmlns:dok="http://www.bolagsverket.se/schemas/dokumentinformation/dokumentbestallning_203"> <inf:informationshuvud xmlns:inf="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200"> <inf:avsandare>snr</inf:avsandare> <inf:sekvensnummer>tfjx4qfgnlta0sgp0zx3c19:1914</inf:sekvensnummer> <inf:meddelandetyp>fraga</inf:meddelandetyp> <inf:referens>logginsnr</inf:referens> <inf:meddelandedatumtid>2009-01-12t08:30:04.490+01:00</inf:meddelandedatumtid> <inf:referens2/> </inf:informationshuvud> <dok:produkt version="2.03"> <dok:namn>d4dokumentleverans</dok:namn> <dok:dokument> <dok:dokumentid>7270642</dok:dokumentid> </dok:dokument> <dok:dokument> <dok:dokumentid>7270643</dok:dokumentid> </dok:dokument> </dok:produkt> </dok:dokumentbestallning> Exempel på frågexml för registreringsbevis (dokumentbeställning version 2.03) <?xml version="1.0" encoding="utf-8"?> <dok:dokumentbestallning SchemaVersion="2.03" xmlns:dok="http://www.bolagsverket.se/schemas/dokumentinformation/dokumentbestallning_203"> <inf:informationshuvud xmlns:inf="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200"> <inf:avsandare>snr</inf:avsandare> <inf:sekvensnummer>s0dhub3lsn8pkw2mwiyumyp:5</inf:sekvensnummer> <inf:meddelandetyp>fraga</inf:meddelandetyp> <inf:referens>bjs</inf:referens> <inf:meddelandedatumtid>2009-01-16t08:27:56.154+01:00</inf:meddelandedatumtid> <inf:referens2/> </inf:informationshuvud> <dok:produkt version="2.03"> <dok:namn>d4dokumentleverans</dok:namn> <dok:regbevis> <iden:foretagsidentitet xmlns:iden="http://www.bolagsverket.se/schemas/common/identitet/identitet_201"> <iden:organisationsnummer>5565535027</iden:organisationsnummer> </iden:foretagsidentitet> </dok:regbevis> </dok:produkt> </dok:dokumentbestallning> Firmagranskning Firmagranskningsfrågan ger olika svar beroende på vilken nyckeltyp som anges. De nyckeltyper som kan anges är: OS = Firmagranskning OD = Firmagranskning endast levande. Företag med viss status sorteras bort. OT = Firmagranskning med wilcard. OM = Sökning av sökord OL = Firmagranskning med endast levande och wildcard. VE = Till verksamhetsbeskrivning för viss firma.
Frågexml för firmagranskning 13 (15) Exempel på frågexml <?xml version="1.0" encoding="iso-8859-1"?> <fir:firmagranskningsfraga SchemaVersion="2.00" xmlns:fir="http://www.bolagsverket.se/schemas/firmagranskninginformation/firmagranskningfraga200"> <inf:informationshuvud xmlns:inf="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200"> <inf:avsandare>peek-a-boo</inf:avsandare> <inf:sekvensnummer>1</inf:sekvensnummer> <inf:meddelandetyp>string</inf:meddelandetyp> <inf:referens>2</inf:referens> <inf:meddelandedatumtid>2009-01-21t08:30:38.706+01:00</inf:meddelandedatumtid> <inf:sessionsid>nboudfynxavbux31nbqoa2c</inf:sessionsid> <inf:referens2>1</inf:referens2> </inf:informationshuvud> <fir:produkt version="2.00"> <fir:namn>f33firmagranskning</fir:namn> <fir:granskning> <fir:sokstrang>volvo</fir:sokstrang> <fir:soknyckel>os</fir:soknyckel> </fir:granskning> </fir:produkt> </fir:firmagranskningsfraga> Företagsinteckningar Söknyckeln kan innehålla företagsidentitet, EIDK (unik nyckel för idkarkombination) eller inteckningsnummer.
14 (15) Exempel på frågexml <?xml version="1.0" encoding="iso-8859-1"?> <for:foretagsinteckningarfraga SchemaVersion="2.00" xmlns:for="http://www.bolagsverket.se/schemas/foretagsinteckningsinformation/foretagsinteckningarfraga"> <inf:informationshuvud xmlns:inf="http://www.bolagsverket.se/schemas/common/informationshuvud/informationshuvud_200"> <inf:avsandare>peek-a-boo</inf:avsandare> <inf:sekvensnummer>6</inf:sekvensnummer> <inf:meddelandetyp>string</inf:meddelandetyp> <inf:referens>2</inf:referens> <inf:meddelandedatumtid>2009-01-21t08:31:26.437+01:00</inf:meddelandedatumtid> <inf:sessionsid>t7ktpnssrxxelnclvwztrb6</inf:sessionsid><inf:referens2>1</inf:referens2> </inf:informationshuvud> <for:produkt version="2.00"> <for:namn>f37foretagsinteckningar</for:namn> <for:sokbegrepp> <iden:foretagsidentitet xmlns:iden="http://www.bolagsverket.se/schemas/common/identitet/identitet_202"> <iden:organisationsnummer>5560125790</iden:organisationsnummer> </iden:foretagsidentitet> </for:sokbegrepp> </for:produkt> </for:foretagsinteckningarfraga> Firmateckning Söknyckeln kan innehålla personidentitet kombination personidentitet och företagsidentitet I frågan kan man också ange ett maxantal träffar, gäller då frågan används för sökning på bara personidentitet.
Kontakt Vid frågor gällande avtal mm kontakta forsaljning@bolagsverket.se Vid tekniska frågor kontakta helpdesk@bolagsverket.se 15 (15)