Snitfladebeskrivelse for WEBService IndkomstEnkeltForespoergsel. KMD Indkomst, P13-5. Version 13.0,

Transkript

1 Snitfladebeskrivelse for WEBService IndkomstEnkeltForespoergsel KD Indkomst, P13-5 Version 13.0,

2 Indholdsfortegnelse Ændringer i forhold til forrige version Brug af snitfladebeskrivelsen Formål og målgrupper Formålet med standardsnitfladen ålgrupper Informationer i snitfladen Servicemål og forretningsmæssigt grundlag Servicemål Forretningsmæssigt grundlag Teknisk implementering Beskrivelse Snitfladeoversigt OIOXL krav Tegnsæt Betingelser for anvendelse af standardsnitfladen Tilslutningsaftale Tilslutningsprøve Garantier Protokol for dataudveksling Forespørgslens dataindhold Data i input Datadefinition I - LaesInput Data i output Datadefinition O LaesOutput Datadefinition L - LaesOutput FeltIndkomstListe Fælles definitioner for LaesInput og LaesOutput Datadefinition F - LaesInput LaesOutput indkomst:funktionkode Validering af data Validering af forespørgselsdata Håndtering af fejl i OIOXL Web service Sikkerhed Autentifikation Autorisation BILAG Bilag 1 SagsområdeKode Bilag 2 eksempler Strukturtegning in - /output KD - Alle rettigheder forbeholdes. Dette materiale er ophavsretligt beskyttet og må ikke kopieres i videre omfang end forudsat i ophavsretsloven.

3 Ændringer i forhold til forrige version Dokumentrevision Dato Udarbejdet af Kommentar Versions nr HHK Første version HHK Beskrivelse af eindkomst er fjernet. 002 Felterne <Timestamp> og <TransaktionsID> er tilføjet beskrivelsen HHK Justeret med kommentarer fra KOBIT & ATP HHK Justeret med kommentarer fra KOBIT & ATP HHK Justeret med kommentarer fra KOBIT modtaget HHK Justeret med kommentarer fra KOBIT modtaget HHK Indarbejdelse af eksempler samt præcisering af sikkerhed, autentifikation og autorisation HHK Justeret som følge af kommentarer fra KOBIT modtaget HHK Opdateret reference på XSD afsnit HHK Justeret som følge af kommentarer fra KOBIT modtaget HHK Justeret som følge af kommentarer fra ATP modtaget HHK Justeret som følge af kommentarer fra ATP modtaget HHK indre (meget små) tekstrettelser 013 Side 2

4 1 Brug af snitfladebeskrivelsen Denne snitfladebeskrivelse er en del af beskrivelsen af snitfladen KD INDKOST, P13-5. Den samlede beskrivelse består af: Snitfladebeskrivelse i sammenhæng. 1 Løsningsbeskrivelsen for KD INDKOST er henvendt til myndigheden (kommune / Udbetaling Danmark). 2 WEBService IndkomstEnkelForespoergsel, som indeholder en beskrivelse af synkrone forespørgsler om indkomstoplysninger. Beskrivelsen er henvendt til myndighedens it-leverandør. 3 QService IndkomstasseForespoergsel, som indeholder en beskrivelse af asynkrone masseforespørgsler om indkomstoplysninger og advis om ændringer i indkomstoplysninger. Beskrivelsen er henvendt til myndighedens it-leverandør. 4 Feltoversigt, som indeholder en liste over de indkomstfelter, som KD INDKOST, P13-5 kan levere. Beskrivelsen er henvendt til myndigheden og til myndighedens it-leverandør. 5 Tegning over sammenhæng mellem Q records (kun QService IndkomstasseForespoergsel). Tegningen er henvendt til myndighedens it-leverandør. 6 Beskrivelse af fejlkoder. Beskrivelsen er en del af aftalen med KD A/S om brug af standardsnitfladen KD INDKOST, P13-5. Udlån til andre leverandører. Løsningsbeskrivelsen, skemaer (WSDL) og datadefinitioner (xsd skemaer) kan ses på KDs kundenet, tryk på link. Den er desuden et praktisk arbejdsredskab til støtte for kommunikationen mellem myndighedens it-leverandør og KD A/S om standardsnitfladens anvendelse. KD forbeholder sig rettighederne til snitfladebeskrivelsen. Snitfladebeskrivelsen kan udlånes af myndigheden til myndighedens it-leverandør i forbindelse med etablering af snitfladen samt ved fremtidige ændringer. Snitfladebeskrivelsen må anvendes af myndigheden og af KOBIT i udbudsmateriale. Henvendelser vedrørende standardsnitfladen rettes til: Team Indkomst Telefon ail [email protected] Kontakt til KD A/S. Side 3

5 2 Formål og målgrupper 2.1 Formålet med standardsnitfladen Formålet med snitfladen er at beskrive kommunikationen mellem et kaldende system og KD Indkomst om synkrone (online) opslag. Snitfladen anvendes til at hente indkomstoplysninger i KD Indkomst om én enkeltperson (der spørges med et enkelt CPR nummer og modtages informationer om et enkelt CPR nummer). Snitfladen håndterer ikke personkredse. Denne service må ikke anvendes til automatiseret masse-kald, og den kan ikke anvendes til bestilling af advisering. Brug i stedet QService IndkomstasseForespørgsel. 2.2 ålgrupper De primære målgrupper er: De ansvarlige for KD Indkomst i KD. Alle myndigheder, som har licens til at bruge KD Indkomst (kommuner, Udbetaling Danmark). yndighedens it-leverandører, der skal bruge denne snitflade ved løsning af en opgave for myndigheden (i det følgende kaldt Anvender ). KOBIT, som har stillet opgaven. 3 Informationer i snitfladen Snitfladen stiller følgende informationer til rådighed: Årsopgørelsesoplysninger, seneste 3 skatteår. Forskudsoplysninger, indeværende år og det kommende skatteår (når dette foreligger). Side 4

6 4 Servicemål og forretningsmæssigt grundlag 4.1 Servicemål Denne snitflade anvender it-systemet KD Indkomst til at skaffe indkomstoplysninger. KD Indkomst anvender services, som SKAT udstiller og er derved underlagt de muligheder og begrænsninger, som dette medfører. 4.2 Forretningsmæssigt grundlag Denne snitflade leverer data fra følgende registre: SKATs forskudsregister, som afvikles hos SKATs it-leverandør. Kopi af årsopgørelsesregistret fra SKAT, som føres på KD. an kan læse mere om KD Indkomst på KD s kundenet under Systembrugere KD Indkomst. 5 Teknisk implementering 5.1 Beskrivelse Denne snitflade leverer indkomstoplysninger på anfordring. Anvender skal i hver forespørgsel identificere sig med certifikat, som beskrevet i afsnit I forespørgslen angiver Anvender, hvilken person, hvilke oplysninger og for hvilken periode, der ønskes oplysninger om. Endvidere angives det formål, hvortil oplysningerne skal anvendes. Snitfladen giver adgang til de under afsnit 3 nævnte indkomstoplysninger. Fejlbehæftede forespørgsler afvises med angivelse af årsag. Webservicekaldet mellem det kaldende system og denne snitflade foregår synkront, og webservicen holder derfor forbindelsen åben i det tidsrum, hvor forespørgslen kontrolleres og svaret er sendt retur. Der er i KD Indkomst indlagt en generel time-out-tid på 30 sekunder mellem KD og SKAT. Forespørgsler, der ikke kan afvikles inden for dette tidsrum, stoppes. Løsningen herpå er at brugeren kalder WEBServicen igen. 5.2 Snitfladeoversigt WEBService: IndkomstEnkeltForespoergsel Der er 1 metode til servicen: IndkomstEnkeltForespoergsel: Henter Forskudsopgørelse eller Årsopgørelse for én person. Side 5

7 5.3 OIOXL krav Webservicen skal opfylde kravene givet fra OIOXL. Der er ikke krav i OIOXL for Indkomstområdet. Det betyder, at alle beskrevne felter betragtes som lokale KD udvidelser. Formatangivelser i skemadefinitionen hentes fra disse namespaces: Namespace Skemadefinition for namespace xs indkomst urn:oio:kmd:indkomst: Tegnsæt OIOXL standarden specificere at der skal benyttes UTF-8 ved kald af KD WEBServicen IndkomstEnkeltForespoergsel. Side 6

8 6 Betingelser for anvendelse af standardsnitfladen 6.1 Tilslutningsaftale Anvender skal indgå aftale med KD om anvendelse af denne løsning. Anvender må kun anvende løsningen for de yndigheder, som Anvender har indgået aftale med. Anvender forpligter sig til kun at kommunikere om personer, der er dækket af den indgåede aftaler. Det er Anvenders ansvar at føre logning af de slutbrugere og it-løsninger, der anvender denne løsning via Anvenders it-løsning. yndigheden som Anvender er it-leverandør for, skal have indgået de nødvendige aftaler med SKAT og KD for at snitfladen kan fungere. Se Løsningsbeskrivelsen. 6.2 Tilslutningsprøve Det er en forudsætning, at der er foretaget en teknisk afprøvning, inden snitfladen kan tages i anvendelse af Anvender. 7 Garantier KD forpligter sig til at vedligeholde standardsnitfladen i overensstemmelse med transitionsaftalen (TSA) med KOBIT. Ændringer i snitfladen varsles med 3 måneder. Ved lovændringer, der påvirker anvendelsen af snitfladen, kan de 3 måneders varsel bortfalde. Side 7

9 8 Protokol for dataudveksling Denne datastruktur skal anvendes. Skema Anvendelse INDKOST_v009.xsd Beskriver OIOXL formaterne for forespørgslens og svarets dataindhold. Namespace indkomst: OIOXL, der indeholder forespørgsel eller svar, skal kunne validere op mod skemaet INDKOST_v009.xsd. Skemaerne kan rekvireres på KDs kundenet, tryk på link. Dataelementerne har mulighed for en markering af: /O Betydning andatory Krævet felt O Optional Ikke krævet felt * Iteration. Datastruktur, der gentages 8.1 Forespørgslens dataindhold OIOXL strukturerne til dataudveksling er beskrevet i følgende skemaer: Datadefinition Datadel Anvendelse Forespørgsel I LaesInput LaesInput Svar O LaesOutput LaesOutput L FeltIndkomstListe LaesOutput Fælles definitioner for forespørgsel og svar F FunktionKode LaesInput og LaesOutput Side 8

10 8.2 Data i input. Overordnet datastruktur for input til WEBService IndkomstEnkeltForespoergsel ifølge gældende xsd skema INDKOST i KD. Strukturtegning findes i bilag 3, strukturtegning input/output Datadefinition I - LaesInput Navn /O Forklaring Format Timestamp Timestamp for forespørgslen genereres af Anvender datetime TransaktionsId Unik transaktionsid genereres af Anvender. Genereres efter Anvenders valg af standard. string Eksempel: de305d54-75b4-431b-adb2- eb6b9e Feltets indhold valideres ikke af WEBService: IndkomstEnkeltForespoergsel. indkomst: PartIdentifikator CPR-nummer på den person, der forespørges på følger OIO CPR standard. string Indkomst: yndighed Eksempel: CVR-nummer på forespørgende myndighed følger OIO CVR standard. string indkomst: SagsomraadeKode Eksempel: Angiver det sagsområde, som oplysninger skal bruges til. Eksempel: "Social pension" Se Bilag 1 SagsomraadeKode string indkomst: FunktionKode Kombinationen af Anvender (udledes af KD af logon), Sagsområde, yndighed og Funktion skal være registreret i KD Indkomst Anvender-register. Angiver det register der ønskes informationer fra - enten Forskudsopgørelse eller Årsopgørelse. Se datadefinition på FunktionKode i fælles tabel F for LaesInput og LaesOutput Side 9

11 8.3 Data i output. Overordnet datastruktur for output fra WEBService IndkomstEnkeltForespoergsel ifølge gældende xsd skema INDKOST i KD. Strukturtegning findes i bilag 3, strukturtegning input/output Datadefinition O LaesOutput Navn /O Forklaring Format indkomst:standar dretur indkomst:statusk ode indkomst:statust ekst Kode der bekskriver forespørgslens status. Beskrivelser af statuskoder og tekster er tilgængeligt på KD kundenet.dk integer O Beskrivelse af StatusKode. string Nedenstående felter (angivet med ) udfyldes med værdier fra forespørgslen. Timestamp Timestamp for forespørgslen genereret af Anvender i datetime forbindelse med forespørgslen. TransaktionsId Unik transaktionsid genereret af Anvender i forbindelse string med forespørgslen. indkomst:partiden tifikator Personnummer på den person, der forespørges på følger OIO CPR standard. string indkomst:yndigh ed Eksempel: CVR nummer på forespørgende myndighed følger OIO CVR standard. string indkomst:funktion Kode Eksempel: Angiver det register der ønskes informtioner fra - enten Forskudsopgørelse eller Årsopgørelse. indkomst:sagsom raadekode Se datadefinition på FunktionKode i fælles tabel F for LaesInput og LaesOutput. Angiver det sagsområde, som oplysninger skal bruges til. Eksempel: "Social pension" string Se Bilag 1 SagsomraadeKode indkomst: AegtefaellePartIde ntifikator indkomst:feltindk omstliste O Kombinationen af Anvender (udledes af KD af logon), Sagsområde, yndighed og Funktion skal være registreret i KD Indkomst Anvender-register. Personnummer på ægtefællen til forespurgte person følger string OIO CPR standard. I tilfælde af ingen ægtefælle, udfyldes med Eksempel: FeltIndkomstListe indeholder oplysninger om et variabelt antal felter (FeltIndkomst). Se datadefinition på FeltIndkomstListe i fælles tabel L for LaesOutput Side 10

12 8.3.2 Datadefinition L - LaesOutput FeltIndkomstListe Datastruktur L for returneret liste af indkomstfelter i svar. Navn /O Forklaring Format indkomst:feltindk omstliste FeltIndkomstListe indeholder oplysninger om et variabelt antal felter (FeltIndkomst). indkomst:feltindk * 0:N Forekommer fra 0 til ubegrænset antal gange omst indkomst:felttype Oplyser om typen af værdien i FeltVaerdi. integer Udfyldes med 1 for kode/tekst 2 for dage 3 for beløb/antal/år indkomst:feltnum merkode Entydig identifikation af feltet. Angives med op til fem tegn. integer Eksempelvis: 24 indkomst:feltlede tekst Kort forklarende tekst til feltets indhold. string Indkomst:FeltTyp evaerdi Udfyldes med værdi afhængig af hvad der er angivet i indkomst:felttype string Ved Felttype 1 : Teksten behandles som en string. Ved Felttype 2 : Værdien er et heltal. Der anvendes ikke 1000-talsseparatorer. Ved Felttype 3 : Såfremt værdien har decimaler anvendes punktum (. ) som decimalseparator. Der anvendes ikke 1000-talsseparatorer. Side 11

13 8.4 Fælles definitioner for LaesInput og LaesOutput Datadefinition F - LaesInput LaesOutput indkomst:funktionkode Navn /O Forklaring Format indkomst:funktion Kode indkomst:forskud sopgoerelse indkomst:aarsopg oerelse indkomst:aarstali dentifier Angiver det register der ønskes informtioner fra - enten Forskudsopgørelse eller Årsopgørelse. Oplysninger leveres om det år som er angivet i feltets værdi. For gyldige værdier se afsnit 3 Informationer i snitfladen. gyear Eksempel: Side 12

14 9 Validering af data 9.1 Validering af forespørgselsdata De forretningsmæssige valideringer kan inddeles i: Simpel validering: Datatyper, formater, mandatory data, værdisæt herunder grænseværdier og tilladte værdier fra kodelister, samt periodetjek. Udvidet validering: Sammenhængsvalidering og validering mod tabeller i KD Indkomst. Regler for feltudfyldelse og datatyper fremgår af tabeller over datastrukturerne for WEBServicemetode i Forespørgslens dataindhold i afsnittet Protokol for dataudveksling. 9.2 Håndtering af fejl i OIOXL Web service Der kan opstå tre forskellige typer af fejl i forbindelse med kald til KD WEBService IndkomstEnkeltForespoergsel: Transportorienterede fejl i forbindelse med eksekvering af den startede transaktion, f.eks. at dele af den benyttede infrastruktur ikke er tilgængelig eller tekniske fejl. Skemavalideringsfejl, hvor den modtagne besked ikke opfylder de krav til format og indhold, som er stillet i den kaldte service skemadefinition. Forretningsmæssige fejl, hvor den modtagne besked ikke opfylder de krav til indhold og formalia, som er beskrevet i afsnit 8.2. Sekvensen for validering er flg.: 1. Den indkomne beskeds signatur valideres 2. Beskedens indhold valideres op mod de gældende skemadefinitioner 3. Beskedens indhold valideres efter forretningsmæssige regler Kun hvis der ikke er konstateret fejl i et trin, fortsættes til næste valideringstrin. Det betyder, at en besked kan indeholde flere fejl end der gives besked om. Side 13

15 10 Sikkerhed KD s standard for autentifikation og autorisation anvendes Autentifikation Når en 3. part service benytter KD WEBService IndkomstEnkeltForespoergsel er der krav til Autentifikation og Autorisation til denne snitflade. Kommunikationen mellem Anvender og KD følger OWSA-T modellen i for sikker kommunikation mellem Serviceaftager og Serviceudbyder baseret på SSLkryptering samt autentifikation og autorisation via Anvenders OCES virksomhedscertifikat indsat i SOAP http-kontekst Autorisation Som beskrevet i afsnit 5.1 oversættes det OCES virksomhedscertifikat, som benyttes af Anvender til en systembruger defineret i KD s sikkerhedssystem (KSP/CICS). Systembrugeren repræsenterer Anvender, og KD sikrer ved indgåelse af anvenderaftale med serviceaftageren, at den relevante bruger er oprettet og givet de nødvendige rettigheder til at kunne konsumere snitfladen. i OWSA-T modellen definerer Anvender som Serviceaftager og KD som Serviceudbyder. Side 14

16 11 BILAG 11.1 Bilag 1 SagsområdeKode Angiver det sagsområde, som oplysninger skal bruges til. SagsomraadeKode Aktiv beskæftigelsesindsats Boliganvisning Boligstøtte Børnebidrag Børnetilskud Dagpenge ved barsel Dagpenge ved sygdom Delpension Fleksydelse Introduktionsydelse Opkrævning af sociale og beskæftigelsesmæssige ydelser Repatriering Social pension Social service Økonomisk friplads 11.2 Bilag 2 eksempler Eksempelfiler er tilgængelig på KD kundenet Strukturtegning in - /output Strukturtegninger Input HTL Document Output HTL Document Side 15