TRACKINGDATEN AN KUNDEN. Beschreibung der Kundenschnittstelle für die Bereitstellung von Trackingdaten

Transkript

1 TRACKINGDATEN AN KUNDEN Beschreibung der Kundenschnittstelle für die Bereitstellung von Trackingdaten Version 1.2 Gültig ab 8. August 2011

2 2

3 Änderungsprotokoll: Dokument erstellt: Österreichische Post AG, Paketlogistik Österreich, Operative IT Systeme Datum Version Änderung Martin Brückler Martin Brückler, Korrekturen und Anpassungen an Corporate Design Vladimir Jocha, Korrekturen und Anpassungen am Inhalt und Corporate Design 3

4 4

5 INHALTSVERZEICHNIS 1. EINLEITUNG EVENTTYPEN DATENFORMATE XML-DATEI Aufbau des Headers Eventinformationen Beispiel XML-Trackinginformationen ASCII-FLATFILE Aufbau der Eventdaten im Flatfile Beispiel CSV-Trackinginformationen DATENPROTOKOLLE (S)FTP DATEINAMEN ZEITFENSTER PERIODISCH FIXE ZEITFENSTER BENÖTIGTE INFORMATIONEN ANHANG: XML-STRUKTUR TRACKINGEVENTS ANHANG: XML-SCHEMA-DEFINITION (XSD) TRACKINGEVENTS

6 1. Einleitung Das vorliegende Dokument beschreibt die Kundenschnittstelle, über welche einem Kunden Trackingdaten zu den eigenen Paketen bereitgestellt werden können: Zu den Paketen eines Kunden können innerhalb des Paketlaufes die erzeugten Daten (ScanEvents) in definierten regelmässigen Abständen elektronisch für einen Import in ein Eigensystem (z.b. CRM oder Call-Center- Applikation, etc.) zur Verfügung gestellt werden. Mit diesen Informationen ist es dem Kunden möglich auf einzelne Zustände oder Situationen einer Paketsendung zeitnah zu reagieren. ACHTUNG! Die aktuelle Event Reason Tabelle finden Sie im Dokument Beilage 1 zu Trackingdaten an Kunden 6

7 2. Eventtypen Die Eventinformationen der Post AG sind in Event-Types und Event-Reasons strukturiert. Es werden immer alle Trackingdaten (Event-Types und Event-Reasons) zurückgemeldet. Im Anhang 8 ist die aktuelle Gesamtliste der Event-Types und Event-Reasons dargestellt. Kurze Erläuterung: Event-Type Kürzel Event-Type Text Event-Reason Kürzel ZUS Zustellung BZ beschädigt übergeben Event-Reason Text ZUS Zustellung HH Zustellung sonstige HH defekt ZUS Zustellung SA Selbstabholung/Zuführung VZ ZUS Zustellung SV Selbstabholung/Zuführung VZ (automatisch) ZUS Zustellung VU Sendung zugestellt - Vertrag unterfertigt ZUS Zustellung ZA Abstellung gem. Vereinbarung ZUS Zustellung ZB Sendung an Übernahmsberechtigten übergeben ZUS Zustellung ZE Ersatzabgabestelle ZUS Zustellung ZJ Post.24 Paket durch Empfänger übernommen ZUS Zustellung ZK Sendung an Angestellten/Kollegen übergeben ZUS Zustellung ZM Sendung an Mitbewohner übergeben ZUS Zustellung ZN Sendung an Nachbar übergeben ZUS Zustellung ZP Sendung persönlich übergeben ZUS Zustellung ZR Zustellung Retoursendung ZUS Zustellung ZS Sendung an Spediteur übergeben ZUS Zustellung ZU Zustellung sonstige ZUS Zustellung ZV Sendung an Postbevollmächtigten übergeben ZUS Zustellung ZW Sendung an Wohnungsinhaber zugestellt ZUS Zustellung ZY Sendung an Familienmitglied übergeben ZUS Zustellung ZZ Austausch - Zug um Zug Beispiel: EventType = ZUS Zustellung An diesem Event-Type können nun (je Event) verschiedene Begründungen (Event-Reasons) für eine genaue Aussage - in diesem Fall durch den Zusteller - zugeordnet sein: Eventreason = ZW - Sendung an Wohnungsinhaber zugestellt oder Eventreason = ZN - Sendung an Nachbar übergeben Innerhalb des Datenfiles werden immer nur die entsprechenden Kürzel z.b. ZUS oder als dazugehörender Event-Reason ZN angeführt. 3. Datenformate Zur Ausführung gelangen die beiden Formate: 7

8 XML-Datei Flatfile (*.CSV, Semikolon-separiert, CR+LF) XML-Dateien beinhalten zusätzlich einen Header zur eindeutigen Bestimmung des Trackingdaten-Empfängers und zur Übermittlung von Metainformationen. Diese Header werden in den Beschreibungen der Formate genauer erläutert. Flatfiles beinhalten keinen Header, sondern bestehen nur aus Eventinformationen XML-Datei Die verwendete XML-Datei ist einfach strukturiert. Die XML-Struktur liegt in englischer Sprache vor und ist tabellarisch im Anhang 9 ersichtlich. Die Struktur der XML-Trackingdatei wird technisch durch eine XML-Schema-Defnition (XSD) spezifiziert und ist im Anhang 10 ersichtlich Aufbau des Headers Der Header ist wie folgt aufgebaut: Header Parent DebitorPayer Alphanum. 10 Customer Alphanum. 80 CreationDate DateTime EventCount Numeric 8 Der Header wird als Level 1 Information übertragen und wird nur einmal pro Trackingdatei übertragen. 8

9 Felder: DebitorPayer: Debitorennummer des Auftraggebers (Paketabsender = Empfänger Trackingdaten) bei der Post AG Customer: Name des Kunden laut Vertrag CreationDate: Datum des physischen Tages (Werktag), an welchem die Versanddaten erstellt werden EventCount: Anzahl der Tracking-Events im File Alle diese Felder mit Ausnahme des Kundennamens (Customer) sind Pflichtfelder. In einer Datei können jeweils nur Trackingdaten zu einem Debitor enthalten sein. Liefert ein Kunde über mehrere Debitoren bei der Post AG auf, so wird für jeden Debitor eine eigene Tracking-Datei generiert Eventinformationen Event Parent IdentCode Alphanum. 40 ReferenceIdentcode Alphanum. 40 ColliRefNr Alphanum. 40 CustomerNumber Alphanum. 40 CustomerShipmentNr Alphanum. 40 ShpRefNr Alphanum. 40 EventTimestamp DateTime EventPostalCode Alphanum. 10 ParcelEventTypeCode Alphanum. 3 ParcelEventReasonCode Alphanum. 3 Weight Decimal 7,3 ParcelEventId Alphanum. 40 OriginCustomerNumber Alphanum. 10 ConsigneeName Alphanum. 40 Remark Alphanum. 255 InsertDate DateTime Die einzelnen Eventinformationen werden als Level 2 Information übertragen und können beliebig oft im File übertragen werden. Die einzelnen Parameter sind teilweise Pflichtfelder. Falls es sich bei der Trackingdatei um ein Leerfile handelt (es sind keine neue Daten für die Rückmeldung vorhanden), so besteht die Trackingdatei nur aus dem Header (nur bei XML!) Beispiel XML-Trackinginformationen In der Instanz der XML-Datei ist der Aufbau der Trackingdatei mit Dummy-Daten beispielhaft ersichtlich. Zu beachten ist vor allem die richtige Verarbeitung der Namespaces 9

10 <ns0:trackingevent xmlns:ns0=" <Header> <DebitorPayer>DebitorPayer_0</DebitorPayer> <Customer>Customer_0</Customer> <CreationDate> T13:20:00.000</CreationDate> <EventCount>EventCount_0</EventCount> </Header> <Event> <IdentCode>IdentCode_0</IdentCode> <ReferenceIdentcode>ReferenceIdentcode_0</ReferenceIdentcode> <ColliRefNr>ColliRefNr_0</ColliRefNr> <CustomerNumber>CustomerNumber_0</CustomerNumber> <CustomerShipmentNr>CustomerShipmentNr_0</CustomerShipmentNr> <ShpRefNr>ShpRefNr_0</ShpRefNr> <EventTimestamp> T13:20:00.000</EventTimestamp> <EventPostalCode>EventPostalCode_0</EventPostalCode> <ParcelEventTypeCode>ParcelEventTypeCode_0</ParcelEventTypeCode> <ParcelEventReasonCode>ParcelEventReasonCode_0</ParcelEventReasonCode> <Weight>10.4</Weight> <ParcelEventId>10</ParcelEventId> <OriginCustomerNumber>OriginCustomerNumber_0</OriginCustomerNumber> <ConsigneeName>ConsigneeName_0</ConsigneeName> <Remark>Remark_0</Remark> <InsertDate> T13:20:00.000</InsertDate> </Event> <Event> <IdentCode>IdentCode_0</IdentCode> <ReferenceIdentcode>ReferenceIdentcode_0</ReferenceIdentcode> <ColliRefNr>ColliRefNr_0</ColliRefNr> <CustomerNumber>CustomerNumber_0</CustomerNumber> <CustomerShipmentNr>CustomerShipmentNr_0</CustomerShipmentNr> <ShpRefNr>ShpRefNr_0</ShpRefNr> <EventTimestamp> T13:20:00.000</EventTimestamp> <EventPostalCode>EventPostalCode_0</EventPostalCode> <ParcelEventTypeCode>ParcelEventTypeCode_0</ParcelEventTypeCode> <ParcelEventReasonCode>ParcelEventReasonCode_0</ParcelEventReasonCode> <Weight>10.4</Weight> <ParcelEventId>10</ParcelEventId> <OriginCustomerNumber>OriginCustomerNumber_0</OriginCustomerNumber> <ConsigneeName>ConsigneeName_0</ConsigneeName> <Remark>Remark_0</Remark> <InsertDate> T13:20:00.000</InsertDate> </Event> </ns0:trackingevent> 10

11 3.2. ASCII-Flatfile Alternativ zur XML-Datei kann ein ASCII Flatfile (CSV, Semikolon-separiert, CR+LF) benutzt werden. Die Daten im Flatfile sind entsprechend der XML-Datei (siehe Tabelle im Anhang 9) aufgebaut, enthalten allerdings keinen Header. Leere Felder werden ingnoriert (aaaa;;bbbb). Nicht benutzte Stellen in den einzelnen Feldern werden nicht mit Leerzeichen oder Nullen ausgefüllt! Aufbau der Eventdaten im Flatfile Die Dateninhalte sind allequot zur XML-Datei wie folgt aufgebaut: IdentCode ; ReferenceIdentcode ; ColliRefNr ; CustomerNumber ; ; InsertDate (CR+LF) Beispiel CSV-Trackinginformationen In der Instanz des ASCII-Flatfiles ist der Aufbau des Avisos mit Dummy-Daten beispielhaft ersichtlich. Zu beachten ist vor allem die richtige Verwendung der Satzart-Typen. IdentCode;ReferenceIdentcode;ColliRefNr;CustomerNumber;CustomerShipmentNr;ShpRefNr; T14:42:14.381;EventPostalCode;ParcelEventTypeCode;ParcelEventReasonCode;12.789; ;Origi ncustomernumber;consigneename;remark; t14:42: IdentCode1;ReferenceIdentcode1;ColliRefNr1;CustomerNumber1;CustomerShipmentNr1;ShpRefNr1; T15:42:14.000;EventPostalCode1;ParcelEventTypeCode1;ParcelEventReasonCode1;13.789; ; OriginCustomerNumber1;ConsigneeName1;Remark1; T15:42: IdentCode2;ReferenceIdentcode2;ColliRefNr2;CustomerNumber2;CustomerShipmentNr2;ShpRefNr2; T16:42:14.000;EventPostalCode2;ParcelEventTypeCode2;ParcelEventReasonCode2;14.789; ;OriginCustomerNumber2;ConsigneeName2;Remark2; T16:42:

12 4. Datenprotokolle Unterstützt wird der Datentransfer via (S)FTP und/oder (S)FTP Die Verbindung über (S)FTP wird wie folgt verwendet: Übertragung im Binärmodus Eindeutige Dateinamen Versand über SFTP-Postserver (Kunde holt sich Datei von Postserver ab) Versand an einen Kundenserver (nur FTP) Die Verbindung über wird wie folgt verwendet: Übertragung an eine oder mehrere Mailadresse Eindeutige Dateinamen der Trackingdateien Eine Trackingdatei als Attachments pro Mail Im Betreff steht folgender Standardsatz: Trackingdaten für Debitorennummer vom Versanddatum und uhrzeit Datum und Uhrzeit wird dabei im Format YYYYMMTThhmmss beschrieben. Beispiel: Trackingdaten von vom

13 5. Dateinamen Für die Übertragung wird eine Namensstruktur wie folgt verwendet: POSTAG_ Debitorennummer _ Datum und Uhrzeit _TE.XML/CSV Datum und Uhrzeit wird dabei im Format YYYYMMTThhmmss beschrieben. Beispiel: POSTAG_ _ _TE.xml POSTAG_ _ _TE.csv 6. Zeitfenster Trackingdaten werden zu bestimmten Zeitfenster an den Kunden gesendet. Dabei sind zwei Varianten möglich: 6.1. Periodisch Trackingdaten werden in einem angegeben Intervall gesendet, z.b. jede Stunde oder alle vier Stunden Fixe Zeitfenster Trackingdaten werden zu definierten Zeitfenstern gesendet. z.b.: jeden Tag um 03:00 Uhr oder jeden Tag um 04:00, 11:00, und 22:00 Uhr. 13

14 7. Benötigte Informationen Um einen Kunden Trackingdaten rückmelden zu können, werden folgende Informationen vom Kunden benötigt: Debitor Auftraggebernummer (Kundennummer) Firmenname Ansprechpartner Telefonnummer des Ansprechpartners Adresse des Ansprechpartners Bekanntgabe des gewünschte Datenformat (XML oder CSV) Bekanntgabe des gewünschten Datenprotokolls ((S)FTP oder ) Bekanntgabe zu welchen Zeitfenster(n) die Trackingdaten gesendet werden sollen 14

15 ANHANG: XML-Struktur TrackingEvents TrackingEvents: XML-Structure Root Level1 Level2 Type Lenght Example Occurence MaxOccurs Description TrackingEvent Parent M 1 Header Parent M 1 DebitorPayer Alphanum M 1 Number of the DebitorPayer Customer Alphanum. 80 Merck O 1 Name of the customer CreationDate DateTime T13:20: M 1 Timestamp of the Tracking-Data Creeation. Format: YYYY-MM-DDTHH:MM:SS.XXX EventCount Numeric M 1 Number of the TrackingEvents in the Tracking-Data File. Event Parent O unbounded IdentCode Alphanum M 1 Unique Parcel Identifier ReferenceIdentcode Alphanum O 1 Reference- (Original-) Parcel Identifier ColliRefNr Alphanum ABC O 1 Reference-Number of the Parcel used by the customer CustomerNumber Alphanum O 1 CustomerIdentcodeNumber CustomerShipmentNr Alphanum O 1 Reference-Number of the Shipment used by the customer ShpRefNr Alphanum. 40 AB O 1 Another Reference-Number of the Shipment used by the customer EventTimestamp DateTime T13:20: M 1 Timestamp of the Event Creation. Format: YYYY-MM-DDTHH:MM:SS.XXX EventPostalCode Alphanum M 1 Location (Postal Code) of the Event Creation ParcelEventTypeCode Alphanum. 3 ANA M 1 Code of the Event-Type ParcelEventReasonCode Alphanum. 3 AO M 1 Code of the Event-Reason Weight Decimal 7, O 1 Weight of the Parcel ParcelEventId Alphanum O 1 Unique Database-Id of the Event OriginCustomerNumber Alphanum O 1 CustomerNumber of the Customers Customer ConsigneeName Alphanum. 40 Huber O 1 Name of the Consignee, who received the parcel Remark Alphanum. 255 stiege fehlt O 1 Delivery remark InsertDate DateTime T13:21: O 1 InsertDate of the Event into the database 15

16 8. ANHANG: XML-Schema-Definition (XSD) TrackingEvents <?xml version="1.0" encoding="utf-16"?> <xs:schema xmlns:b=" xmlns=" targetnamespace=" xmlns:xs=" <xs:element name="trackingevent"> <xs:complextype> <xs:sequence> <xs:element minoccurs="1" maxoccurs="1" name="header"> <xs:complextype> <xs:sequence> <xs:element name="debitorpayer" type="xs:string" /> <xs:element minoccurs="0" name="customer" type="xs:string" /> <xs:element name="creationdate" type="xs:datetime" /> <xs:element name="eventcount" type="xs:string" /> </xs:sequence> </xs:complextype> </xs:element> <xs:element minoccurs="0" maxoccurs="unbounded" name="event"> <xs:complextype> <xs:sequence> <xs:element name="identcode" type="xs:string" /> <xs:element minoccurs="0" name="referenceidentcode" type="xs:string" /> <xs:element minoccurs="0" name="collirefnr" type="xs:string" /> <xs:element minoccurs="0" name="customernumber" type="xs:string" /> <xs:element minoccurs="0" name="customershipmentnr" type="xs:string" /> <xs:element minoccurs="0" name="shprefnr" type="xs:string" /> <xs:element name="eventtimestamp" type="xs:datetime" /> <xs:element name="eventpostalcode" type="xs:string" /> <xs:element name="parceleventtypecode" type="xs:string" /> <xs:element name="parceleventreasoncode" type="xs:string" /> <xs:element minoccurs="0" name="weight" type="xs:decimal" /> <xs:element minoccurs="0" name="parceleventid" type="xs:long" /> <xs:element minoccurs="0" name="origincustomernumber" type="xs:string" /> <xs:element minoccurs="0" name="consigneename" type="xs:string" /> <xs:element minoccurs="0" name="remark" type="xs:string" /> <xs:element minoccurs="0" name="insertdate" type="xs:datetime" /> </xs:sequence> </xs:complextype> </xs:element> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> 16

17

18 Österreichische Post AG Paketlogistik Österreich Operative IT Systeme Steinheilgasse 1, 1210 Wien Rechtsform: Aktiengesellschaft Sitz in politischer Gemeinde Wien FN d des Handelsgerichts Wien Druck- und Satzfehler vorbehalten.