Tjänster mot befolkningsregistret. version

Transkript

1 Tjänster mot befolkningsregistret version

2 2(18) Innehåll Förutsättningar... 4 Säkerhet... 4 WSDL... 4 Test... 4 Produktion... 4 Personnummerbyten... 5 Adresser... 5 Skyddade adresser... 5 Tjänster... 6 GetPerson... 6 FindPerson... 7 GetCountries... 9 GetRegionalDevisions GetCareChoice Dataformat Personnummer Nil Person Deregistration SwedishAddress ForeignAddress Relation Country County Municipality Parish CareChoice PrimaryCareChoice ArgumentFault FormatFault ServerFault Dokumenthistorik... 18

3 3(18) Inledning Det här dokumentet är en specifikation av de tjänster som Västerbottens läns landsting tillhandahåller för uttag av aktuella personuppgifter. Målgruppen är tekniskt ansvariga och de utvecklare som ska integrera ett system med befolkningsregistret. Dessa tjänster är det gränssnitt vilket Informatikenheten vill att alla system använder sig av. Om någon personuppgift saknas, eller om ett system har behov av att söka i befolkningsregistret på ett annat sätt, är vi förstås beredda att vidareutveckla tjänsterna.

4 4(18) Förutsättningar Säkerhet Den teknik som används för autentisering är så kallad basic authentication enligt http-protokollet, där användarnamn och lösenord skickas Base64-kodat. I autentiseringen är det inte slutanvändarens identitet som kontrolleras, utan användarnamnet och lösenordet är unikt per anropande system. Om systemet redan har ett Active Directory-konto hos landstinget så kan detta användas. Annars tilldelas ett konto av Informatikenheten. Informatikenheten lägger också upp en åtkomstbehörighet till tjänsterna. Vi vill att lösningen byggs konfigurerbar så att våra administratörer kan ändra användarnamn och lösenord i efterhand. Även om det är det anropande systemet som autentiseras och auktoriseras för att komma åt tjänsterna, så loggar vissa av tjänsterna slutanvändarens namn för att få en fullgod spårbarhet. Kraven kring detta beskrivs närmare under respektive tjänst. För att skydda lösenord och övrig data så används alltid traditionell SSL-kryptering baserat på servercertifikat, det man brukar kalla https. WSDL Landstingets tjänster bygger på SOAP version 1.1 och en beskrivning i WSDL-format finns som bilaga till detta dokument, men kan också laddas ner från följande adresser: eller Test För testkörning under utvecklingsfasen och för acceptanstest hos beställaren har vi särskilda versioner av tjänsterna. Dessa finns på en server som heter servicestest och den adress som finns i WSDL-filen går mot denna. För att komma åt testservern så behöver den part som utvecklar kopplingen antingen sitta inom landstingets interna nätverk, eller installera en VPN-klient på sin dator. Beställning av en sådan VPNklient görs av systemägaren på landstinget. Produktion När det är dags för produktion så ska tjänsteanropen gå mot en server som heter services. Tjänsternas adress ändras då till: eller

5 5(18) Personnummerbyten System som arbetar med persondata kan behöva hantera personnummerbyten. En person kan få ett nytt personnummer av flera olika anledningar. Nationellt kan Skatteverket tilldela en person ett nytt nummer till exempel när ett sekretesskydd ska träda i kraft, eller när ett födelsedatum ska korrigeras. En person kan tillfälligt ha ett reservnummer som tilldelats lokalt av Västerbottens läns landsting som sedan knyts till ett nationellt personnummer när detta blir känt. Det kan till exempel gälla nyfödda eller akutfall där man inte med en gång kan bestämma identiteten. Ett system som behöver hantera personnummerbyten och som bygger på våra tjänster kan känna igen detta via elementet Deregistration i Person-posten. Om Reason är GN är personnumret avregistrerat och utbytt mot det som står i ReferenceId. Systemet kan då göra en till sökning på det nya personnumret. Detta kan behöva upprepas i fler än ett steg. Adresser För att bestämma aktuell adress utifrån de uppgifter som returneras i en Person-post, så gör man det normalt så här: Om personen är utvandrad, dvs Deregistration är inte nil och Deregistration.Reason = UV, ta adressen från ForeignAddress. Är ForeignAddress nil finns ingen adress som kan anses vara aktuell. Om personen inte är utvandrad, ta första adressen som inte är nil från 1) MailingAddress, 2) RegistrationAddress, eller 3) ForeignAddress. Till exempel kan personer med reservnummer ha status som ej utvandrad, men samtidigt bara ha en utlandsadress. Skyddade adresser Personer med skyddad adress markeras med Confidencial = J och får en RegistrationAddress som går till Skatteverket som handhar att vidarebefordra post till personen. County, Municipality och Parish är också knutna till Skatteverkets kontor, inte till personens verkliga bostadsort.

6 6(18) Tjänster Nedan beskrivs de tjänster som finns mot befolkningsregistret. Allmänt kan sägas att argument som skickas in tolkas på ett förlåtande sätt. Nil och tom sträng hanteras ekvivalent och ingen skillnad görs mellan stora och små bokstäver. Svarstiderna som anges beskriver ett 99-procentigt konfidensintervall, men är bara tänkt att ge en uppfattning om vad man kan förvänta sig i normalfallet. Vid hög last eller uppstartsfaser kan det mycket väl ta längre tid att få svar. GetPerson Hämta personuppgifter för en eller flera fullständiga personnummer. Parametrar personids En lista av fullständiga personnummer. Som mest kan personnummer anges. För giltiga format, se avsnitt Dataformat. applicationuser Identitet på den användare som gör sökningen. Ange nil eller tom sträng om sökningen inte är en del av en användarsession. Resultat Tjänsten returnerar en lista med en Person-post för varje personnummer i parametern personids. Första posten innehåller personuppgifterna för första personnumret, osv. Personnummer som inte finns i befolkningsregistret ger tillbaka en nil-post. Om något eller några personnummer i personids är felaktigt formatterade så orsakar detta inte ett vanligt SOAP-fel, utan förfrågan går vidare för de personnummer som är rätt formatterade. De som var felaktigt formatterade ger tillbaka en Person-post där FaultCode har värdet Format. Svarstid (millisekunder): N, där N = antal nummer i personids. De SOAP-fel som kan inträffa är: FaultCode Detail-typ Beskrivning Argument ArgumentFault Parametern personids har för många element. Server ServerFault Ett fel har orsakats av tjänsten eller bakomliggande system. Funktion GetPerson används när man har en eller flera identifierade personer och vill hämta de senaste uppgifterna om dessa. Till skillnad mot FindPerson så kan GetPerson också returnera information om relaterade personer i elementet Relations.

7 7(18) För att entydigt kunna identifiera varje person måste personnumren vara fullständiga, men eftersom det förekommer att system inte arbetar med 12 teckens personnummer så är tolkningen förlåtande. 11 och 10 teckens personnummer, med eller utan bindestreck, accepteras också. För personnummer med 10 tecken kommer tjänsten att bestämma sekelsiffrorna genom att söka i befolkningsregistret efter senast giltiga personnumret. Om befolkningsregistret innehåller både (avliden) och , så tolkas som det senare. I resultatpostens PersonId-element kan det fullständiga personnumret med 12 tecken avläsas. Sökningen sker både bland aktuella och inaktuella personnummer. För inaktuella personnummer kommer Deregistration att ange en avregistreringsorsak och ett datum för avregistreringen, om det är känt. Speciell hantering kan behövas för avregistreringsorsak GN, se avsnitt Personnummerbyten. Reservnummer som registrerats lokalt hos Västerbottens läns landsting kan också sökas fram med GetPerson och hanteras på samma sätt som sökning på vanliga personnummer. Sekretesskyddade personer kan sökas fram med GetPerson, men kommer alltid att returneras med en RegistrationAddress som går till Skatteverket. Likaså County, Municipality och Parish är inte personens verkliga bostadsort. För att se om en person är sekretesskyddad testar man om Confidencial är skilt från nil och innehåller värdet J. För personer som aldrig bott i vår region, eller personer som har bott inom vår region och flyttat ut, kan uppgifterna man får tillbaka vara några dagar gamla. Sådana personer genererar en nationell sökning hos Skatteverket som sedan sparas några dagar i vårt lokala befolkningsregister. Personer som flyttat ut ur vår region de senaste åren kommer att ha datum för detta angivet i LeftRegion. Sökningar med GetPerson loggas och för att få spårbarhet i detta så ska namnet på den användare som gör sökningen anges i parametern applicationuser. Detta ska vara användarens identitet i det anropande systemet. Om sökningen görs i samband med ett bakgrundsjobb eller av annan anledning inte kan sägas vara initierad av en användare, så lämnas denna parameter tom eller sätts till nil. FindPerson Sök efter personer som matchar givna personuppgifter. Parametrar personid firstname middlename lastname Personnummer, fullständigt eller ofullständigt. Förnamn separerade med blanksteg. Mellannamn, dvs ett andra efternamn. Efternamn.

8 8(18) address postalcode city birthdate gender Utdelningsadress. Postnummer, 1-5 siffror. Postort. Födelsedatum. Del av YYYYMMDD eller YYYY-MM-DD ner till Y-M-D. Kön, F = kvinna, M = man, U = obestämt. excludenationalids Sätts till true om man bara vill söka på reservnummer, nil eller förvalt värde är false. maxcount Högsta antalet träffar som önskas, eller nil för tjänstens förvalda värde. Anges ett värde ska det vara inom intervallet [0, 1 000]. applicationuser Identitet på den användare som gör sökningen. Ange nil eller tom sträng om sökningen inte är en del av en användarsession. Resultat Tjänsten returnerar en lista med Person-poster som matchar personpattern. Om ingen i befolkningsregistret matchar personpattern så returneras en lista med noll poster. Svarstid (millisekunder): ,5N, där N = antal svarsposter. De SOAP-fel som kan inträffa är: FaultCode Detail-typ Beskrivning Argument ArgumentFault Parametern maxcount är utanför giltigt intervall. Format FormatFault Ett element i personpattern har ogiltigt format. Server ServerFault Ett fel har orsakats av tjänsten eller bakomliggande system. Funktion FindPerson används när man har en persons namn eller andra uppgifter och vill hitta den exakta identiteten. Tjänsten är byggd utifrån scenariot där sökresultatet presenteras som valalternativ för en användare. Därför är matchningen inte exakt. För namn, adress och postort görs en fonetisk sökning där liknande bokstäver matchar varandra och diakritiska tecken ignoreras. För alla termer gäller att matchning bara görs mot inledningen av varje ord, så att till exempel sökning på Ann ger träff på Anna och sökning på postnummer 907 ger träff på Om personnummer anges så kan århundrade och ett eller flera av de sista fyra tecknen utelämnas.

9 9(18) Anger man endast ett fullständigt personnummer med 10, 11 eller 12 tecken, så kan en nationell sökning ske och man hittar då en person oavsett var i Sverige han eller hon är registrerad. Men anger man fler söktermer, eller ett ofullständigt personnummer, så sker sökningen bara i vår region. Personer som av någon anledning har avregistrerats, till exempel avlidna och utvandrade, är exkluderade från sökresultatet. Sökningen görs bara bland de senaste uppgifterna i befolkningsregistret. Man får alltså inte träff på gamla gatuadressen om en person har flyttat, eller på det gamla namnet om namnet har bytts. En annan begränsning är att sökning bara sker bland personer registrerade i norra regionen, dvs Västerbottens län, Västernorrlands län, Jämtlands län och Norrbottens län. Fältet Relations i Person-posten fylls inte i av FindPerson. Behöver man dessa uppgifter kan man göra ett kompletterande anrop till GetPerson. Reservnummer som registrerats lokalt hos Västerbottens läns landsting kan sökas fram med FindPerson, med den skillnaden att mellannamn inte finns i reservnummerdatabasen. Söker man på mellannamn får man därför ingen träff på reservnummer. Sekretesskyddade personer kan sökas fram med FindPerson, förutsatt att man angett ett fullständigt personnummer med 10, 11 eller 12 tecken. Dessa kommer alltid att returneras med en RegistrationAddress som går till Skatteverket. Likaså County, Municipality och Parish är inte personens verkliga bostadsort. För att se om en person är sekretesskyddad testar man om Confidencial är skilt från nil och innehåller värdet J. Sökningar med FindPerson loggas och för att få spårbarhet i detta så ska namnet på den användare som gör sökningen anges i parametern applicationuser. Detta ska vara användarens identitet i det anropande systemet. Om sökningen görs i samband med ett bakgrundsjobb eller av annan anledning inte kan sägas vara initierad av en användare, så lämnas denna parameter tom eller sätts till nil. GetCountries Hämta fullständig förteckning över landskoder och landsnamn. Parametrar Inga. Resultat Tjänsten returnerar en lista med Country-poster sorterad efter landsnamn. Svarstid (millisekunder): 100. De SOAP-fel som kan inträffa är:

10 10(18) FaultCode Detail-typ Beskrivning Server ServerFault Ett fel har orsakats av tjänsten eller bakomliggande system. Funktion Förteckningen över landskoder och landsnamn bygger på kodstandarden i ISO 3166 med svensk namnsättning. Koderna kan användas till att översätta Citizenship i Person-poster till ett landsnamn, eller till att översätta landsnamnet i BirthCountry till en landskod. GetRegionalDevisions Hämta fullständig förteckning över Sveriges geografiska indelning. Parametrar Inga. Resultat Tjänsten returnerar en trädstruktur med County-, Municipality- och Parish-poster sorterade efter länsnamn, kommunnamn respektive församlingsnamn. Svarstid (millisekunder): 150. De SOAP-fel som kan inträffa är: FaultCode Detail-typ Beskrivning Server ServerFault Ett fel har orsakats av tjänsten eller bakomliggande system. Funktion Förteckningen över Sveriges geografiska indelning bygger på de tvåsiffriga koder som bestämts av SCB och Svenska kyrkan. I folkbokföringen används koderna för att registrera var personer bor och återfinns i Person-postens element County, Municipality och Parish. GetCareChoice Hämta hälsoval i Västerbotten för en eller flera fullständiga personnummer. Parametrar personids En lista av fullständiga personnummer. Som mest kan personnummer anges. För giltiga format, se avsnitt Dataformat. applicationuser

11 11(18) Identitet på den användare som gör sökningen. Ange nil eller tom sträng om sökningen inte är en del av en användarsession. Resultat Tjänsten returnerar en lista med en CareChoice-post för varje personnummer i parametern personids. Första posten innehåller hälsoval för första personnumret, osv. Personnummer som aldrig varit registrerade med ett hälsoval ger en nil-post tillbaka. Om något eller några personnummer i personids är felaktigt formatterade så orsakar detta inte ett vanligt SOAP-fel, utan förfrågan går vidare för de personnummer som är rätt formatterade. De som var felaktigt formatterade ger tillbaka en CareChoicepost där FaultCode har värdet Format. Svarstid (millisekunder): N, där N = antal nummer i personids. De SOAP-fel som kan inträffa är: FaultCode Detail-typ Beskrivning Argument ArgumentFault Parametern personids har för många element. Server ServerFault Ett fel har orsakats av tjänsten eller bakomliggande system. Funktion För att entydigt kunna identifiera varje person måste personnumren vara fullständiga, men eftersom det förekommer att system inte arbetar med 12 teckens personnummer så är tolkningen förlåtande. 11 och 10 teckens personnummer, med eller utan bindestreck, accepteras också. För personnummer med 10 tecken kommer tjänsten att bestämma sekelsiffrorna genom att söka efter senast giltiga personnumret. Om hälsoval finns registrerade för både (avliden) och , så tolkas som det senare. I resultatpostens PersonId-element kan det fullständiga personnumret med 12 tecken avläsas. Sekretesskyddade och reservnummer har aldrig något hälsoval registrerat och ger därför en nil-post tillbaka. PrimaryCareChoices innehåller historiken över personens hälsoval, senaste först och äldsta sist. From och To anger giltighetsintervallet för varje hälsoval. Observera att To är exklusiv, dvs dagen efter giltigheten upphört. Om ett aktivt hälsoval finns så har första posten i PrimaryCareChoices en To som är nil. I annat fall betyder det att personen haft ett hälsoval i Västerbotten, men har flyttat ut ur länet eller avregistrerats ur befolkningsregistret. Sökningar med GetCareChoice loggas och för att få spårbarhet i detta så ska namnet på den användare som gör sökningen anges i parametern applicationuser. Detta ska vara användarens identitet i det anropande systemet. Om sökningen görs i samband med ett bakgrundsjobb eller av annan anledning inte kan sägas vara initierad av en användare, så lämnas denna parameter tom eller sätts till nil.

12 12(18) Dataformat Många element i de typer som tjänsterna arbetar med är kopierade från en motsvarande term hos Skatteverket. När så är fallet anges det i kolumnen Termkod, som är den beteckning som termen har i Skatteverkets system för distribution av folkbokföringsuppgifter Navet. I de formatbeskrivningar som ges används följande beteckningar: N en siffra. X en siffra eller en bokstav. Y del av ett årtal. M del av en månad, D del av en dag, Personnummer När personnummer skickas som resultat från tjänsterna har de konsekvent 12 tecken och inget bindestreck. För personnummer som skickas som argument till tjänsterna görs först ett försök att tolka det som ett fullständigt personnummer med 10, 11 eller 12 teckens längd, med eller utan bindestreck. Formatet på dessa är: 10 tecken: YYNNNN-XNNN eller YYNNNNXNNN 11 tecken: YYYNNNN-XNNN eller YYYNNNNXNNN 12 tecken: YYYYNNNN-XNNN eller YYYYNNNNXNNN Om personnumret inte kan läsas som ett fullständigt personnummer, tolkas det som ett ofullständigt personnummer. Detta ska bestå av de första sex till åtta siffrorna, men en eller flera av de sista fyra tecknen kan vara utelämnade. Tjänsterna lägger ytterligare begränsningar på kombinationer av N och X som kan resultera i ett FormatFault, men detta lämnas ospecificerat för att kunna stödja framtida person- och reservnummerformat. Nil Alla element kan vara nil och ska tolkas som att uppgiften är okänd eller inte meningsfull i sammanhanget.

13 13(18) Person Element Typ Innehåll och format Termkod PersonId String Personnummer som posten gäller YYYYNNNNXNNN Confidencial String Sekretessmarkering J = sekretessmarkerad, nil/saknas = ej sekretessmarkerad ReferenceId String Gammalt eller nytt personnummer YYYYNNNNXNNN Deregistration Deregistration Uppgifter om avregistrering. FirstName String Förnamn separerade med blanksteg tecken MiddleName String Mellannamn separerade med blanksteg tecken LastName String Efternamn separerade med blanksteg tecken County String Län där personen är folkbokförd. 2 siffror Municipality String Kommun där personen är folkbokförd. 2 siffror Parish String Församling där personen är folkbokförd. 2 siffror Property String Fastighetsbeteckning tecken RegistrationAddress SwedishAddress Uppgifter om bostadsadress MailingAddress SwedishAddress Uppgifter om särskild postadress. ForeignAddress ForeignAddress Uppgifter om adress i utlandet. BirthCountry String Födelseland i klartext tecken Relations ArrayOfRelation Relaterade personer. Citizenship String Land där personen är medborgare. 2 tecken GivenName String Tilltalsnamn i klartext tecken BirthDate String Födelsedatum. YYYYMMDD, nollor för okända delar Gender String Kön. F = kvinna, M = man, U = obestämt NYKOCode String Statistikområde enligt SCBs NYKO-register. 6 siffror LeftRegion String Datum för flytt ut ur vår region. YYYYMMDD, nollor för okända delar LMAId String LMA-nummer för flykting. NN-NNNNNN FaultCode String Felkod. Se avsnitt GetPerson

14 14(18) Deregistration Element Typ Innehåll och format Termkod Reason String Orsak för avregistreringen. AV = avliden, UV = utvandrad, GN = gammalt personnummer, AN = annan anledning, GS = gammalt samordningsnummer, TA = tekniskt avregistrerad, OB = obefintlig Date String Datum för avregistrering. YYYYMMDD, nollor för okända delar SwedishAddress Element Typ Innehåll och format Termkod CareOf String Care of-adress tecken Address1 String Utdelningsadress, rad tecken Address2 String Utdelningsadress, rad tecken PostalCode String Postnummer. 5 siffror City String Postort tecken ForeignAddress Element Typ Innehåll och format Termkod Address1 String Utdelningsadress, rad tecken Address2 String Utdelningsadress, rad tecken Address3 String Utdelningsadress, rad tecken Country String Landsnamn i klartext tecken Date String Datum för utlandsadress. YYYYMMDD, nollor för okända delar 01078

15 15(18) Relation Element Typ Innehåll och format Termkod PersonId String Personnummer för relationspersonen YYYYNNNNXNNN BirthTimeId String Födelsetid för ej folkbokförd relationsperson YYYYMMDDNNNN RelationType String B = barn, MO = moder, FA = fader, F = förälder, V = vårdnadshavare, VF = vårdnadshavare för, M = make/maka, P = partner FromDate String Startdatum för relationen YYYYMMDD, nollor för okända delar FirstName String Förnamn, ej folkbokförd relationsperson tecken MiddleName String Mellannamn, ej folkbokförd relationsperson tecken LastName String Efternamn, ej folkbokförd relationsperson tecken Deregistration Deregistration Uppgifter om avregistrering. Country Element Typ Innehåll och format Code String Landskod enligt ISO tecken Name String Svenskt namn tecken County Element Typ Innehåll och format Code String Länskod. 2 siffror Name String Namn tecken Municipalities ArrayOf- Municipality Uppgifter om kommuner i detta län. Municipality Element Typ Innehåll och format Code String Kommunkod.

16 16(18) 2 siffror Name String Namn. Parishes ArrayOf- Parish 1-32 tecken Uppgifter om församlingar i denna kommun. Parish Element Typ Innehåll och format Code String Församlingskod. 2 siffror Name String Namn tecken CareChoice Element Typ Innehåll och format PersonId String Personnummer som posten gäller. YYYYNNNNXNNN PrimaryCareChoices ArrayOfPrimary- Historik över hälsoval i primärvården. Senaste valet först. CareChoice FaultCode String Felkod. Se avsnitt GetCareChoice PrimaryCareChoice Element Typ Innehåll och format Status Integer Hur hälsovalet kom till. 1 = geografisk tilldelning, 2 = eget val From DateTime Startdatum (inkl). To DateTime Slutdatum (exkl), eller nil om tillsvidare. UnitId String HSA-id för hälsocentralen tecken UnitCode String VL-intern kod för hälsocentralen. 6 tecken UnitName String Namn på hälsocentralen tecken DoctorId String HSA-id för läkaren tecken DoctorCode String VL-intern kod för läkaren. 10 tecken DoctorName String Namn på läkaren tecken

17 17(18) ArgumentFault Element Typ Innehåll och format Parameter String Namn på den parameter som är felaktig. FormatFault Element Typ Innehåll och format Element String Namn på det element som har felaktigt format. ServerFault Element Typ Innehåll och format Reference String Används ej.

18 18(18) Dokumenthistorik (förändringar mot version ) Ett avsnitt Adresser har lagts till. FindPerson tar alla element från PersonPattern som parametrar istället. En ny parameter har lagts till för att kunna begränsa sökningen till reservnummer. En tjänst GetCareChoice har lagts till för att hämta hälsoval för en eller flera personer Avsnittet Adresser har skrivits om för att inkludera personer med reservnummer som inte har status som utvandrade men ändå bara har en utlandsadress (förändringar mot version ) Ett nytt element LMAId har lagts till i Person-posten Förtydligande om att sökning med FindPerson är begränsad till norra regionen URL:erna rättade i avsnitt Förutsättningar. Nytt avsnitt om skyddade adresser.