Nachrichtenhandbuch

AC03 V2

 

Version 1.5

 

 

 

DAKOSY-Logo_ohneUnterzeile_140x21

 

 

 

 

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.4

Alle

Nachrichtenelement ‚TransportOrder‘:

- Element <TransportOrder><TransportContainer><WagonLoadingPosition> korrigiert

Nachrichtenhandbuch aktualisiert

XML Beispiele aktualisiert

Dokumentation innerhalb der XSDs aktualisiert

S.Buse

03.06.2013

1.5

Alle

Umzug der XSDs auf xsd.daskoy.de und Aktualisierung der Nachrichtenbeispiele

S.Buse

01.06.2018

 

 

Änderungsdienst

 

DAKOSY

Datenkommunikationssystem AG

Mattentwiete 2

20457 Hamburg

 

 

 

 

 

Verwendete Werkzeuge

 

Dieses Dokument wurde mit dem Textverarbeitungsprogramm MS Word 2010 erstellt.

 

 

 

Mitgeltende Dokumente

 

Im EDI - Handbuch "Allgemeiner Teil" sind die Grundsätze beschrieben, die für jeden Datenaustausch, der über DAKOSY erfolgt, gültig sind. Die dort niedergelegten Definitionen, die beschriebenen Mitwirkungspflichten des Kunden sowie die Grundlagen des Kommunikationsablaufes gelten auch für die im vorliegenden Handbuch beschriebene Schnittstelle.

 

 

 


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

TransportOrder.xsd

AC03CoreDataTypes.xsd

MessageEnvelope.xsd

 

Beispiel Auftrag

 


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

 

StatusInformation.xsd

AC03CoreDataTypes.xsd

MessageEnvelope.xsd

 

Beispiel Status

Beispiel Rückweisung

Beispiel Buchungsbestätigung

Beispiel Löschung

 


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

REFTOCONS

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

 

Invoice.xsd

AC03CoreDataTypes.xsd

MessageEnvelope.xsd

 

Beispiel Fakturadaten

 

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:


 

Entscheidend für die Bedeutung der Quittung ist das Attribut ‚type‘ des Elements ‚Response‘:

 

Type

Bedeutung

Response

Wird zur positiven Quittierung einer Nachricht verwendet – ein erläuternder Text ist nicht notwendig

Error

Negative Quittung / Fehler beim Parsen der Nachricht – der Fehlertext kann im Element 'Free Text' übermittelt werden

 

Bei einer positiven Quittung wird im Element ‚Code‘ der Wert ‚00000‘ erwartet. Bei negativen Quittungen kann ein entsprechender Fehlercode kommuniziert werden.

2.4.1.  XSD-Schema und Beispiele

 

Response.xsd

AC03CoreDataTypes.xsd

MessageEnvelope.xsd

 

Beispiel positive Quittung

Beispiel negative Quittung

 

2.5.     Allgemeine Element Definitionen / eingebundene XSDs

Die verschiedenen AC03 Nachrichtenelemente nutzen für gemeinsam verwendete Elemente zentrale Definitionen (Core Datentypen) und eine einheitliche Definition für die Elemente zur Adressierung der Nachrichten (Message Envelope) in Form von eingebundenen XSDs.

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

Auftragserteilung mit Stornierung

Auftragserteilung mit Fakturierung

 

3.2.     DAKOSY spezifische Szenarien

Auftragserteilung mit ZODIAK

Auftragserteilung mit HBZ (HABIS Zoll)

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:

 

Normalfall

Beispiel positive Quittung

 

Verlorene Nachricht

Verlorene Quittung

 

Syntaktisch oder inhaltlich fehlerhafte Nachricht

 

Beispiel negative Quittung

 

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