- beskrivelse af snitflader

Transkript

1 - beskrivelse af snitflader

2 1. Indholdsfortegnelse 1. Indholdsfortegnelse Ændringer Læsevejledning Tilmeldingslisten Materiale-indlæsningsfilen Fejl- og kvitteringslisterne Returkoder og -tekst Feltbeskrivelser Specifikt for kunder der genererer data på mainframe Specifikt for kunder der genererer data på PC Konverteringstabel

3 2. Ændringer Rettet beskrivelse af e-boks i ASCII format Tilføjet fejlkode 16 i fejliste Rettet ASCII til EBCDIC i afsnit Tilføjet returkode 17 3

4 3. Læsevejledning Dokumentet beskriver de snitflader der er mellem kunderne og e-boks, jf. nedenstående diagram. Afsnittene er en generel beskrivelse af snitfladerne, mens afsnittene 8. og 9. specifikt omhandler de forhold der gør sig gældende når kunden genererer data på en mainframe henholdsvis PC. Afsnit 4. omhandler feltbeskrivelserne som bør gennemlæses først. 4

5 4. Tilmeldingslisten Tilmeldingslisten er den fil, som indholder: tilmeldte brugere (identificeret ved cpr-/cvr-nummer) til et dokument (identificeret ved materiale-identen) fra en given kunde (identificeret ved kunde-nr.). Filen sendes fra e-boks til kunden. Hver fil indeholder én headerrecord, et antal parameterrecords (én parameterrecord pr. modtager (person og/eller virksomhed)) og én trailerrecord. På næste side ses en grafisk fremstilling og et eksempel på filens opbygning. Headerrecord længde 100 Rec-type String 8 Altid 'EBOKS001' Struktur-version String 3 Pt. '004' Data-type String 30 Her 'Tilmeldingsliste' Kunde-nr String 15 Kunde-nr. hos e-boks. Højrestillet med foranstillede 0. Indholdet er pt. nummerisk. Timestamp String 26 Dannelsestidspunkt f.eks Filler String 18 Er udfyldt med blanke Parameterrecord længde 100 Rec-type String 8 Altid 'EBOKS002' Struktur-version String 3 Pt. '005' Materiale-ident String 15 Nummer, som entydigt definerer et dokument i e-boks. Indholdet er pt. nummerisk og angives højrestillet med foranstillede 0. Ident-type String 20 P for cpr-nummer, V for cvr-nummer Venstrestillet med efterfølgende blanke Ident String 50 Identifikation af modtager (cpr-nummer eller cvr-nummer) Venstrestillet med efterfølgende blanke Nationalitet String 2 Landekode på bruger ifølge ISO Danmark = DK Filler String 2 Er udfyldt med blanke Trailerrecord længde 100 Rec-type String 8 Altid 'EBOKS003' Struktur-version String 3 Pt. '003' Antal parameterrecords String 15 Antallet af (førnævnte) parameterrecords Filler String 74 Er udfyldt med blanke 5

6 Grafisk fremstilling af tilmeldingsliste: en hel fil for tilmeldingslisten headerrecord parameterrecord n trailerrecord - én for hver ident Eksempel på tilmeldingsliste: EBOKS001004Tilmeldingsliste EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS P DK EBOKS Eksemplet viser en tilmeldingsliste med to materiale-identer (13029 og 13030). Tilmeldingslisten er altid en totalliste. 6

7 5. Materiale-indlæsningsfilen Kunden genererer materiale-indlæsningsfilen og sender den til e-boks. I filen er der - overordnet set - fire væsentlige oplysninger: 1) identifikation af hvilke modtagere der skal have dokumentet (identificeret ved cpr-/cvr-nummer) 2) hvilket dokument der er tale om (materiale-identen) 3) hvornår dokumentet skal være synligt i modtagernes e-bokse (valørdato) 4) selve PDF-dokumentet. Materiale-indlæsningsfilen består af 1 headerrecord. Pr. dokument: 1 parameterrecord + 1 datastartrecord + et antal datarecords + 1 dataslutrecord 1 trailerrecord. Nedenstående figur viser materiale-indlæsningsfilen grafisk uden ekstrabruger-record: headerrecord parameterrecord en hel fil for materialeindlæsning datastartrecord datarecord dataslutrecord trailerrecord = PDF-dokumentet Ekstrabruger-record e-boks giver også mulighed for at flere forskellige modtagere kan modtage det samme dokument. Det er bl.a. relevant ifm. fælleskonti eller foreninger. Til det formål benyttes ekstrabruger-recorden. Der kan maksimalt tilføjes 9 ekstrabruger-records til én parameterrecord. 1 headerrecord. Pr. dokument - (1 parameterrecord + et antal ekstrabruger-record + 1 datastartrecord + et antal datarecords + 1 dataslutrecord). 1 trailerrecord. Nedenstående figur er en grafisk fremstilling af materiale-indlæsningsfilen med ekstrabruger-record: headerrecord parameterrecord ekstrabruger-record en hel fil for materialeindlæsningen incl. ekstrabruger-record = et antal ekstrabruger-record datastartrecord datarecord = PDF-dokumentet dataslutrecord trailerrecord 7

8 Generelt Alle dokumenter med tilhørende parameterrecords samles i én fil. Filen starter med én headerrecord og slutter med én trailerrecord, der begge indeholder information om filens indhold. Parameterrecorden anvendes bl.a. til at beskrive modtageren af et dokument. Er der flere modtagere af det samme PDF-dokument tilføjes et antal ekstrabruger-records (svarende til det ekstra antal modtagere) efter parameterrecorden (den første modtager). Datastartrecorden er en identifikation på at efterfølgende record er starten på et givet dokument. Dataslutrecorden er en identifikation på at forrige record var sidste record i et dokument. I dataslutrecorden skal også angives det antal byte PDF-dokumentet fylder. Til sidst sluttes af med én trailerrecord, som indeholder det samlede antal identer og det samlede antal records alt inklusive. Det samlede antal identer svarer til det totale antal brugere, som er modtagere af et dokument. Headerrecord, parameterrecord, ekstrabrugerrecord, datastartrecord og slutrecord og trailerrecord skal alle være i EBCDIC-format 1, mens alle datarecords skal indeholde PDF-dokumentet i ASCII-format. Hvis filen fylder mere end bytes Hvis PDF-dokumentet fylder mere end byte, skal dokumentet deles i flere datarecords. Det er ikke et krav, at den enkelte datarecord skal fylde præcis bytes. Det er således tilladt at opdele PDFdokumentet i datarecords, der fylder mindre end bytes. Er dokumentet mindre end bytes må de resterende bytes ikke påsættes i form af blanke eller andet så længden bliver Nedenstående eksempel viser opbygningen af en fil, der indeholder to PDF-dokumenter - ét på bytes og ét på (der er ikke benyttet ekstra brugerrecord): oplysninger om indholdet af filen headerrecord parameterrecord datastartrecord første dokument med parameterrecord PDF-dokument (de første bytes) PDF-dokument (de resterende bytes) dataslutrecord en fil med alle dokumenter parameterrecord datastartrecord andet dokument med parameterrecord PDF-dokument bytes dataslutrecord oplysninger om indholdet af filen trailerrecord 1 Se afsnit 10. Konverteringstabel for hex-konvertering fra ASCII til EBCDIC. 8

9 Headerrecord længde 82 Rec-type String 8 Altid 'EBOKS004' Struktur-version String 3 Recordversion. Pt. 004 Data-type String 30 Her 'Data til e-boks' Kunde-nr String 15 Kunde-nr. hos e-boks. Højrestillet med foranstillede 0. Indholdet skal pt. være nummerisk. Timestamp String 26 Dannelsestidspunkt f.eks Parameterrecord længde 295 Rec-type String 8 Altid 'EBOKS005' Struktur-version String 3 Recordversion. Pt. 005 Materiale-ident String 15 Nummer, som entydigt definerer et dokument i e-boks. Indholdet skal pt. være nummerisk og angives højrestillet med foranstillede 0 Ident-type String 20 P for cpr-nummer, V for cvr-nummer Venstrestillet med efterfølgende blanke Ident String 50 Identifikation af modtager (cpr-nummer eller cvr-nummer) Venstrestillet med efterfølgende blanke Nationalitet String 2 Landekode på bruger ifølge ISO Danmark = DK Valørdato String 10 Formatet er: YYYY-MM-DD. Må max ligge 45 dage frem i tiden. Materialebeskrivelse String 50 Er valgfri for kunden. Teksten sættes sammen med den faste tekst (bør venstrestilles) Materialetype String 10 Altid 'PDF' Leverandør_identifikation String 30 Kunden vælger selv indhold (bør venstrestilles) Antal bilag String 2 Numerisk Bilags-id 1-10 String 80 Bilag_id'et er på otte karakterer. Her er mulighed for at angive 10 bilag. Bilag_id'erne angives uden at separere. Selve bilag_id'erne skal bestilles hos e-boks Filler String 15 Skal udfyldes med blanke Ekstrabrugerrecord længde 83 Rec-type String 8 Altid 'EBOKS013' Struktur-version String 3 Recordversion. Pt. 004 Ident-type String 20 P for cpr-nummer, V for cvr-nummer Venstrestillet med efterfølgende blanke Ident String 50 Identifikation af modtager (cpr-nummer eller cvr-nummer) Venstrestillet med efterfølgende blanke Nationalitet String 2 Landekode på bruger ifølge ISO Danmark = DK 9

10 Datastartrecord længde 11 Rec-type String 8 Altid 'EBOKS014' Struktur-version String 3 Recordversion. Pt. 004 Datarecord længde Areal String Variabel længde max byte Dataslutrecord længde 26 Rec-type String 8 Altid 'EBOKS015' Struktur-version String 3 Recordversion. Pt. 005 Ant_byte String 15 Antal byte i PDF-dokumentet Trailerrecord længde 41 Rec-type String 8 Altid 'EBOKS007' Struktur-version String 3 Recordversion. Pt. 003 Antal parameterrecord String 15 Antallet af dokumenter Antal records String 15 Samlet antal records i filen 10

11 6. Fejl- og kvitteringslisterne Fejl- og kvitteringslisterne indeholder oplysninger om hvorvidt indlæsningen af dokumenter i e-boks er gået godt eller på fejl. Om en ident (cpr.-nr. eller cvr.-nr.) fremgår af kvitteringslisten eller fejllisten afhænger af returkoden. Er returkoden = 0 ( indsættelsen er foretaget ) fremgår identen (modtageren) af kvitteringslisten. Er returkoden 0 fremgår identen af fejllisten. Nedenstående records indeholdes i både fejl- og kvitteringslisten. Der genereres således to lister ud fra de samme records. Hver fil indeholder én headerrecord, et antal parameterrecords (én parameterrecord pr. modtager (person og/eller virksomhed)) og én trailerrecord. Filerne sendes fra e-boks til kunden. Headerrecord længde 197 Rec-type String 8 Altid 'EBOKS008' Struktur-version String 3 Recordversion. Pt. 005 Data-type String 30 Kvitteringsliste / Fejlliste Kunde-nr String 15 Kunde-nr. hos e-boks. Højrestillet med foranstillede 0. Indholdet er pt. nummerisk. Timestamp String 26 Dannelsestidspunkt. F.eks Filler String 100 Er udfyldt med blanke Parameterrecord længde 197 Rec-type String 8 Altid 'EBOKS009' Struktur-version String 3 Recordversion. Pt. 005 Materiale-ident String 15 Nummer, som entydigt definerer et dokument i e-boks. Indholdet er pt. nummerisk og angives højrestillet med foranstillede 0. Ident-type String 20 P for cpr-nummer, V for cvr-nummer Venstrestillet med efterfølgende blanke Ident String 50 Identifikation af modtager (cpr-nummer eller cvr-nummer) Venstrestillet med efterfølgende blanke Nationalitet String 2 Landekode på bruger ifølge ISO Danmark = DK Leverandør-identifikation String 30 e-boks returnerer den tekst der blev medsendt i filen Mat-længde String 15 Længde pr. indlagt dokument i antal byte Returkode String 2 e-boks returnerer returkode Returtekst String 52 e-boks returnerer returtekst Trailerrecord længde 197 Rec-type String 8 Altid 'EBOKS010' Struktur-version String 3 Recordversion. Pt. 005 Antal Identer String 15 Antal fejl/kvitteringer Filler String 156 Er udfyldt med blanke 11

12 Eksempel på kvitteringsliste: EBOKS008005Kvitteringsliste EBOKS P DK Indsættelsen er foretaget EBOKS P DK Indsættelsen er foretaget EBOKS P DK Indsættelsen er foretaget EBOKS P DK Indsættelsen er foretaget EBOKS P DK Indsættelsen er foretaget EBOKS Eksempel på fejlliste: EBOKS008005Fejlliste EBOKS P DK Bruger findes ikke EBOKS P DK Bruger findes ikke EBOKS P DK Bruger findes ikke EBOKS P DK Bruger findes ikke EBOKS P DK Bruger findes ikke EBOKS Returkoder og -tekst Følgende returkoder med tilhørende returtekst kan forekomme i parameterrecorden. Returkode Returtekst 0 Indsættelsen er foretaget 1 Bilag xxx findes ikke 7 Abonnementsforholdet findes ikke 8 Kunde-materialeforhold findes ikke 9 Materiale findes ikke 10 Kunde findes ikke 11 Bruger findes ikke 12 Antal bilag ikke lovlig 13 Antal modtagere ikke lovlig 14 Forskel på angivet længde og optalt længde 15 Afvist pga. fejl ved anden modtager af samme dokument 16 Samme modtager angivet flere gange på et dokument 17 Virkningsdato ligger mere end 45 dage frem i tiden 99 Anden fejl 12

13 8. Feltbeskrivelser <Rec-type> <Struktur-version> <Data-type> <Kunde-nr> <Timestamp> Identificerer record-typen. Nummeringen af de enkelte records er et udtryk for den 'rækkefølge' de er udviklet af e-boks i. Records er derfor ikke angivet i nummerisk orden. Angiver versionen for den enkelte record. Ved ændringer i recordlayout vil versionsnummeret også ændres. Identificerer hvilken snitflade der er tale om (tilmeldingsliste, materialeindlæsning, fejl-/kvitteringsliste). Et unikt nummer for den enkelte kunde. Nummeret tildeles af e-boks. Ønsker kunden at benytte egne kunde-numre skal dette aftales med e-boks. Tidspunktet hvor filen er genereret. En bruger i e-boks identificeres vha. nedenstående tre felter: <Ident-type> <Ident> <Nationalitet> Ident-type skal være P for cpr-nummer eller V for cvr-nummer, Skal være cpr-nummer eller cvr-nummer. Cpr.-nummeret angives uden '-' (bindestreg) og angives venstrestillet med efterfølgende blanke Nationalitet for brugeren ifølge ISO3160. F.eks. Danmark = DK, <Filler> <Materiale-ident> <Valørdato> <Materialebeskrivelse> Et felt der bruges til at fylde strukturen op, så strukturen passer til en bestemt længde. Feltet skal angives med blanke. Unikt nummer, som tildeles hvert dokument, fx et nummer for regninger, et andet for årsopgørelser osv. Nummeret tildeles af e-boks. Ønsker kunden at benytte egne materiale-identer skal dette aftales med e-boks. Den dato PDF-dokumentet skal være synligt i modtagerens indbakke. Data kan indlæses før denne dato, men vil ikke være synligt i e-boks før. Angives der ikke nogen valørdato, vil dokumentet være synligt senest dagen efter. Afsenderens mulighed for frit at angive en tekst. Teksten indgår i navnet på dokumentet, som modtageren ser det i sin indbakke. Bemærk, at den variable tekst sættes sammen med den (faste) tekst, som er registreret på materialet hos e-boks. Den faste tekst står forrest efterfulgt af den variable tekst. <Leverandør_Identifikation> En identifikation, som entydigt identificerer det pågældende PDF-dokument. Det genereres af kunden og returneres af e-boks i fejl-/kvitteringslisten. Kunden kan derudover bruge feltet som et slags 'fingerprint' for dokumentet. Feltet tolkes ikke af e-boks. <Antal bilag> <Bilags-id> Numerisk felt som angiver antallet af bilag der skal vedhæftes PDFdokumentet. Der kan tilknyttes op til 10 bilag pr. dokument. De identer der angives skal være otte karakterer lange og skal matche med de af e-boks fremsendte bilag. 13

14 <Materialetype> <Returkode> <Returtekst> Filtypen på dokumentet. Pt. understøttes kun PDF. e-boks angiver en returkode i parameterrecorden. Er returkoden 0 er indlæsningen af dokumentet i e-boks gået godt. Er returkoden 0 er der opstået en fejl. Uddybende tekst som forklarer hvad en given returkode skyldes. 14

15 9. Specifikt for kunder der genererer data på mainframe Nedenstående omhandler kun materiale-indlæsningsfilen. Datasættet indeholder records med variabel længde, med maksimal længde på bytes. 15

16 10. Specifikt for kunder der genererer data på PC Nedenstående omhandler kun materiale-indlæsningsfilen. Jf. beskrivelsen af materiale-indlæsningsfilen (side 7) skal data leveres til e-boks i det angivne format. Genererer kunden data til e-boks på en PC-platform, er det vanskeligt at levere disse i records med fast længde. For at kunne møde e-boks krav til levering, skal kunden levere hver record med et to-karakters længdefelt foran hver record. Længdefelterne skal svare til den længde der er angivet over hver record i beskrivelsen af materiale-indlæsningsfilen. Længdefelterne efterfølges af data med et indhold der svarer til længden. Den eneste adskillelse der er mellem de enkelte records er således længdefeltet og der må derfor ikke indsættes andre former for adskillelsestegn. Logisk opbygning af filen 82 header 295 parameter 83 ekstrabruger 11 datastart?? data 26 dataslut 41 trailer Indhold i materiale-indlæsningsfilen Nedenfor er angivet et eksempel på indholdet i en materialefil. Det samme indhold er angivet i hhv. hex, ASCII og EBCDIC. HEX ASCII EBCDIC 16

17 11. Konverteringstabel Nedenstående tabel viser hex-konvertering fra ASCII til EBCDIC. Det EBCDIC tegnsæt der skal benyttes er IBM codepage 277. FØRSTE TEGN 1x 2x 3x 4x 5x 6x 7x 8x 9x Ax Bx Cx Dx Ex Fx x0 8C F0 7C D7 97 B0 9A DF A 2A 1A x1 AE 5A F1 C1 D B1 AA DE x2 9C 7F F2 C2 D B2 AF DB x3 CC 7B F3 C3 E2 83 A2 B3 9F DA x4 CE 5B F4 C4 E3 84 A3 B4 8F CF x5 EC 6C F5 C5 E4 85 A4 B5 BE CD ANDET TEGN x6 BF 50 F6 C6 E5 86 A5 B6 FE CB x7 BB 7D F7 C7 E6 87 A6 B7 FD CA x8 77 4D F8 C8 E7 88 A7 B8 FC BA x9 76 5D F9 C9 E8 89 A8 B9 FB 8A xa 5C 7A D1 E9 91 A9 8D EF xb 4E 5E D2 AD 92 A1 8E EE F 2F 1F 0F xc 6B 4C D3 E0 93 9E A0 ED E 2E 1E 0E xd 5F 60 7E D4 BD 94 AB 9D EB D 2D 1D 0D xe 80 4B 6E D5 6A 95 AC DD EA C 2C 1C 0C xf F D6 6D 96 BC DC E B 2B 1B 0B Eksempel e-boks skrives i ASCII: 65 2D 42 6F 6B 73 I EBCDIC angives e-boks hex-decimalt på følgende måde: C A2 17