Snitfladebeskrivelse for WEBService IndkomstEnkeltForespoergsel KD Indkomst Opgørelser (P13-5) Version 1.0, 21.02.2017
Indholdsfortegnelse 1 Versionsoversigt... 2 2 Brug af snitfladebeskrivelsen... 3 3 Formål og målgrupper... 4 3.1 Formålet med standardsnitfladen... 4 3.2 ålgrupper... 4 4 Informationer i snitfladen... 5 5 Servicemål og forretningsmæssigt grundlag... 6 5.1 Servicemål... 6 6 Teknisk implementering... 7 6.1 Beskrivelse... 7 6.2 Snitfladeoversigt... 7 6.3 OIOXL krav... 7 6.4 Tegnsæt... 8 7 Betingelser for anvendelse af standardsnitfladen... 9 7.1 Tilslutningsaftale... 9 7.2 Logning... 9 7.3 Tilslutningsprøve... 9 8 Garantier... 10 9 Protokol for dataudveksling... 11 9.1 Forespørgslens dataindhold... 11 9.2 Data i input.... 12 9.2.1 Datadefinition I - LaesInput... 12 9.3 Data i output.... 13 9.3.1 Datadefinition O LaesOutput... 13 9.3.2 Datadefinition L - LaesOutput FeltIndkomstListe... 14 9.4 Fælles definitioner for LaesInput og LaesOutput... 15 9.4.1 Datadefinition F - LaesInput LaesOutput indkomst:funktionkode... 15 10 Validering af data... 16 10.1 Validering af forespørgselsdata... 16 10.2 Håndtering af fejl i OIOXL Web service... 16 11 Sikkerhed... 17 11.1 Autentifikation... 17 11.2 Autorisation... 17 12 BILAG... 18 12.1 Bilag 1 Sagsområde... 18 12.2 Bilag 2 eksempler... 18 12.3 Strukturtegning in - /output... 19 KD INDKOST OPGØRELSER Side 1 af 20
1 Versionsoversigt Dokumentrevision Dato Udarbejdet af Kommentar Versions nr. 21-02-2017 HHK Første version. 001 KD INDKOST OPGØRELSER Side 2 af 20
2 Brug af snitfladebeskrivelsen Snitfladebeskrivelsen må anvendes af myndigheden og af KOBIT i udbudsmateriale. 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. Henvendelser vedrørende standardsnitfladen rettes til: Team Indkomst Telefon 4460 1077 ail kmdindkomst@kmd.dk KD INDKOST OPGØRELSER Side 3 af 20
3 Formål og målgrupper 3.1 Formålet med standardsnitfladen Formålet med snitfladen er at beskrive kommunikationen mellem et kaldende system og KD Indkomst Opgørelser om synkrone (online) opslag. Denne service må ikke anvendes til automatiseret masse-kald, og den kan ikke anvendes til bestilling af advisering. Snitfladen håndterer ikke personkredse. Brug i stedet QService IndkomstasseForespørgsel. 3.2 ålgrupper De primære målgrupper er: Alle myndigheder, som har licens til at bruge KD Indkomst Opgørelser (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 ). De ansvarlige for KD Indkomst Opgørelser i KD A/S. KD INDKOST OPGØRELSER Side 4 af 20
4 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). Se feltbeskrivelser i KDIndkomstOpgørelser-Feltoversigt KD INDKOST OPGØRELSER Side 5 af 20
5 Servicemål og forretningsmæssigt grundlag 5.1 Servicemål Denne snitflade anvender it-systemet KD Indkomst Opgørelser til at skaffe indkomstoplysninger. KD Indkomst Opgørelser anvender services, som SKAT udstiller og er derved underlagt de muligheder og begrænsninger, som dette medfører. KD INDKOST OPGØRELSER Side 6 af 20
6 Teknisk implementering 6.1 Beskrivelse Denne snitflade leverer indkomstoplysninger på anfordring. Anvender skal i hver forespørgsel identificere sig med certifikat, som beskrevet i afsnit 11.2. 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. Anvender valideres på KD side via KSP/CICSsystemet. Snitfladen giver adgang til de under afsnit 4 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 Opgørelser 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. 6.2 Snitfladeoversigt WEBService: IndkomstEnkeltForespoergsel Der er 1 metode til servicen: IndkomstEnkeltForespoergsel: Henter Forskudsopgørelse eller Årsopgørelse for én person. 6.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 http://www.w3.org/2001/xlschema indkomst urn:oio:kmd:indkomst:1.0.0 KD INDKOST OPGØRELSER Side 7 af 20
6.4 Tegnsæt OIOXL standarden specificerer at der skal benyttes UTF-8 ved kald af KD WEBServicen IndkomstEnkeltForespoergsel. KD INDKOST OPGØRELSER Side 8 af 20
7 Betingelser for anvendelse af standardsnitfladen 7.1 Tilslutningsaftale yndighed skal indgå aftale med KD om anvendelse af denne løsning. 7.2 Logning Det er Kundens ansvar at føre logning af de slutbrugere og it-løsninger, der anvender denne løsning via Anvenders it-løsning. 7.3 Tilslutningsprøve Det er en forudsætning, at der er foretaget en teknisk afprøvning, inden snitfladen kan tages i anvendelse af Anvender. KD INDKOST OPGØRELSER Side 9 af 20
8 Garantier KD forpligter sig til at vedligeholde standardsnitfladen i overensstemmelse med transitionsaftalen (TSA) med KOBIT. KD INDKOST OPGØRELSER Side 10 af 20
9 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. Dataelementerne har mulighed for en markering af: /O Betydning andatory Krævet felt O Optional Ikke krævet felt * Iteration. Datastruktur, der gentages 9.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 KD INDKOST OPGØRELSER Side 11 af 20
9.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. 9.2.1 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- eb6b9e546014 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: 1234567890 CVR-nummer på forespørgende myndighed følger OIO CVR standard. string indkomst: SagsomraadeKode Eksempel: 12345678. 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 Opgørelser 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 KD INDKOST OPGØRELSER Side 12 af 20
9.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. 9.3.1 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: 1234567890 CVR nummer på forespørgende myndighed følger OIO CVR standard. string indkomst:funktion Kode Eksempel: 12345678. 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 Opgørelser Anvender-register. Personnummer på ægtefællen til forespurgte person følger string OIO CPR standard. I tilfælde af ingen ægtefælle, udfyldes med 000000000. Eksempel: 1234567890 FeltIndkomstListe indeholder oplysninger om et variabelt antal felter (FeltIndkomst). Se datadefinition på FeltIndkomstListe i fælles tabel L for LaesOutput KD INDKOST OPGØRELSER Side 13 af 20
9.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 tekst, kan indeholde en tekst på op til 40 tegn. 2 for heltal, kan være i mellem -32768 32768. 3 for decimaltal, skal være i mellem -9999999999999.99-9999999999999.99. 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. I nogle tilfælde String indeholder dette felt også felt-værdien: I det tilfælde er feltværdien også angivet i nedenstående felt. 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 kun negativt tal er der foranstillet fortegn, ved positivt tal intet fortegn. Ved Felttype 3 : Værdien er et decimaltal. Der anvendes punktum (. ) som decimalseparator. Der anvendes ikke 1000-talsseparatorer. Ved kun negativt tal er der foranstillet fortegn, ved positivt tal intet fortegn. Hvis årstal angives med felttype 3, så vil årstallet være med 2 decimaler. KD INDKOST OPGØRELSER Side 14 af 20
9.4 Fælles definitioner for LaesInput og LaesOutput. 9.4.1 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: 2014. KD INDKOST OPGØRELSER Side 15 af 20
10 Validering af data 10.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 Opgørelser. Regler for feltudfyldelse og datatyper fremgår af tabeller over datastrukturerne for WEBServicemetode i Forespørgslens dataindhold i afsnittet Protokol for dataudveksling. 10.2 Håndtering af fejl i OIOXL Web service Der kan opstå tre forskellige typer af fejl i forbindelse med kald til KD Indkomst Opgørelser 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 9.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. KD INDKOST OPGØRELSER Side 16 af 20
11 Sikkerhed KD s standard for autentifikation og autorisation anvendes. 11.1 Autentifikation Når en 3. part service benytter KD Indkomst Opgørelser WEBService IndkomstEnkeltForespoergsel er der krav til Autentifikation og Autorisation til denne snitflade. Kommunikationen mellem Anvender og KD Indkomst Opgørelser følger OWSA-T modellen i for sikker kommunikation mellem Serviceaftager og Serviceudbyder baseret på SSL-kryptering samt autentifikation og autorisation via Anvenders OCES virksomhedscertifikat indsat i SOAP http-kontekst. Webservice URL: https://intewswlbswm2q2012.kmd.dk/kd.ay.ews.indkomstenkeltforespoergsel_001/indkomstenke ltforespoergsel.svc WSDL kan rekvireres ved henvendelse til KD. 11.2 Autorisation Det OCES virksomhedscertifikat, som benyttes af Kunden, oversættes til en systembruger defineret i KD s sikkerhedssystem (KSP/CICS). Systembrugeren repræsenterer Kundens fagsystem, og KD sikrer ved indgåelse af tilslutningsaftale, at den relevante bruger er oprettet og er givet de nødvendige rettigheder til at kunne benytte snitfladen. i OWSA-T modellen definerer Anvender som Serviceaftager og KD som Serviceudbyder. KD INDKOST OPGØRELSER Side 17 af 20
12 BILAG 12.1 Bilag 1 Sagsområde Angiver det sagsområde, som oplysninger skal bruges til samt den information forespørgslen skal indeholde. SKAT Sagsområde 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 samt familieydelser Repatriering Social pension, herunder folkepension, førtidspension og opsat pension Social service Økonomisk friplads Aktivbeskæftigelsesindsats Boliganvisning Boligstøtte Børnebidrag Børnetilskud Dagpengevedbarsel Dagpengevedsygdom Delpension Fleksydelse Introduktionsydelse Opkrvafsocialeogbeskæftigelsesmæssigeydelser Repatriering Socialpension Socialservice Økonomiskfriplads 12.2 Bilag 2 eksempler Eksempelfiler er også tilgængelige på KDs kundenet. Input input_v004.xml Output fejl Output - Fejl_v004.xml Output Output_v004.xml Outputfeltliste WHEN('Økonomiskfriplads') do; INPUT_DATA.SAGSORÅDE = 'F'; WHEN('Boligstøtte') do; INPUT_DATA.SAGSORÅDE = 'B'; OutputFeltListe_v005.xml KD INDKOST OPGØRELSER Side 18 af 20
WHEN('Dagpengevedsygdom') do; INPUT_DATA.SAGSORÅDE = 'D'; WHEN('Dagpengevedbarsel') do; INPUT_DATA.SAGSORÅDE = 'N'; WHEN('Aktivbeskæftigelsesindsats') do; INPUT_DATA.SAGSORÅDE = 'C'; WHEN('Introduktionsydelse') do; INPUT_DATA.SAGSORÅDE = 'L'; WHEN('Repatriering') do; INPUT_DATA.SAGSORÅDE = ''; WHEN('Fleksydelse') do; INPUT_DATA.SAGSORÅDE = 'E'; WHEN('Socialpension') do; INPUT_DATA.SAGSORÅDE = 'A'; WHEN('Delpension') do; INPUT_DATA.SAGSORÅDE = 'K'; WHEN('Socialservice') do; INPUT_DATA.SAGSORÅDE = 'G'; WHEN('Børnetilskud') do; INPUT_DATA.SAGSORÅDE = 'H'; WHEN('Børnebidrag') do; INPUT_DATA.SAGSORÅDE = 'O'; WHEN('Opkrvafsocialeogbeskæftigelsesmæssigeydelser') do; INPUT_DATA.SAGSORÅDE = 'I'; WHEN('Boliganvisning') do; INPUT_DATA.SAGSORÅDE = 'J'; 12.3 Strukturtegning in - /output Strukturtegninger Input HTL Document Output HTL Document KD INDKOST OPGØRELSER Side 19 af 20