Nachrichtenhandbuch
AC03 V2
Version 1.3
DAKOSY Datenkommunikationssystem AG
Mattentwiete 2
20457 Hamburg
Tel. 040 / 37003 - 0
Fax. 040 / 37007 – 370
Änderungsnachweis:
|
Version |
Betr. Abschnitte |
Grund |
Name |
Datum |
|
0.1 |
Alle |
Erstellung |
K.Zeissig |
18.01.2008 |
|
1.0 |
Alle |
Review |
S. Buse |
15.08.2008 |
|
1.1 |
Alle |
- Kompatibilität mit AC03 V01: Korrektur der XML-Attribute im Bereich der Struktur <Metainfo> - Ergänzung des optionalen Elements <IMPReference> im Transportauftrag - Korrektur des Elements <Document><Messages><Message> des Nachrichtenelements 'Response' |
S. Buse |
30.01.2009 |
|
1.2 |
Alle |
Nachrichtenelement 'TransportOrder': - Änderung der Elemente <Date> und <Instruction> in der Struktur <TransportOrder><TransportContainer><Loading> in optionale Elemente der Struktur - Ergänzung des optionalen Attributs 'position' bei Zollregistriernummern (..<GoodsItem><RegistrationNumber> und ...<Goodsitem><PreviousNumber>) - Änderung der Kardinalität des Elements <TransportOrder><TransportContainer><CustomsZODIAK><Date> in 0..3 - Korrektur der Definition des Attributs 'reference' des Elements <TransportOrder> Nachrichtenelement 'StatusInformation': - Korrektur der Definition des Attributs 'reference' des Elements <Status> - Korrektur der Kardinalität des Elements <Status><OrderConfirmation><NumberOfPositions> in 1..999 |
S. Buse |
30.06.2009 |
|
1.3 |
Alle |
Nachrichtenelement 'StatusInformation': - Wiederholung der Struktur <Status> korrigiert XML Beispiele aktualisiert |
S.Buse |
27.04.2012 |
1. Vorbemerkung
Die Transaktion AC03 in der Version 02 stellt eine Weiterentwicklung, bzw. Konsolidierung der ersten Version der Transaktion dar. In den folgenden Kapiteln werden die verschiedenen Nachrichtenelemente einzeln dargestellt. Eine Dokumentation der Änderungen gegenüber der ersten Version der Transaktion finden Sie in Kapitel 4.4 Migration AC03 Version 01 / AC03 Version 02.
2. Nachrichtenelemente
2.1. Vormeldung / Transportauftrag / Verlade-Ist
Vormeldungen, Transportaufträge und Verlade-Ist Meldungen werden bei der Kommunikation strukturell gleich behandelt. Sie unterscheiden sich in der praktischen Verwendung in ihrer Bedeutung und im Umfang der jeweils kommunizierten Daten. Der konkrete Typ der Nachricht wird über das Attribut 'type' im XML-Element 'TransportOrder' festgelegt.
 |
Die nachfolgende Grafik stellt die Struktur der Vormeldung, Transportauftrags und Verlade-Ist Meldung dar und ist mit einer detaillierten Beschreibung der einzelnen Nachrichtenelemente verlinkt:
Die Nachrichtenelemente Transport Order, Address Data, Transport Container und Dangerous Goods Information beschreiben respektive die inhaltlichen Elemente des Auftragskopfs, der Adressdaten, des Containers und der Gefahrgutinformationen.
Die Nachrichtenelemente Goods Item und Goods Item Allocation ermöglichen die Kommunikation von Warenpositionen und deren Zuordnung zu Containern.
Die Zolldaten werden mit Hilfe des Nachrichtenelements Customs übermittelt. Für die Kommunikation mit ZODIAK (ATLAS Anmeldung) benötigte zusätzliche Datenelemente werden in dem dedizierten Nachrichtenelement Customs Information ZODIAK kommuniziert.
2.1.1. XSD-Schema und Beispiele
2.2. Statusmeldungen
Die Statusmeldungen dienen zur Kommunikation verschiedener Inhalte. Mit ihnen werden Statusinformationen (im engeren Sinne), Fehlermeldungen oder Rückweisungen, Buchungsbestätigungen und Löschungen übermittelt.
Die nachfolgende Grafik stellt die Struktur der Statusmeldungen dar und ist mit einer detaillierten Beschreibung der einzelnen Nachrichtenelemente verlinkt:
 |
2.2.1. XSD-Schema und Beispiele
2.2.2. Codes Nachrichtenelement StatusInformation
Element ReferenceQualifier
Folgende Werte können im Element ReferenceQualifier verwendet werden:
|
ReferenceQualifier |
|
|
Code |
Bedeutung |
|
HABISTANR |
HABIS Transportauftragsnummer |
|
REFTOCOMP |
Auftragsreferenz des Transportunternehmers |
|
HANUMBER |
HABIS Zoll HA-Nummer |
|
ATLASNUMBER |
ATLAS Referenz |
|
TRAIN |
Zugnummer |
|
REFTOCONSR |
Auftragsreferenz des Auftraggebers |
Element StatusQualifier
Die möglichen Werte für das Element StatusQualifier sich noch nicht abgestimmt.
|
StatusQualifier |
|
|
Code |
Bedeutung |
|
NN |
NN |
Element StatusTimeQualifier
Folgende Werte können im Element StatusTimeQualifier verwendet werden:
|
StatusTimeQualifier |
|
|
Code |
Bedeutung |
|
OCCURRANCE |
Zeitpunkt zu dem der Status, bzw. das dem Status zugrunde liegenden Ereignis eingetreten ist |
|
REPORTING |
Zeitpunkt zu dem der Status, bzw. das dem Status zugrunde liegenden Ereignis gemeldet worden ist |
|
TARGET |
Zeitpunkt zu dem der Status, bzw. das dem Status zugrunde liegenden Ereignis eintreten sollte |
Element StatusCode
Die möglichen Werte für das Element StatusCode sich noch nicht abgestimmt.
|
StatusCode |
||
|
Typ |
Code |
Bedeutung |
|
NN |
NN |
NN |
2.3. Fakturadaten
Die nachfolgende Grafik stellt die Struktur der Fakturadaten dar und ist mit einer detaillierten Beschreibung der einzelnen Nachrichtenelemente verlinkt:
 |
2.3.1. XSD-Schema und Beispiele
2.4. Quittung
Jede kommunizierte Nachricht – außer der Quittung selber - wird quittiert. Dies geschieht mit Hilfe einer technischen Quittung.
Die nachfolgende Grafik stellt die Struktur der Quittung dar und ist mit einer detaillierten Beschreibung der einzelnen Nachrichtenelemente verlinkt:
 |
Das Nachrichtenelement 'Response' kann folgende Werte für das Element 'Code' des komplexen Typs 'Notification' enthalten:
|
Code |
Type |
Bedeutung |
|
00000 |
INFO |
Der Code wird zur positiven Quittierung einer Nachricht verwendet – ein erläuternder Text ist nicht notwendig |
|
00100 |
INFO |
Positive Quittierung einer doppelt erhaltenen Nachricht (Vorraussetzung: gleiche Nachrichtenreferenz) |
|
10000 |
ERROR |
Fehler beim Parsen der Nachricht – der Fehlertext kann im Element 'Free Text' übermittelt werden |
|
85000 |
ERROR, INFO, STATUS, WARNING |
Freier Text – Details siehe Element 'Free Text' |
2.4.1. XSD-Schema und Beispiele
3. Fachlicher Nachrichtenaustausch
Die hier dargestellten Szenarien stellen beispielhaft den Nachrichtenaustausch aus fachlicher Sicht dar. Die technischen Aspekte des Nachrichtenaustauschs werden in Kapitel 2 Technischer Nachrichtenaustausch erörtert.
3.1. Allgemeine Szenarien
Auftragserteilung mit Buchungsanfrage
- Übermittlung einer Buchungsanfrage mit anschließender Auftragserteilung (Übermittlung des Auftrags mit gleicher Referenz)
- Annahme des Auftrags
- Änderung des Auftrags durch den Auftraggeber
- Rückmeldung von Statusinformationen und der Verlade-Ist Meldung
Auftragserteilung mit Stornierung
- Übermittlung des Auftrags
- Annahme des Auftrags durch den Auftragnehmer
- Stornierung des Auftrags durch den Auftraggeber und anschließende Löschung des Auftrags durch den Auftragnehmer
Auftragserteilung mit Fakturierung
- Übermittlung des Auftrags
- Annahme des Auftrags durch den Auftragnehmer
- Rückmeldung von Statusinformationen und der Verlade-Ist Meldung
- Rückmeldung von Fakturadaten an den Auftraggeber
3.2. DAKOSY spezifische Szenarien
Auftragserteilung mit ZODIAK
- Szenario für Aufträge mit ATLAS-Anmeldung
- Übermittlung einer Transport Order (Auftrag) mit Nachrichtenelementen Goods Item und Customs Information ZODIAK
- Weiterleitung der Daten an ZODIAK und nach entsprechender Verarbeitung an ATLAS
- Rückmeldung von Statusinformationen aus ATLAS und ZODIAK (z.B. Zollregistriernummern)
- Weitere Verarbeitung des Auftrags (mit ergänzten Zolldaten) in ACTION / UNIKAT
Auftragserteilung mit HBZ (HABIS Zoll)
- Szenario für Bahnauftrage ab/nach Hamburg
- Übermittlung einer Transport Order (Auftrag) mit Nachrichtenelementen Goods Item und der notwendigen Zollangaben in der Struktur Customs
- Automatische Weiterleitung und Verarbeitung der HABIS Zoll Anmeldung
Auftraggeber
4. Technischer Nachrichtenaustausch
4.1. Nachrichtenversionen
Die Version der verwendeten Nachrichtenelemente wird über das Attribut 'version' des Elements 'Transaktion' in jeder Nachricht festgelegt. Für alle in diesem Dokument beschriebenen Nachrichtenelemente ist dies die Version '02'. Zum Beispiel für eine Quittungsnachricht sieht das Element 'Transaktion' wie folgt aus:
<Transaction Code="AC03" Type="Response" Version="02">
Aus technischer Sicht gibt es keinen Zwang nur Nachrichtenelemente einer Version zu kommunizieren. Es ist zum Beispiel möglich auf eine TransportOrder der Nachrichtenversion '01' mit einer Quittung oder Statusmeldung der Version '02' zu antworten (oder umgekehrt). Dies ermöglicht insbesondere eine schrittweise Migration zwischen den Versionen '01' und '02' von AC03.
Die verwendete Version der einzelnen Nachrichtenelemente wird bilateral zwischen den Kommunikationspartnern vereinbart.
4.2. Quittierung
Die Quittungsmeldung wird als Antwort auf jede Nachricht gesendet. Quittungsmeldungen selber werden nicht quittiert.
Die Quittungsmeldung erfüllt folgende Aufgaben:
- Bestätigung der korrekten Verarbeitung bzw. Ablehnung aufgrund einer fehlerhaften Syntax (Prüfung gegen XML-Schema)
- Erkennung von Nachrichtenverlust / -doppelung zusätzlich zur Sicherung auf der technischen Ebene.
Normalfall
- Nachricht syntaktisch korrekt.
- Der Absender erhält für jede Nachricht eine Quittungsmeldung mit dem Wert 'Response' im Attribut 'type' des Elements Response und dem 'Code 00000'.
Verlorene Nachricht
- der Absender erhält keine Quittungsmeldung
- erneute Übermittlung der Nachricht (kann mit gleicher Nachrichtenreferenz erfolgen).
- Hierfür sind beim Absender entsprechende Timeout und Retry-Verfahren zu implementieren.
Verlorene Quittung
- Der Absender erhält keine Quittungsmeldung – die Nachricht muss erneut gesendet werden.
- Der Empfänger ignoriert die doppelte Nachricht (Vorraussetzung: gleiche Nachrichtenreferenz) und sendet erneut eine Quittungsmeldung mit der Information 'Nachricht doppelt empfangen'.
Syntaktisch oder inhaltlich fehlerhafte Nachricht
- die Nachricht lässt sich nicht gegen das Nachrichtenschema validieren
- die Nachricht enthält inhaltliche Fehler
- Übermittlung der korrigierten Nachricht mit einer neuen Nachrichtenreferenz und gleicher fachlicher Version.
4.3. Protokolle
Bevorzugtes Protokoll für den Austausch von AC03 XML-Nachrichten ist FTP. Das generelle Verfahren zum Nachrichtenaustausch mit DAKOSY per FTP ist in dem folgenden Handbuch beschrieben:
Datenaustausch mit DAKOSY über FTP
Aufgrund der expliziten Quittierung aller Nachrichten ist ebenfalls ein gesicherter Austausch der Nachrichten per E-Mail möglich.
Das konkrete Verfahren ist jeweils zwischen den Kommunikationspartnern bilateral abzustimmen.
4.4. Migration AC03 Version 01 / AC03 Version 02
4.4.1. TransportOrder
Das Nachrichtenenlement TranportOrder in der Version 02 unterscheidet sich gegenüber der Version 01 durch Umstrukturierungen im Bereich der Datenelemente des Hauptlaufs per Bahn und der Zolldaten. Die Tabelle 'TransportOrder Änderungen AC03 Version 01 / Version 02' enthält eine detaillierte Liste der geänderten, nicht mehr verwendeten oder neuen Elemente.
4.4.2. Freistellung
Das Nachrichtenelement Freistellung ist nicht in der AC03 Version 02 enthalten und wird weiterhin nur in der Version 01 kommuniziert.
4.4.3. Statusmeldung
Die Änderungen im Bereich des Nachrichtenelements StatusInforamtion betreffen im Wesentlichen die eigentlichen Statusinformationen. Es ist jetzt möglich 'beliebige' Statuswerte zu kommunizieren. Die Tabelle 'StatusInformation Änderungen AC03 Version 01 / Version 02' enthält eine detaillierte Liste der geänderten, nicht mehr verwendeten oder neuen Elemente
4.4.4. Fakturadaten
Die Fakturadaten in der Nachrichtenversion 02 stellen eine Neuentwicklung dar. Aus diesen Grunde wird auf eine Anleitung zur Migration der Fakturadaten in der Nachrichtenversion 01 verzichtet.
4.4.5. Quittung
Die Quittung stellt in der Nachrichtenversion 02 eine Vereinfachung der ersten Version dar. Die Tabelle 'Response Änderungen AC03 Version 01 / Version 02' enthält eine detaillierte Liste der geänderten, nicht mehr verwendeten oder neuen Elemente