V. 2015.11.18 Version 2.1 UC Web Service Teknisk beskrivning gällande integrerad lösning för UC:s svenska företags/personinformation
Innehåll Inledning... 3 Krav för användning... 3 Säkerhet... 3 Kontakta UC... 3 Beskrivning av UC:s Web Services... 4 Adresser... 4 Dokument... 4 SOAPmeddelandet... 5 Beställning... 6 Påloggningsdata... 7 Beställning av kreditregelverk...10 Svar...11 <body>...11 Status...13 xmlreply...14 htmlreply...14 Exempel på svar...15 Värdeområden för element och attribut...16 <override>...17 Svarstransaktioner/xmlReply...17 Beskrivning av informationsgrupper och termer...17 Sidan 2 av 18
Inledning UC tillhandahåller webbtjänster för att underlätta integrering mellan våra kunders system och vår. Detta dokument beskriver UCs webbtjänst för beställning av kreditupplysningar via Web Services. Idag erbjuder tjänsten beställning av företagsupplysning för svenska företag, företagare, personer, kontroll av namn och adress samt IDnummersökning. Samtliga kreditupplysningar kan beställas tillsammans med kreditregelverk som är en tillvalstjänst. Alla UC:s Web Services är byggda för att vara WSI compliant (www.wsi.org) och är testade från flera olika klientmiljöer, däribland Java och Microsoft dotnet. Alla UC:s Web Services stöder SOAP version 1.1. Krav för användning För att använda UC:s Web Services krävs ett avtal med UC. När du tecknar avtalet får du ett kundnummer och lösenord. Säkerhet Säkerheten för Web Services är HTTPS samt traditionell autentisering med kundnummer och personkod. Om ni ställer högre krav på säkerhet kan VPN erbjudas. Vid behov av andra säkerhetslösningar tag kontakt med UC. Kontakta UC Har du frågor om UC Web Services är du välkommen att kontakta oss via epostadressen kundservice@uc.se. Vid tekniska problem kan du kontakta UC, via telefon 08670 90 00 eller via epostadressen applikationssupport@uc.se Sidan 3 av 18
Beskrivning av UC:s Web Services Följande beställningsgrupper finns för närvarande att beställa via Web Services: companyreport. Företagsupplysning för svenska företag, med eller utan kreditregelverk. Möjlig att beställa med UC:s produkt UC4, UC41, UC410, UC91 med flera. businessreport. Företagareupplysning, med eller utan kreditregelverk. Möjlig att beställa med UC:s produkter UC4, UC410, UC91 med flera. individualreport. Personupplysning, med eller utan kreditregelverk. Möjlig att beställa med UC:s produkt UC3, UC90 med flera. identitycheck. Kontroll av namn och adress. IdentitySeekJur Idnrsökning juridiker. IdentitySeekFys Idnrsökning fysiker. Alla Web Services i UCOrders2 är stateless vilket innebär att påloggningsdata måste bifogas i varje beställning. Adresser Endpoint framgår av tjänstegruppens wsdlfil och är https://www.uc.se/ucsoapweb/services/ucorders2 Dokument och filer Följande dokument och filer får du av din kontaktperson på UC samt kortare information om den information som UC kommer att leverera. UC Web Services Beskrivning av UC:s informationsgrupper och termer. UC Web Services Teknisk beskrivning, detta dokument UCOrders2.wsdl Teknisk beskrivning av UC:s Web Services i UCOrders2 UC Web Services Beskrivning av UC:s personinformation UC Web Services Beskrivning av UC:s företagsformation UC Web Services Beskrivning av UC:s företagareinformation UC Web Services Beskrivning av UC:s information om enskild näringsverksamheter Felkoder vid anrop mot UC Testobjekt Sidan 4 av 18
SOAPmeddelandet Den principiella uppbyggnaden av SOAPmeddelandet för beställning respektive svar framgår av följande bild. Allt data i beställningen skickas i <Body>elementet och allt data i svarsmeddelandet från UC skickas i <Body>elementet eller i <Fault>elementet. SOAPdelen av en beställning eller ett svar kan se ut på följande sätt: <?xml version= 1.1 encoding= UTF8?> <SOAPENV:Envelope xmlns:soapenv= https://schemas.xmlsoap.org/soap/envelope/ xmlns:xsi= https://www.w3.org/2001/xmlschemainstance xmlns:xsd= https://www.w3.org/2001/xmlschema > <SOAPENV:Body> Här kommer beställningen eller svaret </SOAPENV:Body> </SOAPENV:Envelope> För en fullständig beskrivning av formatet på SOAPmeddelandet hänvisas till beskrivning i filen UCOrders2.wsdl Sidan 5 av 18
Beställning Anropet av en Web Service läggs i element med samma namn som beställd Web Service (<businessreport>, <companyreport>, <individualreport>, <identitycheck>, < identityseekjur > eller < identityseekfys>). Elementet har följande attribut: Element/Attribut Förklaring Obligatorisk product UC produkt, t.ex. 410. Web Service identity Check och identityseek Ja innehåller ej detta element. För valida värden hänvisas till kaptil Värdeområden för element och attribute. identifier Används endast av identitycheck, här anges person/organisations Ja nummer för personer/företaget som ska kontrolleras. version Versionnummer på beställd Web Service. För valida värden hänvisas Ja till kaptil Värdeområden för element och attribute. I beställningselementet läggs element för följande data: Påloggningsdata, främst kundnummer och personkod. Beställningdata inkl. beställning av eventuell mallfråga Beställningselementet ser grovt ut enligt följande exempel: <businessreport product= 410 version= 2.2 > <customer> påloggningsdata </customer> <businessreportquery> beställningsdata </businessreportquery> </businessreport> Beställningselementet ser ut enligt följande för identitycheck: <identitycheck identifier= 5561234567 version= 2.2 > <customer> påloggningsdata </customer> </identitycheck> Sidan 6 av 18
Påloggningsdata Elementet för påloggningsdata heter <customer>. Elementet innehåller följande viktiga element. Element/Attribut Förklaring Obligatorisk <userid> Kundnummer hos UC, fem tecken. Ja <password> Påloggningskod hos UC, två eller tre tecken. Ja Följande exempel visar hur <customer> kan se ut om ditt kundnummer hos UC är ABCDE och din personkod är UTC. Beställningsdata Elementet för beställning av upplysning heter olika beroende på val av tjänst. <companyreportquery> Företagsrapport <individualreportquery> Personrapport <businessreportquery> Företagarerapport <SeekJuridiker> idnrsökning juridiker <SeekFysiker> idnrsökning fysiker Elementen <companyreportquery>, <individualreportquery> och <businessreportquery> innehåller följande viktiga <element> och attribut. Element/Attribut Förklaring Obligatorisk <object> Person eller företagets organisationsnummer, alltid 10 siffor men eller Ja utan bindestreck <orderedby> Extern beställare, det vill saga om du beställer för någon annans Nej räkning, slutbeställare. Detta framkommer även på en eventuell kopia till omfrågad. <reference> Om du önskar ha med en egen referens i svaret tillbaka i Nej kreditupplysningen. <override> Kod för att tvinga igenom en företagare upplysning på en person som Nej enligt UC inte är näringsidkare. För valida värden hänvisas till kapitel för element och attribut. <creeditseek> Sökt kredit Nej extendeddetails Merinformation på personerna som sitter I styrelsen/ägarna. Endast Nej companyreport kan innehålla denna uppgift. Observera att vid beställning av merinfromation skickas det en kopia omfrågad till respektive styrelseledamot samt ägare. För valida värden hänvisas till kapitel för element och attribut. Sidan 7 av 18
Element/Attribut Förklaring Obligatorisk lang Rapportspråk. (Svenska eller Engelska) För valida värden hänvisas till Ja kapitel för element och attribut. xmlreply Beställning att kreditupplysning I XML format ska bifogas I svaret. Ja Detta element anges normalt inte i beställningen då default är att svaret innehåller kreditupplysning i XML format. För valida värden hänvisas till kapitel för element och attribut. htmlreply Beställning att kreditupplysning i HTML format ska bifogas i svaret. Ja För valida värden hänvisas till kapitel för element och attribut. <template> Element för beställning av kreditregelverk tillsammans med kredit Nej upplysningen. Se detaljerad beskrivning i kapitel Beställning av kreditregelverk. Följande exempel visar hur ett anrop av en <companyreportquery> kan se ut. <seekjuridiker> innehåller följande element Attribut Element/Attribut Förklaring Obligatorisk seekname Namn på det företag du efterfrågar Nej seekcategoryjur Kategori möjliga värden Ja Företag Aktiebolag Handels/kommanditbolag Enskild näringsidkare Juridisk person <adress> Grupptag för adress Nej streetadress Gatuadress Nej zipcode Postnummer Nej <telephone> Grupptag för telefon Nej countrycode Landskod Nej areacode Riktnummer Nej number Telefonnummer Nej maxseekhits Max antal träffar Yes Sidan 8 av 18
Följande exempel visar hur <seekjuridiker> kan se ut: <seekfysiker> innehåller följande element Element/Attribut Förklaring Obligatorisk seekname Namnet på personen du efterfrågar. Nej seekcategoryfys Kategori möjliga värden Ja Fysisk person Man Kvinna <adress> Grupptag för adress Nej streetadress Gatuadress Nej zipcode Postnummer Nej maxseekhits Maximalt antal träffar Ja Följande exempel visar hur < seekfysiker > kan se ut: Sidan 9 av 18
Beställning av kreditregelverk Elementet för beställning av kreditregelverk heter <template> och ligger i elementet för beställningsdata enligt beskrivning ovan. <template> har följande attribut: Element/Attribut Förklaring Obligatorisk id Namn på kreditregelverket Ja Elementet <template> innehåller följande viktiga element: Element/Attribut Förklaring Obligatorisk <income> Sökandes inkomst. Observera att endast individualreport kan innehålla Nej denna uppgift. Innehåller attributen type och value. type Inkomstbeloppets sort. För format och valida värden hänvisas till kapitel Nej Värdeområden för element och attribut. value Inkomstbeloppet. För format och valida värden hänvisas till kapitel Ja Värdeområden för element och attribut. <coobject> Personnummer på medsökande. Observera att endast individual Report Nej kan innehålla denna uppgift (inkomstbeloppets typ styrs av type i <income>). <coobjectincome> Inkomst för medsökande. Observera att endast individualreport kan Nej innehålla denna uppgift. <templateparams> Kreditregelverkets fria fält. För innehåll se nedan. Nej Noterbart är att beroende på kreditmallens uppbyggnad så kan vissa av elementen ovan vara obligatoriska om kreditmallen har dessa som tvingande mallparametrar. Elementet <templateparams> innehåller följande viktiga element. Element/Attribut Förklaring Obligatorisk <templateparam> Fritt fält. Innehåller attributen id och value. <templateparam> kan Nej upprepas upp till 20 gånger eftersom ett kreditregelverk kan innehålla upp till 20 fria fält. Id Ordningsnummer på det fria fältet. För format och valida värden Ja hänvisas till kapitel Värdeområden för element och attribut. value Värde på det fria fältet. Ja Sidan 10 av 18
Följande exempel visar hur elementet <individualreportquery> kan se ut om den inkluderar en mallfråga med mall ABC och tre fria fält. Följande exempel visar hur elementet <individualreportquery> kan se ut om den inkluderar en mallfråga med mall ABC som inte innehåller fria fält eller andra mallparametrar. Svar Svaret på en beställning levereras i elementet <body>. <body> innehåller ett fullständigt svar och ett meddelande som i normalfallet signalerar ett OK. <body> Svaret från en Web Service läggs i element <ucreply>. Elementet <ucreply> innehåller följande element. Element/Attribut Förklaring Förekomster <status> Statusinformation 1 <xmlreply> Levererade kreditupplysningar i XML format. 02 <htmlreply> Levererade kreditupplysningar i HTML format. 02 Sidan 11 av 18
Elementet <ucreply> har följande principiella uppbyggnad: Exemplet innehåller två element vardera av <xmlreply> och <htmlreply>. Detta är typexempel på när svaret ges i både XML och HTML, samt där svaret innehåller upplysningar för två personer/ företag. Två upplysningar levereras t.ex. vid fråga på sökande + medsökande eller företag + företagets moderbolag. Sidan 12 av 18
Ett annat typexempel på uppbyggnaden av <ucreply> är vissa företagareupplysningar där två <report>element kan förekomma i en <xmlreply>. Den första <report> innehåller då upplysningen på företagaren och den andra en bilaga med näringsidkaruppgifter enligt följande exempel: Status Elementet som visar statusinformation heter <status> och ligger i svarselementet <ucreply> enligt beskrivning ovan. <status> har följande attribut: Element/Attribut Förklaring Värdeområde result Statusflagga som visar hur din beställning gick. Ok = beställningen gick bra och förväntat resultat kan levereras. Error = beställningen gick inte bra och ett beskrivande med delande levereras. Elementet <status> innehåller följande element om result=error. Element/Attribut Förklaring Anmärkning <message> Meddelande från UC Innehåller attribut id med 3ställig meddelandekod och meddelande I klartext. Sidan 13 av 18
Följande exempel visar ett felmeddelande från UC på grund av felaktigt personnummer. xmlreply Elementet <xmlreply> innehåller de levererade upplysningar och har följande principiella uppbyggnad: Varje <reports> innehåller en eller två element <report>. Elementet <report> innehåller en upplysning eller bilaga till en upplysning. En detaljerad beskrivning av innehållet i <report> finns senare i detta dokument. htmlreply Elementet <htmlreply> innehåller de levererade upplysningar i HTMLformat och levereras om HTMLrapport beställts. <htmlreply> har följande principiella uppbyggnad: Sidan 14 av 18
Exempel på svar Följande exempel visar svaret på en beställning av inividualreport. Upplysningen är beställd utan HTMLrapporten. <?xml version= 1.1 encoding= UTF8?> <soapenv:envelope xmlns:soapenv= https://schemas.xmlsoap.org/soap/envelope/ xmlns:soapenc= https://schemas.xmlsoap.org/soap/encoding/ xmlns:xsd= https://www.w3.org/2001/xmlschema xmlns:xsi= https://www.w3.org/2001/xmlschemainstance > <soapenv:body> <ucreply xmlns= https://www.uc.se.schemas/ucorderreply/ > <ns2:status ns2:result= ok xmlns:ns2= https://www.uc.se.schemas/ucorderreply/ /> <ucreport> <xmlreply> <ns2:reports ns2:lang= swe xmlns:ns2= https://www.uc.se.schemas/ucorderreply/ > <ns2:report ns2:id= 4801093750 ns2:index= 0 ns2:name= Peter Ernst Peltonen ns2:styp= 3 > <ns2:group ns2:id= W080 ns2:index= 0 ns2:key= ns2:name= IDuppgifter, fysiker > <ns2:term ns2:id= W08001 >9480109375</ns2:term> <ns2:term ns2:id= W08002 >4801093750</ns2:term> <ns2:term ns2:id= W08003 >Peter Ernst Peltonen</ns2:term> <ns2:term ns2:id= W08004 >Barong 3</ns2:term> <ns2:term ns2:id= W08005 >23072</ns2:term> <ns2:term ns2:id= W08006 >Tygelsjö</ns2:term> <ns2:term ns2:id= W08007 >5905104948</ns2:term> <ns2:term ns2:id= W08008 >Helga Peltonen</ns2:term> <ns2:term ns2:id= W08015 >199510</ns2:term> <ns2:term ns2:id= W08045 >Registrerat sedan 199510 </ns2:term><ns2:term ns2:id= W08018 >N </ns2:term> <ns2:term ns2:id= W08027 /> <ns2:term ns2:id= W08030 >2</ns2:term> <ns2:term ns2:id= W08043 >Gift sedan 199508 med Helga Peltonen (5905104948)</ns2:term> <ns2:term ns2:id= W08031 >199508</ns2:term> <ns2:term ns2:id= W08036 >20031101</ns2:term> <ns2:term ns2:id= W08009 >12</ns2:term> <ns2:term ns2:id= W08012 >Skåne</ns2:term> <ns2:term ns2:id= W08010 >62</ns2:term> <ns2:term ns2:id= W08013 >Lomma</ns2:term> <ns2:term ns2:id= W08011 >01</ns2:term> <ns2:term ns2:id= W08014 >Lomma</ns2:term> <ns2:term ns2:id= W08035 >Peltonen, Peter Ernst </ns2:term></ns2:group> Här följer resten av rapporten </ns2:report> </ns2:reports> </xmlreply> </ucreport> </ucreply> </soapenv:body> </soapenv Det som skiljer exemplet från tidigare beskrivning är den inlagda referensen till aktuellt namespace, ns2:. Formatet på denna referens skiljer sig i olika produktionsmiljöer och versioner av namespace. Sidan 15 av 18
Värdeområden för element och attribut Element/Attribut Förekomst Valida värden Beställning product <businessreport produkt= 410 > 410 (Standard) 4 (Risk) 91 (Mikro) product <companyreport produkt= 410 > 410 (Standard) 41 (Mini) 4 (Risk) 91 (Mikro) product <individualreport produkt= 3 > 3 (Standard) 90 (Mikro) version <businessreport version= 2.2 > Versionsnummer mellan 1.1 och 2.2 fungerar för närvarande. version <companyreport version= 2.2 > Versionsnummer mellan 1.1 och 2.2 fungerar för närvarande. version <individualreport version= 2.2 > Versionsnummer mellan 1.1 och 2.2 fungerar för närvarande. version <identitycheck version= 2.2 > Versionsnummer mellan 1.1 och 2.2 fungerar för närvarande. <override> <businessreportquery> Se beskrivning nedan. <override>1</override> Blankt/0 13 </businessreportquery> xmlreply xmlreply= true true or false htmlreply htmlreply= false true or false extendeddetalis extendeddetalis= false true or false lang lang= swe swe för svenska och eng för engelska. type <income type= T value= 248 > T för tusentals kronor H för hundratals kronor Om ingen type anges så tolkas inkomsten som angiven I kronor. value <income type= T value= 248 > Numerisk, maximalt 6 tecken. Id <templateparam id= 1 value J > 120 Svar result <status result= ok > Ok or error Sidan 16 av 18
<override> Override är en funktion som gör det möjligt att beställa en företagareupplysning på en person som enligt UC inte är en aktiv näringsidkare. Vid beställning av upplysning om enskild näringsverksamhet (UC 410) eller en företagareupplysning (UC 501) erhålls i vissa lägen en meddelandekod (487 eller 491) som indikerar att personen inte är aktiv näringsidkare i UC:s register. Beställningen kan dock fullföljas, om handläggaren vet att personen är aktiv näringsidkare, genom att använda overridefunktionen. För meddelandekod 487 (när UC 501 beställts) kan <override> 1,2 eller 3 användas för forcering. För meddelandekod 491 (när UC 410 beställts) kan <override> 1 eller 2 användas för forcering. Override 1,2 eller 3 får inte användas som defaultvärde, utan bör endast användas när handläggaren vet att personen är en aktiv näringsidkare. <override></override> <override>1</override> <override>2</override> <override>3</override> Värde vid beställning av fråga utan forcering. Personen driver rörelse (aktivt val). Personen är VD eller styrelseledamot i ett aktiebolag (aktivt val). Personen är delägare i fåmansaktiebolag eller handels/kommanditbolag (aktivt val). Svarstransaktioner/xmlReply Svarstransaktionerna är indelade i informationsgrupper och dessa består av ett antal termer. I dokumentationen beskrivs samtliga förekommande informationsgrupper och tillhörande termer. Vidare beskrivs vilka informationsgrupper som kan förekomma för de olika rapporterna ( companyreport, businessreport eller individualreport ) med utgångspunkt från objektstypen; juridiker (företag) eller fysiker (person). Med andra ord informationsgrupperna och termerna i svarstransaktionen styrs primärt av beställd rapport och objektstyp men beror även på informationens omfattning för det enskilda objektet. Beskrivning av informationsgrupper och termer Varje informationsgrupp och term är beskriven och definierad utifrån följande parametrar; Termid, Benämning, Format, Index och Kommentar. W060 Fskatt, moms och arbetsgivaravgift Termid Benämning Format Index Kommentarer W06001 Reg för fskatt an1 0 J, N, A (J=Ja, N=Nej, A=Avreg) W06002 Klartext fskatt an..22 0 W06003 Datum för fskattuppgift an8 0 SSÅÅMMDD datum för registrering eller för avregistrering Termid: Informationsgrupper och termer är definierad med specifika identiteter (Termid) och där informationsgrupper är definierade med fyra positioner, som exempelvis W060 (Fskatt, moms mm) och tillhörande termer med sex positioner, som exempelvis W06001 (Reg för fskatt). Benämning: Termerna beskrivs av en benämning, d v s benämningen innehåller information om vilken typ av information termen innehåller. Sidan 17 av 18
Index: Informationsgrupper och termer kan förekomma flera gånger i varje svarstransaktion och indexet beskriver just antalet möjliga förekomster. Index 0 = 1 förekomst av termen och den finns i index 0 Index 01 = 2 förekomster en i index 0 och en i index 1 Index 02 = 3 förekomster en i index 0, en i index 1 och en i index 2 O s v Index * = obegränsat antal förekomster per svarstransaktion, d v s från Index 0 till * Kommentarer: I kommentarsfälten beskrivs vissa termer mer ingående för att förtydliga innehållet. För en utförligare beskrivning av UC:s termer se dokumentet UC Web Services Termbeskrivning version 3.1.pdf Huvudkontor Lokalkontor Kontakt Firma UC AB UC AB Göteborg UC AB Malmö Telefon: 08670 90 00 UC AB 117 88 Stockholm Gårdavägen 1 Malmöhusvägen 1 Epost: info@uc.se Org.nr. 5561375113 412 50 Göteborg 211 18 Malmö Web: uc.se