1. Indledning

Dette dokument beskriver CPR Direkte service grænsefladen for servicen "ADRM - Match".

1.1. Formål

Servicen har til formål at levere persondata til CPRs kunder på baggrund af navne- og adressesøgninger. Servicen leverer data i samme recordformat som udtræksprodukt U08080P "Adressematch Person Ændringsudtræk" og derfor kan udtrækskunder bruge servicen til at supplere eller genopfriske data i deres eget systemer mellem CPR batchkørsler.

2. Adgang

Følgende afsnit beskriver de adgangskrav der stilles til brugere af servicen.

2.1. Kundefokus

Brug af denne service henvender sig til private kunder.

2.2. Adgangskontrol

Brugere skal kunne autentificeres af CPR-sikkerhedssystemet for at kunne benytte servicen. Derudover skal brugere være tildelt en CPR Direkte sikkerhedsprofil, der giver adgang til servicen.

3. Parametre

Servicen understøtter følgende parametre:

Parameter: Adresseringsnavn format
Der kan vælges, om adresseringsnavne udskrives i enten Fornavn(e) Efternavn eller Efternavn,Fornavn(e) formatter.
Standardværdi: Efternavn,Fornavn(e)

Parameter: Navne- og adressebeskyttelse undtages
Angiver om der undlades navne- og adressedata på personer med aktiv navne- og adressebeskyttelse registreret i CPR.
Parameterværdier: Ja eller Nej
Standardværdi: Ja

Parameter: Personnummerabonnement kundenummer
Angiver kundenummer hvor kundens personnummer abonnementer oprettes.
Standardværdi: (ingen)

Parameter: Sidst kendte adresse på afdøde personer
Der kan vælges hvorvidt servicen leverer sidste kendte adresse på afdøde (CPR statuskode 90) personer i records, der indeholder adressedata.
Parameterværdier: Ja eller Nej
Standardværdi: Nej

Hvis der ønskes ændret i opgavens parametre skal du kontakte CPR Kundecenter.

4. Kommunikationsprotokol

Kommunikationen med servicen foregår over en almindelig socketforbindelse. Beskeder mellem klientapplikationen og servicen sendes i fastlængde recordformat jvf. recordbeskrivelserne i dette dokument.

For at udføre matchopslag skal brugere først autentificeres af CPR-sikkerhedssystemet hvorefter det er muligt at sende søgekriterierne. Følgende udføres på samme socketforbindelse:

1. Opret forbindelse til CPR Direkte
2. Send Login forespørgsel
3. Læs autentifikation token fra Login respons (eller håndtere evt. fejl angivet i respons)
4. Send Match forespørgsel
5. Læs data fra Match respons (eller håndtere evt. fejl angivet i respons)

Bemærk at CPR Direkte servicen lukker selv forbindelsen i følgende tilfælde:

• Login forespørgslen fejler fx. forkert brugernavn/password
• Der går længere end 5 sekunder mellem afsendelse af Login respons og Match forespørgsel
• Efter klienten har modtaget Match respons

5. Inddata

I dette afsnit beskrives de recordtyper der bruges for at autentificere brugeren samt udføre matchopslag.

5.1. Login forespørgsel

Record der sendes for at hente en tokenværdi fra CPR-sikkerhedssystemet. Autentifikation er nødvendigt for at få en tokenværdi som er krævet for at foretage opslag i CPR.

Recordlængde: 35

Eksempel:

ADRM,111190BRUGER  Password

5.2. Login respons

Record der leveres tilbage til brugeren i forbindelse med en login forespørgsel.

Hvis FEJLNR er 00 kan brugeren hente en tokenværdi fra TOKEN recordfeltet.

Recordlængde: 28

Eksempel (tokenværdi er KETDqhzM):

111190KETDqhzMBRUGER  000028

5.3. Match forespørgsel

Record der indeholder søgekriterierne relateret til det person, der ønskes slået op.

Matchregler beskrives nedenunder i afsnit Matchregler.

Recordlængde: 204

Hvis der er kendskab til en person PNR (CPR-nr.) kan dette bruges til at slå personen op i stedet for navne- og adressesøgekriterier. Personnumre angives i KUNDEREFNR recordfeltet. Se venligst eksemplet nedenunder.

Matchopslag eksempler:

Navn og adresse:

111106KETDqhzMBRUGER  00ref-123456789   Per Andersen                                                      01011970

Personnummer (PNR er 1212123333):

111106KETDqhzMBRUGER  00PNR=1212123333

Alle søgekriterier:

111106KETDqhzMBRUGER  00ref-123456789  MPer Andersen                                                      010119703450                Allerød             Allerødvej                              1   02th

Bemærk at kun en af POSTDISTRIKT eller KOMMUNE feltet skal udfyldes i forbindelse med adressesøgninger. Eksemplet viser begge felter udfyldt.

5.4. Match respons

Record der indeholder responsen for et matchopslag.

Hvis der fandtes en person for de angivne søgekriterierne i CPR leveres der data relateret til personen tilbage i DATA recordfeltet. Hvilke records der leveres tilbage i DATA feltet styres af kundens opgaveindstillinger.

Recordlængde: 28 + DATALÆNGDE

5.5. Matchregler

Følgende regler gælder for Match forespørgsel opslag:

• KUNDEREFNR skal angives hvis der ønskes abonnementssætning eller sletning, idet KUNDEREFNR er nøglen til forbindelsen mellem CPR-registret og kundens administrative system
• Et bestemt KUNDEREFNR kan kun benyttes til én person
• Samme person kan derimod godt blive abonnementsat med flere forskellige kundereferencenumre
• NAVN for personen skal altid angives. De nærmere regler er:
  • at der mindst skal være 2 hele navnedele
  • at navnedelene skal skrives i korrekt rækkefølge (fornavne mellemnavne efternavne)
• Udover ovenstående skal FOEDDTO (fødselsdato) og/eller adresse være angivet til identifikation af personen. Hvis begge er udfyldt skal begge være korrekte. Det vil sige at man kan slå personer op med følgende søgekriterier kombinationer:
  • Navn og fødselsdato
  • Navn og adresse
  • Navn, fødselsdato og adresse
    • KOEN (køn) behøver ikke angives, men hvis det angives skal en af de legale værdier benyttes (K for kvinde, M for mand)
• Når adressen benyttes gælder følgende detailreglerne for adressefelterne:
  • Enten POSTDISTRIKT eller KOMMUNE skal være angivet, men ikke begge
  • For både felterne til POSTDISTRIKT og KOMMUNE gælder, at de kan udfyldes med enten klarskrift fx "Allerød" eller med kode (postnummer henholdsvis kommunekode fx 3450 og 201)
    • For at øge sandsynligheden for et entydigt match anbefales det at benytte postnummer og kommunekode i stedet for klarskrift
  • Ligeledes kan feltet VEJ enten udfyldes med CPR’s vejkode fx "199" eller med klarskrift fx "Allerødvej"
    • For at øge sandsynligheden for et entydigt match anbefales det at benytte vejkode i stedet for klarskrift
  • HUSNR skal udfyldes
    • Ikke alle grønlandske adresser har et husnummer. I sådanne tilfælde skal HUSNR-feltet udfyldes med adressens bygningsnummer (BNR)
  • ETAGE kan udfyldes, men behøver ikke at være det
  • SIDEDOER kan udfyldes, men behøver ikke at være det

Bemærk dog følgende undtagelser til ovennævnte regler:

• Hvis KUNDEREFNR starter med PNR= opfattes de følgende 10 positioner som et PNR og alle andre identifikationsfelter ignoreres (navn, fødselsdato, køn, adresse)
• Hvis KUNDEREFNR er udfyldt, ikke starter med PNR= og alle andre identifikationsfelter er blanke (køn, fødselsdato, navn, adresse) betragtes forespørgslen som en rekvisition på at få udtrukket data for den person, som har det pågældende KUNDEREFNR
• Hvis en transaktion har ABON_TYPE 4 (sletning af adressematch abonnement) er det kun KUNDEREFNR, der benyttes til identifikation af personen/abonnementet. Eventuelle data i de øvrige identifikationsfelter ignoreres
• Personer med CPR status 50 (slettet personnummer) eller 60 (ændret personnummer) vil aldrig resultere i en matchning og bliver derfor heller aldrig abonnementsat. Det gældende personnummer har overtaget det ændrede/slettede personnummers abonnementer

6. Uddata

Servicen returnerer data i form af fastlængde records. Hvilke records leveres i svaret fra servicen afhænger af kundens opgave konfiguration. I de følgende afsnit beskrives dataformatet for de records, der kan leveres tilbage i responsen.

6.1. Recordtyper (DATA)

Oversigten viser, hvilke records der kan forekomme i DATA recordfeltet.

6.1.1. 000 Startrecord

Start record.

Format:

Recordlængde: 48

6.1.2. 001 Aktuelle data

Aktuelle data record.

Format:

Recordlængde: 404

Feltet ADRNVN kan leveres i formatet Fornavn(e) Efternavn eller Efternavn,Fornavn(e).

På inaktive personer (status 70, 80, eller 90) og personer med vejkode 9900 (status 3 eller 7) leveres ingen aktuel indenlandsk adresse.

Hvis personer har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" medmindre det er aftalt med CPR-kontoret.

MATCHTYP overføres uændret fra input-filen.

6.1.3. 001B Aktuelle data med adresse UUID

Aktuelle data record med adresse UUID.

Format:

Recordlængde: 445

Feltet ADRNVN kan leveres i formatet Fornavn(e) Efternavn eller Efternavn,Fornavn(e).

På inaktive personer (status 70, 80, eller 90) og personer med vejkode 9900 (status 3 eller 7) leveres ingen aktuel indenlandsk adresse.

Hvis personer har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" medmindre det er aftalt med CPR-kontoret.

MATCHTYP overføres uændret fra input-filen.

6.1.4. 002 Udlandsadresser

Udrejse record.

For personer med status 80 - udrejste. På personer med navneadressebeskyttelse leveres ingen udenlandske adresse oplysninger.

Format:

Recordlængde: 209

Hvis personer har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" medmindre det er aftalt med CPR-kontoret.

6.1.5. 003 Kontaktadresser

Kontaktadresse record.

For personer med status 20, 70, 80 eller 90.

Format:

Recordlængde: 209

6.1.6. 004 Civilstand

Civilstand record.

Format:

Recordlængde: 40

Leveres kun til brug vedrørende pension. Det forudsættes, at alle personer under det pågældende kundenummer er pensionskunder.

6.1.7. 005 Værge med text felter

Værge med text felter record.

Format:

Recordlængde: 243

6.1.8. 006 Ægtefælle oplysninger

Ægtefælle oplysninger record.

Format:

Recordlængde: 538

Kan kun vælges til brug vedrørende pension. Leveres kun for afdøde personer.

Hvis ægtefællen har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" jvf. CPR-loven § 38, stk 3.

6.1.9. 011 Flere kunderefnr

Flere kundereferencer record.

Leveres kun, hvis MATCHTYP = T eller R, og den indsendte person allerede findes i abonnement med et eller flere forskellige kundereferencenr. Personens nye kundereferencenr. bliver vist i feltet KUNDEREFNR, og det/de allerede eksisterende kundereferencenr. bliver vist i feltet KUNDEREFNR-ANDET-1. Det vil sige, at der bliver leveret en record 011 for hvert kundereferencenr. der allerede er i abonnement på samme person.

Format:

Recordlængde: 102

6.1.10. 012 Personnummer abonnement

Personnummer abonnement på andet kundenummer record.

Leveres kun, hvis MATCHTYP = E, T eller R. Offentlige kunder kan få udtrukket personnummer på alle udtrukne personer.

Format:

Recordlængde: 37

6.1.11. 013 PNR Oplysninger

Personnummeroplysninger record.

Hvis personen er udtrukket som følge af personnummer.

Format:

Recordlængde: 56

6.1.12. 050 Kreditadvarsel

Kreditadvarsel record

Format:

Recordlængde: 43

6.1.13. 052 Værge med text felter og værgemålstype

Værge med text felter record.

Format:

Recordlængde: 258

6.1.14. 999 Slutrecord

Slut record i et andet format.

Format:

Recordlængde: 34

7. Hjælp

Følgende ressourcer kan bruges hvis der opleves fejl eller problemer med kald til servicen:

• CPR Dokumentationssite
• CPR Direkte kodeeksempler
• CPR Driftsstatus
• CPR Servicedesk

8. Bilag - Abonnementer, krav til adgangskoder og fejlkoder

8.1. Abonnementstyper

Servicen understøtter oprettelse og sletning af både adressematch- og personnnummer-abonnementer i forb. med matchopslag. Abonnementer gøre det muligt for CPRs udtrækskunder at modtage løbende opdateringer på de personer, der findes abonnementer på. Læs mere om abonnementer på CPRs hjemmeside.

Følgende abonnementstype værdier må angives i ABON_TYPE recordfeltet i Match forespørgsel.

• 0: Ingen abonnementhandling
• 1: Opret personnummer-abonnement
• 2: Opret adressematch-abonnement
• 3: Slet personnummer-abonnement
• 4: Slet adressematch-abonnement

Bemærk at abonnementstyper 1 og 3 må kun bruges i forb. med PNR (CPR-nr.) abonnementer dvs. i de tilfælde hvor KUNDEREFNR i Match forespørgsel er et PNR (begynder med PNR=). Ligeledes må abonnementstyper 2 og 4 kun bruges i forb. med matchopslag (KUNDEREFNR i Match forespørgsel er ikke et PNR.)

8.2. Krav til adgangskode/kendord

Password skal være 8 tegn.

• Mindst 1 lille bogstav (a-z)
• Mindst 1 stort bogstav (A-Z)
• Mindst 1 tal (0-9)
• Mindst en speciel karakter: ~ ` ! @ # $ % ^ * ( ) _ - + = , . / \ { } [ ] ; :
• Der er kontrol for store og små bogstaver
• Karaktererne < > & ? ' æ ø og å kan ikke benyttes
• Password kan kun skiftes en gang pr døgn
• Det er ikke tilladt at skifte til et kendeord, som har været benyttet tidligere

8.3. Fejlnumre og fejltekster

Dette afnsit beskriver de mulige fejlnumre, der kan forekomme i FEJLNR feltet i responsen fra servicen fx 00 ("Ingen fejl").

Fejl fra CPR-sikkerhedssystemet under autentifikation:

• 01: BRUGER-ID/KENDEORD ikke korrekt
• 02: KENDEORD udløbet, NYT KENDEORD krævet
• 03: NYT KENDEORD opfylder ikke formatet
• 16: IP-adressen forkert

Fejl fra servicen, der skyldes forkert data i forespørgslen:

• 04: Ikke adgang til CPR (CTSERVICE er midlertidigt lukket)
• 05: PNR ukendt i CPR
• 06: Ukendt KUNDENR
• 07: Timeout / ny LOGON nødvendig
• 08: Ikke adgang til CPR (CTSERVICE er ikke aktiv)
• 10: ABON_TYPE ukendt
• 11: DATA_TYPE ukendt
• 12: KUNDEREFNR. SKAL VÆRE UDFYLDT
• 13: KUNDEREFNR. ER I BRUG TIL ANDEN PERSON
• 14: BRUGER-ID har ikke adgang til transaktionen (CTPROFIL er midlertidigt lukket)
  • eller Sætning af abonnement er ikke tilladt
• 15: Ikke fundet i CTADRAB tabel
• 17: "PNR=" er ikke angivet
• 18: BRUGER-ID har ikke adgang til transaktionen (CTPROFIL er ikke aktiv)
• 19: "PNR=" skal ikke angives til abon.type 2 og 4
• 24: BRUGER-ID har ikke adgang til transaktionen (CTPERSKOD_PROFIL er midlertidigt lukket)
• 28: BRUGER-ID har ikke adgang til transaktionen (CTPERSKOD_PROFIL er ikke aktiv)
• 29: KUNDEREFNR starter med en dato, og det må ikke forekomme til abon.type 2 og 4
• 115: Etage indeholder forkerte bogstaver, tegn eller tal
• 126: Husnummer/-bogstav indeholder forkerte bogstaver,tegn,tal
• 143: Side-dørnummer indeholder forkerte bogstaver, tegn eller tal
• 7015: Postnummer/-distrikt findes ikke i CPR
• 7016: Postdistrikt findes flere gange. Indtast postnr
• 7056: Vejen findes ikke i CPR
• 7100: Der skal være blanke efter indtastet vejkode
• 7102: Indtast køn. M for mand eller K for kvinde
• 7144: Indtast et navn
• 7168: Dato skal være korrekt og mindre eller lig med dags dato
• 7251: Enten personnummer, fødselsdato eller adresse må udfyldes
• 7252: Enten personnummer, fødselsdato eller adresse skal udfyldes
• 7255: Ingen personer opfyldte søgekriterierne. Afgræns anderledes
• 7256: Søgningen giver mere end en person. Afgræns anderledes.
• 7257: Kommune eller postdistrikt skal udfyldes
• 7259: Husnummer skal udfyldes, når vej er udfyldt
• 7578: Kommunen findes ikke i CPR
• 7579: Kommunen er ikke en korrekt kommune
• 7677: Udfyld enten kommune eller postdistrikt
• 7713: Der skal være mindst to uforkortede navne
• 8971: KUNDEREFNR starter med en dato. Det er ikke tilladt

Fejl fra servicen hvor det anbefales, at CPR kontaktes hvis fejlen opstår gentagne gange:

• 40: Opgave findes ikke
• 41: Opgave konfiguration mangler
• 42: Opgave udtræksrelation mangler eller inaktiv
• 43: Opgave version mangler eller inaktiv
• 44: Ingen opgaver fundet for den angivne transaktionskode
• 99: Server fejl. Se log