Navet Bilaga 8 Teknisk handledning E-persondata Demo Testdata Version 1.3

Transkript

1 *Skatteverket IT-avdelningen Navet Bilaga 8 Teknisk handledning E-persondata Demo Testdata Version 1.3

2 Innehållsförteckning 1. DOKUMENTINFORMATION SYFTE MÅLGRUPP REFERENSER BESKRIVNING AV SÖKTJÄNSTERNA INDATA OCH SÖKVILLKOR Utformning av indata till Web Service Personpost Utformning av indata till Web Service Namnsökning TESTDATA OCH UTDATA FELMEDDELANDEN Meddelandekoder Web Service Personpost Meddelandekoder Web Service Namnsökning Felsituationer CERTIFIKAT IP-ADRESS WSDL-FILER UPPKOPPLING TILLGÄNGLIGHET...9 Navet IT 2007 Skatteverket Sida 2 av 9

3 1. Dokumentinformation 1.1 Syfte Dokumentet är en användarhandledning för användare av Navets demoversion för onlinetjänsten epersondata som innehåller Web Service Personpost och Web Service Namnsökning. 1.2 Målgrupp Målgruppen för dokumentet är kommunikations- och applikationsansvariga hos de kunder till Skatteverket som skall använda Web Services för att ställa frågor mot Navet. 1.3 Referenser Ref. Dokumenttitel [1] Allmän beskrivning Navet, Skattever ket Utgivare Adress [2] Teknisk beskrivning Navet, Skattever ket [3] Bilaga 6, Teknisk handledning Web Service [4] Bilaga 9, Testdata för E-persondata Demo Navet, Skattever ket Navet, Skattever ket Välj i menyn Folkbokföring och Navet, avisering av befolkningsuppgifter. Välj sedan länken Allmän beskrivning. Välj i menyn Folkbokföring och Navet, avisering av befolkningsuppgifter. Välj sedan länken Teknisk beskrivning. Välj i menyn Folkbokföring och Navet, avisering av befolkningsuppgifter. Välj sedan länken Teknisk beskrivning. Välj bilaga 6. Välj i menyn Folkbokföring och Navet, avisering av befolkningsuppgifter. Välj sedan länken Teknisk beskrivning. Välj bilaga 9. Navet IT 2007 Skatteverket Sida 3 av 9

4 2. Beskrivning av söktjänsterna Med denna onlinetjänst kan man testa sin egen Web Service klient under utvecklingstiden för att se hur den fungerar mot Navets gränssnitt. Denna tjänst erbjuder ett begränsat antal testpersoner samt begränsade sökvillkor vid namnsökning. Den kan användas med ett testcertifikat som erhålls från Skatteverket eller ett eget skarpt certifikat. För ytterligare information angående Navets tjänster, se Navets Allmänna beskrivning ref [1], Tekniska beskrivning ref [2] och Teknisk handledning Web Service ref [3]. 2.1 Indata och sökvillkor Utformning av indata till Web Service Personpost De korrekta inparametrarna som ska anges till Web Service Personpost beskrivs i ref [3], kapitel I denna demoapplikation anges: Inparameter bestallningsid Beskrivning Organisationsnumret måste matcha certifikatets organisationsnummer. Testcertifikatets organisationsnummer är I denna demoapplikation görs ingen kontroll av att den sista delen i beställningsidentiteten är ett giltigt beställningsnummer. Exempel på beställningsidentitet som kan användas vid test med testcertifikat: FO personid Om man använder ett skarpt certifikat anger man istället det organisationsnummer som är knutet till just det certifikatet. Alla organisationsnummer börjar på 16. Giltig personidentitet anges enligt formatet ÅÅÅÅMMDDNNNK. Med personidentitet avses både Personnummer och Tilldelat personnummer/samordningsnummer. Exempel på personidentitet: Det finns endast ett fåtal personer att söka på, se ref [4]. För exempel på hur ett SOAP-meddelande utformas för Web Service Personpost se ref [3], kapitel Navet IT 2007 Skatteverket Sida 4 av 9

5 2.1.2 Utformning av indata till Web Service Namnsökning De korrekta inparametrarna som ska anges till Web Service Namnsökning beskrivs i ref [3], kapitel I denna demoapplikation anges: Inparameter bestallningsid Beskrivning Organisationsnumret måste matcha certifikatets organisationsnummer. Testcertifikatets organisationsnummer är I denna demoapplikation görs ingen kontroll av att den sista delen i beställningsidentiteten är ett giltigt beställningsnummer. Exempel på beställningsidentitet som kan användas vid test med testcertifikat: FO Sökvillkor Om man använder ett skarpt certifikat anger man istället det organisationsnummer som är knutet till just det certifikatet. Alla organisationsnummer börjar på 16. Det går att söka på ett fåtal förnamn och ett fåtal postnummer from var för sig, dvs. det går inte att kombinera de båda sökvillkoren. - Förnamn Sökning kan göras på förnamn, se termkod i ref [4]. * kan användas som fritt tecken i början av ett namn för att söka på del av förnamn. Det görs ingen skillnad på versaler och gemener. - Postnr from Sökning kan göras på postnummer from för folkbokföringsadress, termkod i ref [4]. Postnummer kan anges enligt följande: Postnr from Beskrivning 1 Samtliga postnummer som börjar på Samtliga postnummer som börjar på Samtliga postnummer som börjar på Samtliga postnummer som börjar på Samtliga postnummer som börjar på För exempel på hur ett SOAP-meddelande utformas för Web Service Namnsökning se ref [3], kapitel Navet IT 2007 Skatteverket Sida 5 av 9

6 2.2 Testdata och utdata Personer som går att söka på är de som finns beskrivna i dokumentet innehållande testdata ref [4]. Det resultat som returneras ska matcha dessa personer. Olika typer av testdata förekommer på personerna så att alla uppgifter är möjliga att erhålla på någon person. Utdata ingår i ett SOAP-meddelande i format termkod/termdata eller i XML-format. För information om hur detta meddelande är utformat se ref [3], kapitel samt Felmeddelanden Meddelandekoder Web Service Personpost Web Service Personpost returnerar en personpost när efterfrågad person hittas. Om till exempel inparametrarna är felaktiga, sökt post inte finns eller vid tekniskt fel returneras i stället ett specifikt SOAP-meddelande. De olika typerna av fel har olika meddelandekoder. Följande meddelandekoder kan erhållas från Personpost i denna demoapplikation (1, 4, -11). De olika meddelandekoderna finns beskrivna i ref [3], kapitel Tabellen nedan visar hur ett specifikt fel kan framkallas. Meddelandekod/ faultcode Meddelandetext/ faultstring 1 Ingen person finns med angivet personnummer. 4 Felaktiga inparametrar: Beställningsid har ett ogiltigt värde. 4 Felaktiga inparametrar: Ogiltigt värde på personidentiteten. Skall vara 12-siffrigt på formen 'ÅÅÅÅMMDDNNNK'. -11 Behörighetsfel: Orgnr i Beställningsid matchar inte med orgnr på Certifikatet. Framkallas genom att Söka på ett personnummer som inte finns i testdatat. Ange ett organisationsnummer som inte är 12 tecken dvs TTTTTTTTTTTT eller ange en beställningsidentitet med felaktigt format. Det giltiga formatet är NNNNNNNN-TTNN- NNNN Ange ett felaktigt format för personidentitet, som inte har formen 'ÅÅÅÅMMDDNNNK. Ange ett organisationsnummer i inparametern som inte matchar organisationsnummer på certifikatet Meddelandekoder Web Service Namnsökning Web Service Namnsökning returnerar namnposter när personer hittas enligt angivna sökvillkor. Om till exempel inparametrarna är felaktiga, inga personer hittas eller vid tekniskt fel returneras i stället ett specifikt SOAP-meddelande. De olika typerna av fel har olika meddelandekoder. Navet IT 2007 Skatteverket Sida 6 av 9

7 Följande meddelandekoder kan erhållas från Namnsökning i denna demoapplikation (1, 4, -11). De olika meddelandekoderna finns beskrivna i ref [3], kapitel Navet IT 2007 Skatteverket Sida 7 av 9

8 Tabellen nedan visar hur ett specifikt fel kan framkallas. Meddelandekod/ faultcode Meddelandetext/ faultstring 1 Inga personer uppfyllde sökvillkoren 4 Felaktiga inparametrar: Beställningsid har ett ogiltigt värde. 4 Felaktiga inparametrar: Termens längd är felaktig. Felaktiga inparametrar: Talet är felaktigt. -11 Behörighetsfel: Orgnr i Beställningsid matchar inte med orgnr på Certifikatet. Framkallas genom att Söka på personuppgifter som inte finns i testdatat. Ange ett organisationsnummer som inte är 12 tecken dvs TTTTTTTTTTTT eller ange en beställningsidentitet med felaktigt format. Det giltiga formatet är NNNNNNNN-TTNN- NNNN Ange ett förnamn som är längre än 80 tecken. Ange ett postnummer som har ett felaktigt format. Ange ett organisationsnummer i inparametern som inte matchar organisationsnummer på certifikatet Felsituationer Förutom de meddelandekoder som returneras via ett SOAP-fault kan också andra felsituationer uppstå. Felet kan bero på fel hos Skatteverket eller hos klienten. Exempel på felsituationer beskrivs i ref [3], kapitel Certifikat Denna tjänst kan användas med ett testcertifikat som erhålls från Skatteverket eller ett eget skarpt certifikat. Testcertifikatet beställer ni från Skatteverket genom att maila till navet.solna@skatteverket.se När testcertifikatets giltighet går ut kan ni beställa ett nytt. Mer information om certifikat finns i ref [3], kapitel IP-adress För att använda denna tjänst måste ni ange vilken IP-adress ni kommer att köra ifrån. Brandväggen öppnas då upp för er IP-adress så att ni får åtkomst till tjänsten under 6 månader. Er IP-adress skickar ni till adressen navet.solna@skatteverket.se samt talar om att ni vill köra demoversionen av Navets onlinetjänst epersondata. 2.6 WSDL-filer Gränsnittet till Web Service Personpost och Web Service Namnsökning beskrivs via dess WSDL-filer. Se Bilaga 1-4 som finns i ref [3]. Det som skiljer dessa WSDL-filer från de som ska användas för denna applikation är att ska ersättas med Navet IT 2007 Skatteverket Sida 8 av 9

9 2.7 Uppkoppling För anslutning mot Web Service Personpost i format termkod/termdata anges följande adress: För anslutning mot Web Service Personpost i XML-format anges följande adress: För anslutning mot Web Service Namnsökning i format termkod/termdata anges följande adress: För anslutning mot Web Service Namnsökning i XML-format anges följande adress: Tillgänglighet Tjänsten kommer i stort sett att vara tillgänglig dygnet runt. Enstaka störningar kan dock förekomma. Ingen information om eventuella störningar publiceras på webben. Navet IT 2007 Skatteverket Sida 9 av 9