Technical Whitepaper XML Schnittstelle Stand 25.11.2008
1. Setup und Abrechnung 1.1 Account Setup und eigenes Logo auf Lieferschein Folgende Daten werden von Ihnen benötigt - Rechnungsanschrift - Email-Adresse für Status-Meldungen (siehe 4.) - IP-Adresse für Freischaltung der Firewall - Logo. Hier steht Ihnen eine Fläche von 9x3cm zur Verfügung. Bitte legen Sie Ihr Logo in dieser Größe mit 300dpi an. Das Logo wird schwarz/weiß gedruckt Das Logo wird auf dem Lieferschein wie folgt platziert: 1.2 Abrechnung Abgerechnet wird jede bestellte Datei gemäß Preisliste. Dies beinhaltet auch die Berechnung von Versandkosten und ggf. Sperrgutzuschlägen. Eine Abrechnung findet monatlich durch posterxxl statt und ist innerhalb von 7 Tagen zur Zahlung fällig. 1.3 Ansprechpartner Abrechnung: Auftrag / Status: Isabelle Gail, 089-360359-28, isabelle.gail@karanga.net Peter Schneider, 089-360359-161, peter.schneider@posterxxl.com Technische Implementierung: Max Baum, 089-360359-241, max.baum@karanga.net Seite 2
2. Die Daten 2.1 Daten-Übertragung per FTP Zur Übertragung Ihrer Bestelldaten wird ein eigener FTP Account für Sie eingerichtet. Ihre Daten werden dort von Ihnen abgelegt und von uns regelmäßig in einem automatisierten Prozess abgeholt. Die Zugangsdaten erfahren Sie von Ihrem Ansprechpartner. Dateien, die nicht verarbeitet werden können, werden. Dateien, die verarbeitet werden können, werden an unsere Produktion. Status-Meldungen halten Sie während des gesamten Prozesses auf dem Laufenden (siehe 4.). Auf dem FTP-Server gibt es zwei verschiedene Ordner: INBOX: TEST: Hier legen Sie Ihre Aufträge ab. Nur dieser Ordner wird verarbeitet. Hier legen Sie Aufträge zu Testzwecken ab. Die Daten werden wie gewohnt verarbeitet, jedoch werden diese weder berechnet noch gedruckt noch versendet. Dies dient zur Prüfung, ob das Archiv korrekt gebaut wurde und ob Sie die Status-Meldungen erhalten. Nach dieser Testverarbeitung werden die Daten gelöscht. Seite 3
2.2 Bestell-Datei Pro Auftrag wird eine Datei übertragen, welche als GZIP-komprimiertes TARBALL-Archiv alle notwendigen Auftrags-Dateien enthält. Der Dateiname setzt sich wie folgt zusammen. <coop_id>_<date>_<number>.tar.gz coop_id: ist die Händlernummer die wir an Sie vergeben date: Das Auftrags-Datum im Format YYYYMMDD number: Laufende Nummer, beginnt pro Tag mit 1. (die wievielte Bestellung ist das an diesem Tag) Die Reihenfolge der Aufträge muss nicht mit der laufenden Nummer übereinstimmen. Die laufende Nummer dient dazu, den Auftrag eindeutig zu identifizieren und muss daher pro Tag eindeutig sein. Beispiel: 1234567_20080404_3.tar.gz 2.3 Enthaltene Dateien Beispiel: 1234567_20080404_3.tar.gz enthält: bestellung.xml image_1.jpg image_2.jpg frei wählbar, jedoch im XML gleichen Namen verwenden frei wählbar, jedoch im XML gleichen Namen verwenden Seite 4
2.4 Beispiel-XML <?xml version="1.0" encoding="utf-8"?> <order> <address> <salutation>herr</salutation> <firstname>max</firstname> <lastname>mustermann</lastname> <street>musterweg 1</street> <city>münchen</city> <postcode>80797</postcode> <company /> <address_add /> <country>de</country> <greeting /> <email>max.mustermann@karanga.net</email> </address> <items> <item id="1"> <filename>image_1.jpg</filename> <original_filename>dsc10009.jpg</original_filename> <product_id>p02-std-400x400</product_id> <quantity>1</quantity> </item> <item id="2"> <filename>image_2.jpg</filename> <original_filename>winterlandschaft.jpg</original_filename> <product_id>p02-u01-1200x300</product_id> <quantity>5</quantity> </item> </items> <coop_id>123456</coop_id> <date>20080801</date> <number>1</number> </order> Alle Felder außer company, address_add und greeting sind MUSS-Felder! Zusätzliche Erklärungen: company address_add greeting country product_id Kann zusätzlich den Firmennamen des Empfängers enthalten. Zusätzliche Information, wie z.b. 2. Etage. Kurzer Grußtext, der auf dem Lieferschein erscheint. Der Parameter country muss den 2-stelligen Ländercodes gemäß ISO-3166 entsprechen. Die product_id (Artikel-Nummer)können Sie der beigefügten Preisliste entnehmen. Seite 5
3. Zuschnitt von Bildern Generell sollten Sie darauf achten, dass Bilder immer zum ausgewählten Format passen. Beispiel: Produkt Poster 40x30cm product_id: p02-std-400x300 Datei sollte dann z.b. 4000x3000 Pixel (oder z.b. 2000x1500 Pixel) groß sein. Passt die Datei nicht korrekt, dann wird die Datei soweit vergrößert, dass die gesamte Druckfläche von dem Bild bedeckt ist und überstehende Ränder werden abgeschnitten. Beispiel: Bild 5000x3000 Pixel und Zielformat 40x30 cm Bei diesem Bild würde das zu unschönen Effekten führen: Bei diesem Bild wäre es ein geringeres Problem: Seite 6
4. Status-Meldungen Verschiedene Status-Meldungen halten Sie während des gesamten Prozesses auf dem Laufenden. Sie werden über den aktuellen Stand einer Bestellung ebenso informiert, wie über mögliche Fehler in der Übertragung. 4.1 Übertragung der Status-Meldungen Sie können sämtliche Status-Meldungen per Email oder per HTTP(S) erhalten. 4.1.1 Per Email Auf Wunsch schicken wir die Status-Meldungen an die von Ihnen angegebene Email-Adresse (siehe 1.1). Seite 7
4.1.2 Per HTTP(S) in der Push-Variante In der Push-Variante senden wir den neusten Status jedes Auftrags direkt an ein Skript von Ihnen. Die Übertragung der Daten erfolgt per POST-Befehl als XML. Ihr Skript sendet nach Empfang ein [OK] an uns zurück und bestätigt damit den Erhalt. Parameter-Name: xml Inhalt des Parameters: <?xml version="1.0" encoding="utf-8"?> <status_report> <job>123456_20080801_1</job> <date>20080801</date> <order> <number>da-1a123-12345</number> <dpd> <number>01805123456789</number> <status>new</status> </dpd> </order> <status> <code>001</code> <text>auftrag erfolgreich importiert</text> </status> </status_report> Erklärung der Parameter: <job>der Name des Auftrags, bestehend aus <coop_id>_<date>_<number> <date>yyyymmdd <order>enthält Auftragsdaten von posterxxl <number>interne Auftragsnummer posterxxl <dpd>enthält DPD-Versanddaten des Auftrags <number>dpd-nummer zur Nachverfolgung <status> new : Neues DPD-Paket sent : DPD-Paket wurde versendet <code>status-code 001 : Auftrag erfolgreich importiert 002 : Auftrag wird produziert 003 : Teilauftrag wird versendet 004 : Auftrag komplett versendet und abgeschlossen 100 : Fehler! ZIP-File konnte nicht verarbeitet werden 101 : Fehler! Auftragsdaten sind nicht korrekt 102 : Fehler! Auftrag bereits vorhanden <text>status-text, siehe Erklärung von Status-Code Seite 8
4.1.3 Per HTTP(S) in der Pull-Variante In der Pull-Variante können Sie jederzeit den Status eines Auftrags abrufen. Der Aufruf erfolgt unter Einbeziehung Ihrer Zugangsdaten über folgendes Skript: https://www.posterxxl.de/partnerstatus Sie übergeben den Auftrag per POST-Befel über den Parameter job und erhalten von uns das XML (siehe 4.1.2) mit den aktuellen Details zum Auftrag zurück. Zusätzlich übermitteln Sie Ihren Benutzernamen und das dazugehörige Passwort. Parameter-Name: job Wert des Parameters: <coop_id>_<date>_<number> Parameter-Name: user Wert des Parameters: Ihr Benutzername Parameter-Name: pass Wert des Parameters: Ihr Passwort Seite 9
4.2 Alle Status-Meldungen im Überblick Event 001 - Auftrag erfolgreich importiert Alle Daten eines Auftrags wurden erfolgreich importiert und Bilder und XML passen zusammen. Event 002 - Auftrag wird produziert Der Auftrag befindet sich in Produktion und wird verarbeitet. Die Produktionszeiten variieren von Produkt zu Produkt. Event 003 - Teilauftrag wird versendet Besteht der Auftrag aus mehreren Produkten unterschiedlicher Materialen, findet unter Umständen ein Teilversand statt. In diesem Fall werden mehrere DPD-Nummern angegeben. Event 004 - Auftrag komplett versendet und abgeschlossen Der Auftrag wurde erfolgreich versendet und ist damit komplett abgeschlossen. Fehler 000 Auftrag konnte nicht gefunden werden Zu der gesuchten Auftragsnummer konnte kein Auftrag gefunden werden. Fehler 100 ZIP-File konnte nicht verarbeitet werden Möglicherweise wurde die Datei nicht gezippt oder es liegt ein Übertragungsfehler vor. Fehler 101 Auftragsdaten sind nicht korrekt Entweder fehlen Bilder in Ihrer Datei, welche im XML referenziert sind oder es sind Bilder in der Datei enthalten, welche nicht im XML referenziert sind. Fehler 102 Auftrag bereits vorhanden Wenn Sie den gleichen Auftrag erneut hochladen, zu dem bereits eine Fehlermeldung vorliegt, wird dieser nicht verarbeitet. Bitte ändern Sie hierzu Ihre Auftragsnummer. Seite 10