Kontrollmitteilungsverfahren

Transkript

1 RZF NRW Rechenzentrum der Finanzverwaltung des Landes Nordrhein-Westfalen SST : Schnittstellen SST_KMV_Datenschnittstelle_Protokoll_6 Version : Status : abgestimmt Stand :

2 Seite 2 von 19 KONSENS Inhaltsverzeichnis 1 Allgemeines Kurzbeschreibung Änderungsübersicht Einleitung Referenzierte Dokumente Links Das Protokoll Übersicht die Felder des Protokolls Das Verarbeitungsprotokoll [Protokoll] Die Version des Protokolls [version] Der nsraum des Protokolls [xmlns] Der Zeitstempel der Protokoll-Aufbereitung [ZeitStempel] Der Datenteil [DatenTeil] Das Transferticket [transferticket] Der Statuscode zur gesamten Datenlieferung[code] Der Statustext zur Datenlieferung [text] XML-Beispiel Der Nutzdatenblock [Nutzdatenblock] Das Nutzdatenticket [nutzdatenticket] Der Statuscode zum Nutzdatenblock [code] Der Statustext zum Nutzdatenblock [text] Anzahl der Verarbeiteten Nutzdatensätze [verarbeitetends] Anzahl der nichtverarbeiteten Nutzdatensätze [nichtverarbeitetends] XML-Beispiel Fehler zum Nutzdatensatz [NdSFehler] Laufende Nummer [lfdnr] des Nutzdatensatzes KmId Nutzdatensatz[kmId] Ordnungsmerkmal zum Nutzdatensatz Fehlernummer zum Nutzdatensatz [fehlernummer] Fehlertext zum Nutzdatensatz [fehlertext] XML-Beispiel XML-Beispiele Aufzeichnung und Aufbewahrung der Übertragungsprotokolle durch den Datenlieferanten Version: Seite: 2

3 Seite 3 von 19 1 Allgemeines 1.1 Kurzbeschreibung Die Verfahrensbeschreibung KMV besteht aus folgenden Komponenten: - Beschreibung über den Verfahrensablauf - Beschreibung der versionisierten Datenschnittstellenbeschreibung - Beschreibung der Datenschnittstelle für das Protokollverfahren Dieses Dokument beschreibt die Datenschnittstelle für das Verarbeitungsprotokoll, welches im Rahmen der Verarbeitung der bereitgestellten Datenlieferungen erstellt wird. 1.2 Änderungsübersicht Version Bearbeiter Änderungsdatum Durchgeführte Änderung KMV-Team Ersterstellung 1.0 KMV-Team formale Korrektur aller Kapitel Tabelle 1 / Änderungsübersicht Version: Seite: 3

4 Seite 4 von 19 2 Einleitung Dieses Dokument beschreibt die Datenschnittstelle für das Verarbeitungsprotokoll, welches im Rahmen der Verarbeitung der bereitgestellten Datenlieferungen erstellt wird. Dabei werden in dieser Dokumentation ausschließlich die Datenstrukturen und Datenfelder die sich im Nutzdaten-Teil der Elster-Datenstruktur von Protokollen befinden beschrieben. Mehr zum Thema Elster-Datenstruktur sind der Elster-Basisdokumentation zu entnehmen. 2.1 Referenzierte Dokumente Nr Dateiname Pfad Inhalt 1 EBA_ElsterDatenschn ittstelle.pdf cure/schnittstellen_herst.ph p 2 SST_KMV_Verfahrens ablauf.doc ElsterBasis Dokumentation mit genauer Beschreibung des Transfer- und NutzdatenHeaders. Allgemeine Verfahrensbeschreibung für KMV Schwerpunkte: (Offlineverfahren) Datenlieferung Verfahrensablauf Protokollverfahren (Ablauf) Tabelle 1 / Referenzierte Dokumente Referenzierte Dokumente werden durch ein R und die laufende Nr referenziert z.b. <R1> für das Dokument der gültigen nsvorsatzworte. 2.2 Links Nr Link Inhalt Tabelle 2 / Links In dieser Tabelle aufgelistet Links werden durch ein L und die laufende Nr referenziert z.b. <L1> für den Link auf die Finanzamtstabelle des Bundesamt für Finanzen. Version: Seite: 4

5 Seite 5 von 19 3 Das Protokoll 3.1 Übersicht die Felder des Protokolls Feldname Protokoll version xmlns ZeitStempel DatenTeil transferticket Code text Nutzdatenblock nutzdatenticket code text verarbeitetends nichtverarbeitetends NdSFehler lfdnr kmid ordnungsmerkmal fehlernummer fehlertext Kurzbeschreibung Version des Protokolls nsraum des Protokolls, aus dem auch die Version abgeleitet werden kann. Zeitstempel der Protokoll-Aufbereitung Transferticket der Datenlieferung, zu der das Protokoll abgerufen wurde Status der gesamten Datenlieferung (Nummer) Status der gesamten Datenlieferung (Text) Das eindeutige Ticket des Nutzdatenblocks aus der Datenlieferung Status des Nutzdatenblocks (Nummer) Status des Nutzdatenblocks (Text) Anzahl der aus dem Nutzdatenblock verarbeiteten Nutzdatensätze Anzahl der nicht verarbeiteten Datensätze des Nutzdatenblockes Fehlertext zu einem Datensatz im Nutzdatenblock oder zu dem Nutzdatenblock (Text) Laufende Nummer des Nutzdatensatzes innerhalb des Nutzdatenblocks die durch den Verfasser vorgegebene KmId der Mitteilung die durch den Verfasser vorgegebene bundesweit eindeutige Identifikation der Kontrollmitteilung Fehlernummer zum Fehler Fehlertext zum Fehler Version: Seite: 5

6 Seite 6 von Das Verarbeitungsprotokoll [Protokoll] Protokoll komplexe Struktur die nur weitere Datentypen und Strukturen besteht. Schaubild Attribute Use version Version required xmlns nsraum required Die Version des Protokolls [version] Die bei der Protokollanforderung vorgegebene bzw. durch den Datenlieferanten gewünschte Version des Protokolls wird als Attribut zum Protokoll wiedergegeben. version Zahl length minlength maxlength pattern 6 Version: Seite: 6

7 Seite 7 von Der nsraum des Protokolls [xmlns] Den unterschiedlichen Versionen der Verarbeitungsprotokolle sind unterschiedliche nsräume zugewiesen. Dieses lautet für die Versionen 6: 6 : Innerhalb der Version 6 ist nur der nsraum der Version 6 zulässig. zum nsraum xmlns Text XML-Beispiel: <Protokoll version="6" xmlns= > Der Zeitstempel der Protokoll-Aufbereitung [ZeitStempel] Es wird der Zeitstempel der serverseitigen Verarbeitung der Protokollanfrage zurück übermittelt. Das Format des ZeitStempels lautet: JJJJMMTThhmmss. ZeitStempel Zahl length 14 minlength maxlength Pattern \d{14} XML-Beispiel: <ZeitStempel> </ZeitStempel> Version: Seite: 7

8 Seite 8 von Der Datenteil [DatenTeil] In den Attributen zum DatenTeil werden immer das Transferticket der Datenlieferung und der Status der Verarbeitung als Code sowie als Text wiedergegeben. Der DatenTeil kann 0-n Nutzdatenblöcken als Kindelemente beinhalten. Sofern die Datenlieferung verarbeitet wurde, ist die Anzahl der Nutzdatenblöcke größer 0. Die Anzahl der Nutzdatenblöcke entspricht in der Regel der Anzahl der Nutzdatenblöcke aus der Datenlieferung (es wird der Status zu jedem Nutzdatenblock separat angegeben). In Einzelfällen (wenn ein schwerwiegender Fehler aufgetreten ist) wird nur ein Nutzdatenblock erstellt, in dem eine weitere Fehlerbeschreibung steht. Insbesondere in folgenden Fällen wird nur ein Nutzdatenblock erstellt: die Datenlieferung ist nicht wohlgeformt die Datenlieferung konnte nicht entschlüsselt werden die Zertifikatsprüfung einer authentifizierten Datenlieferungen lieferte einen Fehler die Nutzdatenblocktickets der Datenlieferungen waren nicht eindeutig DatenTeil komplexe Struktur die nur aus weiteren Datentypen und Strukturen besteht. Schaubild Attribute Use transferticket required code s.u. required text required Version: Seite: 8

9 Seite 9 von Das Transferticket [transferticket] Es wird das Transferticket der Datenlieferung, für die dieses Verarbeitungsprotokoll erstellt wurde im Attribut transferticket ausgewiesen. transferticket String Length minlength maxlength Pattern \d{19} oder [0-9a-km-z]{2}[0-9]{3}[0-9a-km-z]{27} 19-stellige Zahl mit führenden Nullen oder ETID (32-stellig alphanumerisch) Der Statuscode zur gesamten Datenlieferung[code] maxexclusive maxinclusive minexclusive mininclusive Enumeration code Zahl 0 (Datenlieferung ok Alle Datensätze konnten verarbeitet werden.) 1 (Es sind Fehler aufgetreten - die Nutzdatenblöcke konnten nur teilweise verarbeitet werden) 2 (Datenlieferung konnte gar nicht verarbeitet werden - alle Nutzdatenblöcke fehlerhaft) 3 (Datenlieferung wurde noch nicht verarbeitet - bitte fordern Sie das Protokoll noch mal zu einen späteren Zeitpunkt an; für Onlinebetrieb relevant) Version: Seite: 9

10 Seite 10 von Der Statustext zur Datenlieferung [text] Korrespondierend zum numerischen Status der Datenlieferung (vgl ) wird ein Klartext wiedergegeben. text String Length minlength maxlength Pattern Enumeration Datenlieferung ok Es sind Fehler aufgetreten - die Nutzdatenblöcke konnten nur teilweise verarbeitet werden Datenlieferung konnte gar nicht verarbeitet werden - alle Nutzdatenblöcke fehlerhaft Datenlieferung wurde noch nicht verarbeitet - bitte fordern Sie das Protokoll nochmal zu einen späteren Zeitpunkt an Hinweis: Die unter Enumeration aufgelisteten Texte sind weder durch XML-Schema noch eine weitere Komponente auf diese Werte beschränkt. Es wird empfohlen, die Texte nicht weiter zu prüfen und stattdessen in weitergehenden Routinen auf den entsprechenden eindeutigen Code, der zu dem Nutzdatenblock bescheinigt wird, abzustellen XML-Beispiel <DatenTeil transferticket=" " code= 2 text= Datenlieferung konnte gar nicht verarbeitet werden - alle Nutzdatenblöcke fehlerhaft > </DatenTeil> Version: Seite: 10

11 Seite 11 von Der Nutzdatenblock [Nutzdatenblock] Neben dem Status für die gesamte Datenlieferung, wird ein Status zu jedem NutzdatenBlock erstellt und übermittelt. Nutzdatenblock Komplexe Struktur minoccurs 0 maxoccurs Schaubild Attribute Use nutzdatenticket Text required code Zahl required text Text required verarbeitetends Zahl optional nichtverarbeitetends Zahl optional Beachte: Für jeden Nutzdatenblock aus der Datenlieferung wird im Verarbeitungsprotokoll ein Nutzdatenblock erstellt, der den Status des Nutzdatenblocks aus der Datenlieferung wiedergibt. Die Reihenfolge im Verarbeitungsprotokoll entspricht nicht zwingend der Reihenfolge der Nutzdatenblöcke aus der Datenlieferung - die Identifizierung des Nutzdatenblockes erfolgt über das Nutzdatenticket. Grundsätzlich steht nach der serverseitigen Verarbeitung für jeden Nutzdatenblock aus der Datenlieferung ein entsprechender Nutzdatenblockstatus zur Verfügung. Version: Seite: 11

12 Seite 12 von Das Nutzdatenticket [nutzdatenticket] Über das Nutzdatenticket im Verarbeitungsprotokoll wird der Nutzdatenblock aus der Datenlieferung referenziert. Lediglich in Einzelfällen in denen die Datenlieferung nicht korrekt verarbeitet werden kann, z.b.: die Gesamtstruktur der Datenlieferung war unzulässig das übermittelte XML ist nicht wohlgeformt die Nutzdatenblocktickets der Nutzdatenblöcke waren nicht eindeutig der DatenTeil der Datenlieferung konnte nicht entschlüsselt werden die Prüfung der Authentifizierung war fehlerhaft Datensätze die nur authentifiziert übermittelt werden dürfen, wurden nicht authentifiziert übermittelt wird serverseitig ein Nutzdatenblockticket generiert, um den Grund der Nichtverarbeitung zu protokollieren. In den o.g. Fällen wird immer die gesamte Datenlieferung nicht verarbeitet. nutzdatenticket Text Length minlength 1 maxlength 32 Pattern [\p{l} \p{p} \p{zs} \p{nd}]* Das Nutzdatenticket darf ausschließlich aus Buchstaben, Zahlen, Punktuationszeichen und dem Leerzeichen (Blank) bestehen. Blanks sind am Anfang und Ende des Nutzdatenticket unzulässig. Schmierzeichen und nicht druckbare Zeichen insbesondere Tabulatoren, Linefeed, Carriage-Return-Linefeed, etc sind unzulässig. Das Nutzdatenticket muss innerhalb der Datenlieferung eindeutig sein Der Statuscode zum Nutzdatenblock [code] Der Code steht in einem festen Zusammenhang mit dem NdBStatus-Text code Zahl maxexclusive maxinclusive minexclusive mininclusive 2 Daten geprüft und korrekt. 3 Daten geprüft und fehlerhaft - Datenblock wurde nicht verarbeitet. 4 Daten geprüft und teilweise fehlerhaft - Datenblock wurde nur teilweise verarbeitet Der Statustext zum Nutzdatenblock [text] Version: Seite: 12

13 Seite 13 von 19 Length minlength maxlength Pattern text Text Daten geprüft und korrekt. Daten geprüft und fehlerhaft - Datenblock wurde nicht verarbeitet. Daten geprüft und teilweise fehlerhaft - Datenblock wurde nur teilweise verarbeitet Anzahl der Verarbeiteten Nutzdatensätze [verarbeitetends] verarbeitetends Zahl minoccurs 0 mininclusive 0 maxinclusive (die maximale Anzahl von Nutzdatensätzen in einer Datenlieferung/ einem Nutzdatenblock) Anzahl der nichtverarbeiteten Nutzdatensätze [nichtverarbeitetends] nichtverarbeitetends Zahl minoccurs 0 mininclusive 0 maxinclusive (die maximale Anzahl von Nutzdatensätzen in einer Datenlieferung/ einem Nutzdatenblock) XML-Beispiel <Nutzdatenblock nutzdatenticket="nutzdatenticket01" code= 4 text= Daten geprüft und teilweise fehlerhaft - Datenblock wurde nur teilweise verarbeitet. verarbeitetends= 147 nichtverarbeitetends= 13 > </Nutzdatenblock> Version: Seite: 13

14 Seite 14 von Fehler zum Nutzdatensatz [NdSFehler] Soweit Fehler bei der Prüfung und Verarbeitung eines Nutzdatenblockes aufgetreten sind, werden diese protokolliert. Die maximale Anzahl von Fehlern ist abhängig von der gewählten Art der Verarbeitung (Vorgang der Datenlieferung) im Falle von KMV gilt: Sofern der Vorgang z.b. auf send-nosig gesetzt wurde, wird grds. beim ersten Fehler der gesamte Nutzdatenblock nicht verarbeitet. Es werden maximal 100 Fehler protokolliert. Im Rahmen der partiellen Verarbeitung (Vorgang send-nosig-part) werden sofern nicht der kritische Prozentsatz zur Nichtverarbeitung überschritten wurde (und somit der gesamte Nutzdatenblock verworfen wird) alle Fehler des Nutzdatenblockes protokolliert. Für jeden Nutzdatenblock werden NdSFehler (NutzdatenSatzFehler) protokolliert. Dabei besteht der Fehler aus einem laufenden Nummer(Attribut zum NdSFehler) der KmId (Attribut zum NdSFehler) oder dem ordnungsmerkmal (Attribut zum NdSFehler) Fehlernummer (Attribut zum NdSFehler) Fehlertext (Inhalt des Tag NdSFehler) NdSFehler Text minoccurs 0 maxoccurs unbounded length minlength maxlength Pattern Schaubild Version: Seite: 14

15 Seite 15 von 19 Attribute Use lfdnr Zahl required kmid Text optional ordnungsmerkmal Text optional fehlernummer Zahl required fehlertext Text required Soweit die Fehler auf Grund von Meldungen des Parsers (das übermittelte XML-Dokument ist nicht wohlgeformt oder nicht gültig) protokolliert wurden, beginnen die Fehlertexte mit org.xml.sax.saxparseexception: und dem entsprechenden Fehler Laufende Nummer [lfdnr] des Nutzdatensatzes Bei der lfdnr handelt es sich um die laufende Nummer des fehlerhaften Datensatzes in diesem Nutzdatenblock. lfdnr Zahl maxexclusive maxinclusive minexclusive mininclusive 0 Bezeichnung der Position des fehlerhaften Datensatzes innerhalb des Nutzdatenblocks. Bsp.: Die laufende Nummer 10 verweist auf den 10. Datensatz innerhalb des Nutzdatenblocks. Sofern ein Parser- oder ein anderer schwerwiegender Fehler auftritt, der den gesamten Nutzdatenblock betrifft, ist die Nummer KmId Nutzdatensatz[kmId] Bei der kmid handelt es sich um die durch den Verfasser vorgegebene KmId des Nutzdatensatzes. minoccurs 0 Length minlength maxlength 100 Pattern kmid String die durch den Verfasser vorgegebene KmId der Mitteilung Version: Seite: 15

16 Seite 16 von Ordnungsmerkmal zum Nutzdatensatz Beim ordnungsmerkmal handelt es sich um die durch den Verfasser vorgegebene bundesweit eindeutige Identifikation des Nutzdatensatzes (z.b. bei LStB, Lohnersatzleistungen) ordnungsmerkmal String minoccurs 0 Length minlength maxlength 100 Pattern Durch den Verfasser vorgegebene eindeutige Identifikation des Nutzdatensatzes Fehlernummer zum Nutzdatensatz [fehlernummer] Es wird die vom Elstersystem für diesen Fehler vergebene Fehlernummer i.d.r. eine 9-stellige Nummer zurückgemeldet. minexclusive mininclusive fehlernummer Zahl 9-stellige Zahl Fehlertext zum Nutzdatensatz [fehlertext] Es wird der vom Elstersystem für diesen Fehler vergebene Fehlertext zurückgemeldet. fehlertext Text minexclusive mininclusive XML-Beispiel <NdSFehler lfdnr="1" kmid="entw-test_2015_10_20_124" fehlernummer=" " fehlertext= org.xml.sax.saxparseexception: cvc-pattern-valid: Value '1000' is not facet-valid with respect to pattern '\d{8}'. /> Version: Seite: 16

17 Seite 17 von 19 KONSENS XML-Beispiele a) Datenlieferung OK <Protokoll version="6" xmlns=" <ZeitStempel> </ZeitStempel> <DatenTeil transferticket=" " code="0" text=" Daten geprüft und korrekt."> <Nutzdatenblock nutzdatenticket="nutzdatenticket01" code="2" text= Daten geprüft und korrekt. verarbeitetends= 655 nichtverarbeitetends= 0 /> <Nutzdatenblock nutzdatenticket="nutzdatenticket02" code="2" text= Daten geprüft und korrekt. verarbeitetends= 102 nichtverarbeitetends= 0 /> <Nutzdatenblock nutzdatenticket="nutzdatenticket03" code="2" text= Daten geprüft und korrekt. verarbeitetends= 17 nichtverarbeitetends= 0 /> </DatenTeil> </Protokoll> b) Datenlieferung konnte nur teilweise verarbeitet werden <Protokoll version="6" xmlns=" <ZeitStempel> </ZeitStempel> <DatenTeil transferticket=" " code="1" text=" Es sind Fehler aufgetreten - die Nutzdatenblöcke konnten nur teilweise verarbeitet werden."> <Nutzdatenblock nutzdatenticket="nutzdatenticket01" code="3" text= Daten geprüft und fehlerhaft - Datenblock wurde nicht verarbeitet. verarbeitetends= 0 nichtverarbeitetends= 1 > <NdSFehler lfdnr="1" kmid="2017-svk-nw abcdefg " fehlernummer=" " fehlertext="org.xml.sax.saxparseexception: cvc-pattern-valid: Value '1000' is not facetvalid with respect to pattern '\d{8}'. /> </Nutzdatenblock> <Nutzdatenblock nutzdatenticket="nutzdatenticket02" code="4" text= Daten geprüft und teilweise fehlerhaft - Datenblock wurde nur teilweise verarbeitet. Version: Seite: 17

18 Seite 18 von 19 KONSENS verarbeitetends= 102 nichtverarbeitetends= 1 > <NdSFehler lfdnr="1" ordnungsmerkmal=" 2013_01_RIE fehlernummer=" " fehlertext="org.xml.sax.saxparseexception: cvc-pattern-valid: Value '1000' is not facetvalid with respect to pattern '\d{8}'. /> </Nutzdatenblock> <Nutzdatenblock nutzdatenticket="nutzdatenticket03" code="2" text= Daten geprüft und korrekt. verarbeitetends= 17 nichtverarbeitetends= 0 /> </DatenTeil> </Protokoll> c) Datenlieferung konnte gar nicht verarbeitet werden <Protokoll version="6" xmlns=" <ZeitStempel> </ZeitStempel> <DatenTeil transferticket="eu1610gw6j7rka608arvzeo297vx1crp" code="2" text="datenlieferung konnte gar nicht verarbeitet werden - alle Nutzdatenblöcke fehlerhaft."> <Nutzdatenblock nutzdatenticket="ndticket-unbekannt" code="3" text="daten geprüft und fehlerhaft - Datenblock wurde nicht verarbeitet." verarbeitetends="0" nichtverarbeitetends="0"> <NdSFehler lfdnr="0" ordnungsmerkmal="unbekannt" fehlernummer=" " fehlertext="fehler beim Parsen der XML-Daten : org.xml.sax.saxparseexception; linenumber: 1; columnnumber: 120; cvc-elt.1: Cannot find the declaration of element &apos;elster&apos;."/> </Nutzdatenblock> </DatenTeil> </Protokoll> d) Datenlieferung wurde noch nicht verarbeitet <Protokoll version="6" xmlns=" <ZeitStempel> </ZeitStempel> <DatenTeil transferticket=" " code="3" text="datenlieferung wurde noch nicht verarbeitet - bitte fordern Sie das Protokoll noch mal zu einen späteren Zeitpunkt an."> </DatenTeil> </Protokoll> Version: Seite: 18

19 Seite 19 von 19 KONSENS 3.3 Aufzeichnung und Aufbewahrung der Übertragungsprotokolle durch den Datenlieferanten Es wird empfohlen das Verarbeitungsprotokoll für 6 Jahre aufzubewahren. Version: Seite: 19