- beskrivelse af snitflader

- beskrivelse af snitflader

1. Indholdsfortegnelse 1. Indholdsfortegnelse... 2 2. Ændringer... 3 3. Læsevejledning... 4 4. Tilmeldingslisten... 5 5. Materiale-indlæsningsfilen... 7 6. Fejl- og kvitteringslisterne... 11 7. Returkoder og -tekst... 12 8. Feltbeskrivelser... 13 9. Specifikt for kunder der genererer data på mainframe... 15 10. Specifikt for kunder der genererer data på PC... 16 11. Konverteringstabel... 17 2

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

3. Læsevejledning Dokumentet beskriver de snitflader der er mellem kunderne og e-boks, jf. nedenstående diagram. Afsnittene 3.-7. 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

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. 2000-12-24-12.30.45.123456 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 3166. 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

Grafisk fremstilling af tilmeldingsliste: en hel fil for tilmeldingslisten headerrecord parameterrecord n trailerrecord - én for hver ident Eksempel på tilmeldingsliste: EBOKS001004Tilmeldingsliste 0000000000011282003-02-13-01.30.27.661552 EBOKS002005000000000013029P 0102731111 DK EBOKS002005000000000013029P 0910352222 DK EBOKS002005000000000013029P 1203653333 DK EBOKS002005000000000013029P 1711724444 DK EBOKS002005000000000013029P 2505685555 DK EBOKS002005000000000013030P 0102731111 DK EBOKS002005000000000013030P 0910352222 DK EBOKS002005000000000013030P 1203653333 DK EBOKS002005000000000013030P 1711724444 DK EBOKS002005000000000013030P 2505685555 DK EBOKS003003000000000000010 Eksemplet viser en tilmeldingsliste med to materiale-identer (13029 og 13030). Tilmeldingslisten er altid en totalliste. 6

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

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 30.000 bytes Hvis PDF-dokumentet fylder mere end 30.000 byte, skal dokumentet deles i flere datarecords. Det er ikke et krav, at den enkelte datarecord skal fylde præcis 30.000 bytes. Det er således tilladt at opdele PDFdokumentet i datarecords, der fylder mindre end 30.000 bytes. Er dokumentet mindre end 30.000 bytes må de resterende bytes ikke påsættes i form af blanke eller andet så længden bliver 30.000. Nedenstående eksempel viser opbygningen af en fil, der indeholder to PDF-dokumenter - ét på 50.000 bytes og ét på 30.000 (der er ikke benyttet ekstra brugerrecord): oplysninger om indholdet af filen headerrecord parameterrecord datastartrecord første dokument med parameterrecord PDF-dokument (de første 30.000 bytes) PDF-dokument (de resterende 20.000 bytes) dataslutrecord en fil med alle dokumenter parameterrecord datastartrecord andet dokument med parameterrecord PDF-dokument 30.000 bytes dataslutrecord oplysninger om indholdet af filen trailerrecord 1 Se afsnit 10. Konverteringstabel for hex-konvertering fra ASCII til EBCDIC. 8

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. 2000-12-24-12.30.45.123456 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 3166. 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 3166. Danmark = DK 9

Datastartrecord længde 11 Rec-type String 8 Altid 'EBOKS014' Struktur-version String 3 Recordversion. Pt. 004 Datarecord længde 30.000 Areal String 30.000 Variabel længde max. 30.000 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

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. 2000-12-24-12.30.45.123456 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 3166. 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

Eksempel på kvitteringsliste: EBOKS008005Kvitteringsliste 0000000000011282003-02-26-13.56.09.540480 EBOKS009005000000000013029P 0102731111 DK 00000000009201000Indsættelsen er foretaget EBOKS009005000000000013029P 0910352222 DK 00000000009201000Indsættelsen er foretaget EBOKS009005000000000013029P 1203653333 DK 00000000009201000Indsættelsen er foretaget EBOKS009005000000000013029P 1711724444 DK 00000000009201000Indsættelsen er foretaget EBOKS009005000000000013029P 2505685555 DK 00000000009201000Indsættelsen er foretaget EBOKS010005000000000000005 Eksempel på fejlliste: EBOKS008005Fejlliste 0000000000011282003-02-21-12.12.31.708815 EBOKS009005000000000013030P 0102731111 DK 00000000000000011Bruger findes ikke EBOKS009005000000000013030P 0910352222 DK 00000000000000011Bruger findes ikke EBOKS009005000000000013030P 1203653333 DK 00000000000000011Bruger findes ikke EBOKS009005000000000013030P 1711724444 DK 00000000000000011Bruger findes ikke EBOKS009005000000000013030P 2505685555 DK 00000000000000011Bruger findes ikke EBOKS010005000000000000005 7. 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

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

<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

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å 30.000 bytes. 15

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

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 70 52 3A 2A 1A x1 AE 5A F1 C1 D8 81 98 B1 AA DE 69 51 39 29 19 x2 9C 7F F2 C2 D9 82 99 B2 AF DB 68 49 38 28 18 x3 CC 7B F3 C3 E2 83 A2 B3 9F DA 67 48 37 27 17 x4 CE 5B F4 C4 E3 84 A3 B4 8F CF 66 47 36 26 16 x5 EC 6C F5 C5 E4 85 A4 B5 BE CD 65 46 35 25 15 ANDET TEGN x6 BF 50 F6 C6 E5 86 A5 B6 FE CB 64 45 34 24 14 x7 BB 7D F7 C7 E6 87 A6 B7 FD CA 63 44 33 23 13 x8 77 4D F8 C8 E7 88 A7 B8 FC BA 62 43 32 22 12 x9 76 5D F9 C9 E8 89 A8 B9 FB 8A 59 42 31 21 11 xa 5C 7A D1 E9 91 A9 8D EF 78 58 41 30 20 10 xb 4E 5E D2 AD 92 A1 8E EE 75 57 3F 2F 1F 0F xc 6B 4C D3 E0 93 9E A0 ED 74 56 3E 2E 1E 0E xd 5F 60 7E D4 BD 94 AB 9D EB 73 55 3D 2D 1D 0D xe 80 4B 6E D5 6A 95 AC DD EA 72 54 3C 2C 1C 0C xf 90 61 6F D6 6D 96 BC DC E1 71 53 3B 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: 85 60 C2 96 92 A2 17