Handbuch zur Instant Order Processing Notification API Eine Anleitung für Entwickler, die automatisch Benachrichtigungen zu Bestellungen erhalten möchten.

Annika Munz

2 | OpenTopic | | Einleitung

OpenTopic | Inhaltsverzeichnis | 3

Inhalt Überblick über die IOPN API............................................................................................. 5 Voraussetzungen für die Nutzung der IOPN-API....................................................................................5 Ihre Aufgaben bei Nutzung der IOPN-API..............................................................................................5 Letzte Änderungen in diesem Dokument.................................................................................................5

Kapitel 1: Überblick über Bestellbenachrichtigungen................................. 7 Inhalt der Bestellbenachrichtigung...........................................................................................................8 Bestellbenachrichtigungsarten................................................................................................................. 8 Benachrichtigung über eine neue Bestellung............................................................................... 8 Benachrichtigung über eine versandbereite Bestellung............................................................... 8 Benachrichtigung über eine stornierte Bestellung....................................................................... 8 Der Ablauf von Bestellbenachrichtigungen............................................................................................. 8

Kapitel 2: IOPN-APIs aktivieren................................................................. 11 Seller Central verwenden....................................................................................................................... 12 Endpunkt-URL eintragen oder ändern....................................................................................... 12 API zur Inline-Integration verwenden....................................................................................................12 Erneute Benachrichtigungsversuche...................................................................................................... 12

Kapitel 3: Benachrichtigungen erhalten und verarbeiten......................... 13 Der Inhalt der Benachrichtigung............................................................................................................ 14 Die UUID................................................................................................................................... 15 Der Zeitstempel.......................................................................................................................... 15 Die Signatur................................................................................................................................15 Die Benachrichtigungsart (NotificationType)............................................................................15 Die Benachrichtigungsdaten (NotificationData)........................................................................ 16 Der Access Key.......................................................................................................................... 18

Kapitel 4: Benachrichtigungs-Anfrage verarbeiten................................... 19 Daten parsen........................................................................................................................................... 20 Gültigkeit der Benachrichtigungs-Anfrage verifizieren.........................................................................20 Signatur abgleichen.................................................................................................................... 20 Zeitstempel abgleichen...............................................................................................................20 Daten verarbeiten................................................................................................................................... 20 Anfrage beantworten.............................................................................................................................. 20

Kapitel 5: Benutzerdefinierte Datenfelder verwenden...............................21 Voraussetzungen für die Nutzung von benutzerdefinierten Datenfeldern............................................. 22 Wie wir benutzerdefinierte Datenfelder verarbeiten.............................................................................. 22 Benutzerdefinierte Datenfelder in der order.xml-Datei verwenden.......................................................22 Benutzerdefinierte Datenfelder mit der IOPN-API verwenden............................................................. 23 Benutzerdefinierten XML-Namensraum verwenden............................................................................. 24

Anhang A: Das IOPN-API-Schema............................................................. 27 Das IOPN-API-Schema..........................................................................................................................28

4 | OpenTopic | Inhaltsverzeichnis

Anhang B: Häufig gestellte Fragen.............................................................. 33

Überblick über die IOPN API Mithilfe der Instant Order Processing Notification API (kurz IOPN-API, deutsch: Schnittstelle zur sofortigen Bestellverarbeitungsbenachrichtigung) werden Sie über alle neuen Bestellungen durch Bezahlen über Amazon sowie Statusänderungen bestehender Bestellungen informiert. Wenn Sie solche Benachrichtigungen erhalten, können Sie diese für die Bestellverarbeitung an Ihr internes Bestellverwaltungssystem weitergeben. Eine sofortige Bestellbenachrichtigung besteht aus einer XML-Datei, die per HTTPS POST übermittelt wird, wenn eine Bestellung aufgeben oder geändert wird. Damit Sie die Instant Order Processing Notification API nutzen können, müssen Sie einen Webservice verwenden, der die Benachrichtigungen von Bezahlen über Amazon annehmen und an Ihr internes Bestellverwaltungssystem weitergeben kann. Dieses Dokument zeigt Ihnen die Typen und Strukturen der verschiedenen Benachrichtigungen. Außerdem erläutert dieses Dokument, wie Sie die Benachrichtigungen aktivieren, autorisieren und verarbeiten können.

Voraussetzungen für die Nutzung der IOPN-API Damit Sie die Instant Order Processing Notification API nutzen können, muss Ihr System die folgenden Voraussetzungen erfüllen: 1. Wenn Sie die Standard-Integration nutzen, müssen Sie die order.xsd in der Version 2009-05-15 oder neuer verwenden. (Laden Sie hier die neueste Version herunter.) 2. Sie müssen die iopn.xsd in der Version 2008-11-30 oder neuer verwenden. (Laden Sie hier die neueste Version herunter.) 3. Sie müssen einen Webservice betreiben, der HTTPS-POST-Anfragen über Port 443 empfangen und verarbeiten kann. 4. Ihr HTTPS-Protokoll muss ein gültiges SSL-Zertifikat von einem vertrauenswürdigen Anbieter verwenden. Eine Liste aller akzeptierten SSL-Zertifikat-Provider finden Sie in der Hilfe von Amazon Payments: SSL-Zertifikate und die Callback-API.

Ihre Aufgaben bei Nutzung der IOPN-API Sie müssen zwei Aufgaben erledigen, wenn Sie die Instant Order Processing Notification API verwenden: 1. IOPN-APIs aktivieren 2. Daten verarbeiten Dieses Dokument erklärt Ihnen, wie Sie diese beiden Aufgaben bewältigen können.

Letzte Änderungen in diesem Dokument Version

Datum

Änderungen

3.0

15.03.2012

Veröffentlichung der deutschen Übersetzung

2.0

01.02.2012

Vollständige Überarbeitung des Dokuments

1.0

01.02.2009

Dokument erstmalig veröffentlicht

6 | OpenTopic | Überblick über die IOPN API

Kapitel

1 Überblick über Bestellbenachrichtigungen Themen: • • •

Inhalt der Bestellbenachrichtigung Bestellbenachrichtigungsarten Der Ablauf von Bestellbenachrichtigungen

Der folgende Abschnitt beschreibt die Inhalte und die Arten der Bestellbenachrichtigungen, die Sie empfangen können.

8 | OpenTopic | Überblick über Bestellbenachrichtigungen

Inhalt der Bestellbenachrichtigung Hier sehen Sie das Format des Inhalts einer Bestellbenachrichtigung. Für weitere Details zu den Parametern lesen Sie bitte Anhang A- Das IOPN-API Schema.

Bestellbenachrichtigungsarten Bei Bestellbenachrichtigungen handelt es sich um HTTPS-POST-Anfragen mit als XML-Datei formatierten Benachrichtigungsdaten. Sie können drei verschiedene Benachrichtigungen empfangen: 1. Benachrichtigung über eine neue Bestellung 2. Benachrichtigung über eine versandbereite Bestellung 3. Benachrichtigung über eine stornierte Bestellung

Benachrichtigung über eine neue Bestellung Wir senden Ihnen diese Benachrichtigung, wenn eine neue Bestellung aufgegeben wurde. Diese Benachrichtigung wird sofort dann geschickt, nachdem die Bestellung erstmalig angelegt wurde. Hinweis: Versenden Sie die Bestellung noch nicht, wenn Sie eine Benachrichtigung über eine neue Bestellung erhalten. Bitte warten Sie mit dem Versand, bis Sie die Benachrichtigung erhalten, dass die Bestellung versandbereit ist.

Benachrichtigung über eine versandbereite Bestellung Wir senden Ihnen diese Benachrichtigung, wenn wir die Zahlungsart des Käufers autorisiert haben. Sobald Sie diese Benachrichtigung erhalten, können Sie die Bestellung versenden.

Benachrichtigung über eine stornierte Bestellung Wir senden Ihnen eine solche Benachrichtigung, wenn die Bestellung storniert wurde. Eine Bestellung kann vom Händler, vom Käufer oder von Amazon Payments storniert werden. Hinweis: In der Benachrichtigungen werden keine Details zur Stornierung übermittelt.

Der Ablauf von Bestellbenachrichtigungen Das Bild zeigt den Ablauf von Bestellbenachrichtigungen, d. h. die Reihenfolge, in der die Benachrichtigungen bei Ihnen eintreffen. Beachten Sie, dass durch diese Benachrichtigungen verursachte Statusänderungen in Gelb angezeigt werden.

OpenTopic | Überblick über Bestellbenachrichtigungen | 9

In einigen Fällen kann es vorkommen, dass die Benachrichtigung über eine neue Bestellung erst nach der Benachrichtigung über eine versandbereite oder stornierte Bestellung eintrifft. Für weitere Informationen lesen Sie bitte den Abschnitt Warum habe ich noch vor der Bestellbenachrichtigung eine Benachrichtigung über eine versandbereite oder stornierte Bestellung erhalten?.

10 | OpenTopic | Überblick über Bestellbenachrichtigungen

Kapitel

2 IOPN-APIs aktivieren Themen: • • •

Seller Central verwenden API zur Inline-Integration verwenden Erneute Benachrichtigungsversuche

12 | OpenTopic | IOPN-APIs aktivieren

Seller Central verwenden Melden Sie sich in Seller Central an und tragen Sie eine Händler-URL (Enpunkt-URL Ihres Webservices), eine Integrationsdienstleister-URL (Endpunkt-URL des Webservices Ihres Integrationsdienstleisters) oder beide ein, um die Instant Order Processing Notification API zu aktivieren. Sie müssen mindestens eine Endpunkt-URL eingeben, um die IOPN-API zu aktivieren. Wenn Sie keinen Integrationsdienstleister haben, können Sie das Feld für die Integrationsdienstleister-URL freilassen.

Endpunkt-URL eintragen oder ändern Befolgen Sie diese Schritte, um die Einstellungen zur Endpunkt-URL zu bearbeiten: 1. Melden Sie sich in Seller Central an. 2. Klicken Sie auf Einstellungen > Einstellungen zum Bestellprozess und anschließend auf Ändern. 3. Tragen Sie unter "Händler-URL" die Endpunkt-URL Ihres Webservices ein, die Benachrichtigungen akzeptiert. Denken Sie daran, für ein Produktiv-Konto https:// zu verwenden. 4. Optional: Falls Sie einen Integrationsdienstleister haben, der über die Änderungen am Bestellstatus informiert werden muss, dann tragen Sie unter "URL des Integrationsdienstleisters" die Endpunkt-URL ein, unter der Ihr Integrationsdienstleister Benachrichtigungen akzeptiert. Denken Sie daran, für ein Produktiv-Konto https:// zu verwenden. 5. Klicken Sie auf Aktualisieren.

API zur Inline-Integration verwenden Hinweis: Alle Einstellungen, die Sie über die API zur Inline-Integration vornehmen, werden gegenüber den Einstellungen in Seller Central bevorzugt.

Erneute Benachrichtigungsversuche Der nachfolgende Abschnitt erklärt, wie erneute Benachrichtigungsversuche an die Endpunkte gehandhabt werden. • • •

Wenn sowohl die Händler-URL als auch die Integrationsdienstleister-URL eingetragen wurden, dann werden die Benachrichtigungen an beide Endpunkte gesendet. Wenn nur einer dieser Endpunkte eingetragen wurde, dann werden die Benachrichtigungen nur an diesen Endpunkt gesendet. Wenn einer dieser Endpunkte nicht erreichbar ist, dann werden die Neuversuche ausschließlich für diesen Endpunkt durchgeführt.

Wenn eine Endpunkt-URL nicht erreichbar ist oder nicht auf die Benachrichtigungsanfrage antwortet, dann wird die Benachrichtigung wie in der Backoff-Regelung beschrieben erneut zu dieser URL gesendet. Hinweis: Sie müssen mindestens eine EndpunktURL eingeben, wenn Sie die Instant Order Processing Notification API verwenden.

Kapitel

3 Benachrichtigungen erhalten und verarbeiten Themen: •

Der Inhalt der Benachrichtigung

Um die Instant Order Processing Notfication API zu aktivieren, müssen Sie einen Webservice aufbauen, der "Bezahlen über Amazon"Benachrichtigungen empfangen und verarbeiten kann. Ihr Webservice muss mittels SSL v3 oder TLS gesichert sein, außerdem müssen Sie ein gültiges SSL-Zertifikat verwenden. Die URL, die Sie für Ihr Produktiv-Konto verwenden, muss HTTPS und den Standard-SSL-Port 443 verwenden. Die URL, die Sie für Ihr Sandbox-Konto verwenden, kann entweder HTTPS mit Port 433 oder HTTP mit Port 80 verwenden. Hinweis: Wenn Ihr Endpunkt nicht erreichbar ist, wird Bezahlen über Amazon 14 Tage lang versuchen, die Benachrichtigung erneut zu senden. Zu weiteren Informationen zur Häufigkeit der Neuversuche lesen Sie bitte die Erklärung zur BackoffRegelung. Eine Liste aller akzeptierten SSLZertifikat-Provider finden Sie im Hilfe-Thema SSL-Zertifikate und die Callback-API. Bezahlen über Amazon beglaubigt die Benachrichtigungen mittels einer Signatur, die unter Einbeziehung des Seller Central Secret Access Keys generiert wird. Die folgenden Abschnitte erläutern die Inhalte der Benachrichtigungen. Hinweis: Verwenden Sie den Seller Central Secret Access Key zur Validierung und um Signaturen für Anfragen und Antworten zu generieren. Sie finden diesen in Seller Central unter Integration > Access Key .

14 | OpenTopic | Benachrichtigungen erhalten und verarbeiten

Der Inhalt der Benachrichtigung Die Benachrichtigung, die wir Ihnen senden, besteht aus einem einfachen URL-kodierten und UTF-8-formatierten String. Die Anfrage enthält die folgenden sechs Blöcke: Block

Erklärung

Einsatz

1. Die UUID (UUID)

UUID steht für Universally Unique Identifier, eine eindeutige ID, und wird für jede Benachrichtigung neu generiert, ganz egal, ob es sich um die Erstbenachrichtigung oder um einen Neuversuch handelt.

Nur für signierte Einkaufswagen.

2. Der Zeitstempel (Timestamp)

Der Zeitpunkt der Anfrage (GMT). Der Zeitstempel wird für jede Benachrichtigung neu generiert, ganz egal, ob es sich um die Erstbenachrichtigung oder um einen Neuversuch handelt.

Nur für signierte Einkaufswagen.

3. Die Signatur (Signature)

Die Signatur wird aus der UUID, dem Zeitstempel und Ihrem Seller Central Secret Access Key berechnet.

Nur für signierte Einkaufswagen.

4. Die Benachrichtigungsart (NotificationType)

Enthält eine der folgenden Benachrichtigungsarten: NewOrderNotification (neue Bestellung), OrderReadyToShipNotification (Bestellung versandbereit) oder OrderCancelledNotification (Bestellung storniert).

Für signierte und unsignierte Einkaufswagen.

5. Die Benachrichtigungsdaten (NotificationData)

Der Inhalt (Body) der Anfrage.

Für signierte und unsignierte Einkaufswagen.

6. Der Access Key (AWSAccessKeyId)

Die Seller Central Access Key ID, die zur Signierung des Einkaufswagens genutzt wird.

Nur für signierte Einkaufswagen.

Beachten Sie, dass die Groß- und Kleinschreibung bei den Namen (z.B. AWSAccessKeyId) eingehalten werden muss. Diese Anfrage besteht aus einem Set von Schlüssel-Wert-Paaren, die zu einem String zusammengefasst wurden und bei dem jedes Schlüssel-Wert-Paar durch ein "&"-Zeichen getrennt ist. Der Schlüssel wird im Klartext übermittelt, der Wert ist URL-kodiert. Die Anfrage enthält die folgenden Schlüssel-Wert-Paare. Die Reihenfolge ist nicht wichtig (die Leerzeichen dienen der Übersichtlichkeit): UUID=[UUID_value] & Timestamp = [Timestamp_value] & Signature = [Signature_value] & NotificationType = [notification_type] & NotificationData = [notification_data_value] & AWSAccessKeyId = [ AWSAccessKeyId_value]

OpenTopic | Benachrichtigungen erhalten und verarbeiten | 15 Hier sehen Sie ein Beispiel einer neuen Bestellungsbenachrichtigung (Leerzeichen und Zeilenumbrüche dienen der Übersichtlichkeit): UUID=5d1769d2 b217 4981 a499 fbad1b9acf15 &Timestamp=2009 01 20T06%3A41%3A20.471Z&AWSAccessKeyId=AKIAJC2EVPPNIFRXIVKQ &Signature=Ltu1alXSqkyZRqzVSjI%2BDPuWQms%3D &NotificationType=NewOrderNotification &NotificationData=%3C%3Fxml%20version %3D%221.0%22%20encoding%3D%22UTF 8%22%3F%3E%0A%3CNewOrderNotification%20xmlns %3D%22http%3A%2F %2Fpayments.amazon.co.uk%2Fcheckout%2F2009 05 15%2F%22%3E%0A %20%20%3 [..] Beachten Sie, dass der Schlüssel in Klartext (fett markiert) angezeigt wird und der Wert URL-kodiert ist. Das "&"Zeichen dient als Trennzeichen. Der folgende Abschnitt erklärt die sechs Blöcke einer Benachrichtigung und erläutert, wie Sie diese nutzen können, um Ihre Antwort zu generieren.

Die UUID Die UUID (Universally Unique Identifier) ist ein String, der vom MWS (Marketplace Webservices) generiert wird. Hier sehen Sie ein Beispiel einer UUID, wie sie in der Anfrage an Sie übermittelt wird: UUID=d6a58609-d9ea-415c-95c6-d7c2528fca09 Sie verwenden diese UUID, um eine Signatur zu berechnen und zu bestätigen, dass die Anfrage gültig ist. (Wenn Sie signierte Einkaufswagen nicht unterstützten, werden Sie diese UUID in Ihrer Händleranfrage nicht erhalten.)

Der Zeitstempel Der Zeitstempel besteht aus dem Datum und der Uhrzeit, zu der die Anfrage von unseren Servern verschickt wurde. Hier sehen Sie einige Beispiele für Zeitstempel aus der Anfrage, die Sie erhalten: Timestamp=2011-11-14T20%3A57%3A07.146Z Diese Benachrichtigung wurde am 14. November 2011 um 8:57:07 Uhr GMT (Greenwich Mean Time) oder 9:57:07 Uhr MEZ (Mitteleuropäische Zeit) abgeschickt. Timestamp=2011-06-21T18%3A34%3A06.125Z Diese Benachrichtigung wurde am 21. Juni 2011 um 18:34:06 Uhr GMT oder 20:34:06 MEZS (Mitteleuropäische Sommerzeit) abgeschickt. Sie nutzen diesen Zeitstempel später, wenn Sie Ihre Signatur berechnen, um diese mit der Signatur der Anfrage abzugleichen. (Wenn Sie signierte Einkaufswagen nicht unterstützten, werden Sie diesen Zeitstempel in Ihrer Händleranfrage nicht erhalten.)

Die Signatur Um eine URL-kodierte Signatur zu generieren, verketten wir die UUID und den Zeitstempel und fügen einen Standard-Signatur-Algorithmus mit Ihrem in Seller Central eingetragenen Access Key hinzu. (Wenn Sie signierte Einkaufswagen nicht unterstützten, werden Sie diese Signatur in Ihrer Händleranfrage nicht erhalten.) Hier sehen Sie ein Beispiel einer Signatur, wie sie in der Anfrage an Sie übermittelt wird. Signature=MRYUB4bk%2B3ehw0BAbzk6mp6SxXw%3D Sie benötigen diese Signatur zum Abgleich mit Ihrer eigenen Signatur, um die Gültigkeit der Anfrage zu bestätigen.

Die Benachrichtigungsart (NotificationType) Der NotificationType bezeichnet die verschiedenen Benachrichtigungstypen. Die folgenden Werte sind möglich: • •

NewOrderNotification (Benachrichtigung über eine neue Bestellung) OrderReadyToShipNotification (Benachrichtigung über eine versandbereite Bestellung)

16 | OpenTopic | Benachrichtigungen erhalten und verarbeiten •

OrderCancelledNotification (Benachrichtigung über eine stornierte Bestellung)

Hier sehen Sie ein Beispiel für die Benachrichtigungsart, wie sie in der Anfrage an Sie übermittelt wird: NotificationType=NewOrderNotification

Die Benachrichtigungsdaten (NotificationData) NotificationData enthält den URL-kodierten Inhalt des Einkaufswagens. Hier sehen Sie ein Beispiel der URL-kodierten Benachrichtigungsdaten. NotificationData=%3c%3fxml+version%3d%221.0%22+encoding%3d%22UTF 8 %22%3f%3e%3cNewOrderNotification+xmlns%3d%22http%3a%2f%2fpayments.amazon.de %2fcheckout%2f2009 05 15%2f%22%3e%3cNotificationReferenceId[..] Hier sehen Sie dieselben Informationen einer neuen Bestellbenachrichtigung (NewOrderNotification) in Form einer lesbaren XML-Datei. Bitte lesen Sie Anhang A - Das IOPN-API-Schema für weitere Informationen zur Benachrichtigung über eine versandbereite Bestellung (OrderReadyToShip) und über eine stornierte Bestellung (OrderCancelled). ae51d3a6-7843-4cbb-ad1d-ee8cc591e10d Amazon Checkout 101-1234567-9876543 2009-08-31 Jana Müller [email protected] Jana Müller Marcel-Breuer-Straße 12 München Bayern 80807 DE Standard 12345 AEIOU1234AEIOU ABC123 Roter Fisch Ein roter Fisch in frischem Quellwasser. 12345 miq://rose:1.0/cart/cba:1.0/cart:2.0/ AEIOU1234AEIOU/AEIOU1234AEIOU/1-1232431180394-57EEF607E6D40DB5 VWXYZ98765VWXYZ Amazon 5.0 EUR 1 1.0 kg

OpenTopic | Benachrichtigungen erhalten und verarbeiten | 17 MERCHANT Principal 5.0 EUR Shipping 0.0 EUR Tax 0.0 EUR ShippingTax 0.0 EUR PrincipalPromo 0.0 EUR ShippingPromo 0.0 EUR NotificationData enthält die NotificationReferenceId (eine eindeutige ID, die für jede Benachrichtigung genieriert wird) und ProcessedOrders (Bestelldetails zu der Bestellung, für die die Benachrichtigung verschickt wurde). ProcessedOrders enthält die Details der order.xml-Datei, die auf Ihrer Website abgeschickt wurde (zum Beispiel Lagerhaltungsnummer (SKU), Artikelname, Artikelbeschreibung, Menge, Preis). ProcessedOrders enthält außerdem die Kosten, die auf Artikelebene berechnet wurden. Die Kosten bestehen aus: Principal (Artikelpreis multipliziert mit der Menge), Shipping (Versandkosten für einen Artikel), PrincipalPromo und ShippingPromo (Werberabatte, die für den Artikelpreis oder die Versandkosten gelten). Die Werte Tax und ShippingTax (Steuern) werden aktuell für "Bezahlen über Amazon"-Bestellungen in Europa nicht unterstützt und deshalb immer mit 0.0 Euro ausgegeben. Hinweis:

18 | OpenTopic | Benachrichtigungen erhalten und verarbeiten Wir generieren eine neue NotificationReferenceId für jede Benachrichtigung, die wir für eine neue Bestellung versenden. Wenn wir versuchen, eine Bestellbenachrichtigung für dieselbe Bestellung noch einmal zuzustellen, verwenden wir dieselbe NotificationReferenceId wie in der ersten Benachrichtigung. Versenden Sie die Bestellung erst, wenn Sie die Benachrichtigung erhalten, dass die Bestellung versandbereit ist.

Der Access Key Der Access Key (AWSAccessKeyId) ist ein Teil Ihrer Seller Central Access-Key-Paare (Secret Access Key und Access Key ID). Dieser Access Key wird in der Benachrichtigung zurückgeliefert.

Kapitel

4 Benachrichtigungs-Anfrage verarbeiten Themen: • •

• •

Daten parsen Gültigkeit der Benachrichtigungs-Anfrage verifizieren Daten verarbeiten Anfrage beantworten

Verwenden Sie die Informationen aus der Benachrichtigungs-Anfrage (sowohl den XML-Inhalt, als auch die anderen Informationen in der Anfrage), um die folgenden Aktionen durchzuführen: 1. 2. 3. 4.

Analysieren Sie die Daten. Gültigkeit der Benachrichtigungs-Anfrage verifizieren. Daten verarbeiten. Anfrage beantworten.

Ihre Anwendung muss diese Anfrage analysieren, um zu bestätigen, dass die Benachrichtigung tatsächlich von Amazon Payments stammt. Anschließend müssen die Informationen für die Berechnungen verarbeitet und eine Antwort vorbereitet werden.

20 | OpenTopic | Benachrichtigungs-Anfrage verarbeiten

Daten parsen Ihr erster Schritt besteht darin, die angefragten Daten zu parsen. Beachten Sie dabei, dass das "&"-Zeichen die Werte voneinander trennt und dass die Anfrage URL-kodiert ist.

Gültigkeit der Benachrichtigungs-Anfrage verifizieren Nachdem Sie die Daten erhalten und geparst haben, sollten Sie die Signatur und den Zeitstempel prüfen, um sich zu versichern, dass die Anfrage gültig ist. Durch den Datenabgleich können Sie vermeiden, dass Anfragen beantwortet werden, die nicht von Amazon Payments stammen.

Signatur abgleichen Vergleichen Sie die von uns generierte Signatur mit der von Ihnen generierten Signatur, um zu verifizieren, dass die Anfrage echt ist. Generieren Sie die Signatur, indem Sie die URL-kodierte UUID und den Zeitstempel der originalen Anfrage entschlüsseln, UUID und Zeitstempel verketten und die Signatur anschließend mithilfe eines StandardHMAC-SHA1-Algorithmus und Ihres Seller Central Secret Access Key generieren. Hinweis: Sie finden den Secret Access Key in Seller Central unter Integration > Access Key .

Zeitstempel abgleichen Zur Vermeidung von Replay-Angriffen sollten Sie den Zeitstempel in der Benachrichtigung mit Ihrer Systemuhrzeit abgleichen. Verarbeiten Sie die Benachrichtigung nicht, wenn die Differenz mehr als 15 Minuten beträgt. Hinweis: Wir empfehlen eine Synchronisierung Ihrer Systemuhr mit einer Atomuhr. Wenn die Systemuhrzeit nicht korrekt ist, kann es passieren, dass Sie gültige Anfragen löschen. Wir empfehlen außerdem, dass Sie alle Benachrichtigungen speichern, so dass Sie die UUID und den Zeitstempel vergleichen können, um zu gewährleisten, dass jede Benachrichtigung einmalig ist. Nachdem Sie den Zeitstempel abgeglichen haben, können Sie die Vearbeitung der XML-Datei fortsetzen.

Daten verarbeiten Nachdem Sie die Benachrichtigungen erhalten haben, können Sie diese auswerten, an Ihre Lagerverwaltung weiterleiten und sie für Ihre interne Bestellbearbeitungssysteme verwenden. Wenn Sie eine Benachrichtigung über eine versandbereite Bestellung (OrderReadyToShip) erhalten, müssen Sie die Bestellung versenden und den Versand gegenüber Amazon bestätigen.

Anfrage beantworten Bei einer erfolgreichen Annahme der Anfrage erwartet Bezahlen über Amazon den HTTP-Status-Code "200 OK". Alle anderen Antworten bewirken, dass Bezahlen über Amazon versucht, die Benachrichtigung erneut zu senden.

Kapitel

5 Benutzerdefinierte Datenfelder verwenden Themen: •

• •

• •

Voraussetzungen für die Nutzung von benutzerdefinierten Datenfeldern Wie wir benutzerdefinierte Datenfelder verarbeiten Benutzerdefinierte Datenfelder in der order.xml-Datei verwenden Benutzerdefinierte Datenfelder mit der IOPN-API verwenden Benutzerdefinierten XMLNamensraum verwenden

Sie können Ihre eigenen Datendefinitionen und Datenfelder in Ihrer order.xml-Datei verwenden. Wenn Sie zum Beispiel Tassen und Becher verkaufen wollen, die Ihre Kunden personalisieren können, dann können Sie das benutzerdefinierte Textfeld "cust_name" in Ihrer order.xml übermitteln. Wir werden diese Information zur Bestellbenachrichtigung hinzufügen.

22 | OpenTopic | Benutzerdefinierte Datenfelder verwenden

Voraussetzungen für die Nutzung von benutzerdefinierten Datenfeldern Zur Nutzung von benutzerdefinierten Datenfeldern in Ihren Feeds muss Ihre XML-basierte Anwendung die folgenden Bedingungen erfüllen: 1. Sie müssen den XML-Namensraum (XMLNS) "http://payments.amazon.com/checkout/2009-05-15/" oder neuer verwenden. 2. Wenn Sie die Standard-Integration nutzen, müssen Sie die order.xsd vom 04.03.2009 oder neuer verwenden. (Laden Sie hier die neueste Version herunter.) 3. Sie müssen die iopn.xsd in der Version vom 04.03.2009 oder neuer verwenden. (Laden Sie hier die neueste Version herunter.)

Wie wir benutzerdefinierte Datenfelder verarbeiten Wenn wir Ihre order.xml-Datei mit Ihrer Antwort auf die Benachrichtigung oder Ihre Callback-Antwort mit benutzerdefinierten Daten erhalten, speichern wir diese einfach, bis wir sie als Teil der Instant Order Processing Notification zurückgeben. Wir parsen die Daten nicht und versuchen auch nicht, sie zu interpretieren. Solange der Inhalt syntaktisch korrekt ist (die Tags sind richtig geschrieben und nicht falsch gegeliedert, oder ähnliches) akzeptieren wir den Inhalt wie er ist und liefern ihn unverändert zurück. Da wir die benutzerdefinierten Daten, die mit den Tags ItemCustomData oder CartCustomData markiert wurden, nicht parsen, müssen Sie uns weder eine XSD-Datei senden, noch Ihre benutzerdefinierten Daten auf andere Weise definieren.

Benutzerdefinierte Datenfelder in der order.xml-Datei verwenden Damit Sie benutzerdefinierte Datenfelder in Ihrer Bestellung verwenden können, müssen Sie einen neuen Bereich zu Ihrer order.xml hinzufügen, entweder ItemCustomData oder CartCustomData wie im folgenden Beispiel: JKL909 AEIOU1234AEIOU Calvin and Hobbes 29.99 EUR 1 2.0 kg Books Charles River Sports Academy Grün 10090

OpenTopic | Benutzerdefinierte Datenfelder verwenden | 23 0525470948 ... Je nachdem, wie Sie diese Daten nutzen möchten, können wir diese entweder als Teil der Callback-API oder als Teil der Instant Order Processing Notification API zurückliefern.

Benutzerdefinierte Datenfelder mit der IOPN-API verwenden Wenn Sie benutzerdefinierte Datenfelder in den Bestellbenachrichtigungen verwenden möchten, dann geben Sie zunächst die Daten in den Bereichen ItemCustomData oder CartCustomData ein. Wenn wir Ihnen die angeforderte Benachrichtigungs-XML-Datei senden, fügen wir die im untenstehenden Beispiel angezeigten Informationen ein: 6e5fdbca-e5c1-4353-9942-87210203378d Amazon Checkout 102-4788713-2074908 2009-09-11T02:19:01.000Z Jana Müller [email protected] Jana Müller Marcel-Breuer-Straße 12 München Bayern 80807 DE Standard 44837685294413 AEIOU1234AEIOU JKL909 Calvin and Hobbes Von Bill Watterson 123457 miq://rose:1.0/cart/cba:1.0/cart:2.0/ AEIOU1234AEIOU/VWXYZ98765VWXYZ/ 2-1328561625299-323F62C3E26F95E9 29.99 EUR 1 2.0 kg Books MERCHANT

24 | OpenTopic | Benutzerdefinierte Datenfelder verwenden Principal 2.5 EUR ... 0525470948 Charles River Sports Academy Grün 10090 Wenn Sie diese Daten erhalten, können Sie diese mithilfe Ihrer eigenen Anwendungslogik modifizieren.

Benutzerdefinierten XML-Namensraum verwenden Sie können Ihren eigenen XML-Namensraum als Teil der benutzerdefinierten Datenfelder verwenden. Beachten Sie das hinzugefügte XMLNS-Attribut im untenstehenden Beispiel (CustomText xmlns="http:// mydomain.com"): JKL909 AEIOU1234AEIOU Calvin and Hobbes 29.99 EUR 1 2.0 kg Bücher Charles River Sports Academy Grün 10090

OpenTopic | Benutzerdefinierte Datenfelder verwenden | 25 0525470948 ... Durch das von Ihnen hinzugefügte benutzerdefinierte XMLNS-Attribut sind auch die Antworten modifziert. Hier ist ein Beispiel einer entsprechenden Bestellbenachrichtigung: 6e5fdbca-e5c1-4353-9942-87210203378d Amazon Checkout 102-4788713-2074908 2009-09-11T02:19:01.000Z Jana Müller [email protected] Jana Müller Marcel-Breuer-Straße 12 München Bayern 80807 DE Standard 44837685294413 AEIOU1234AEIOU JKL909 Calvin and Hobbes Reliquary By Bill Watterson 123457 miq://rose:1.0/cart/cba:1.0/cart:2.0/ AEIOU1234AEIOU/VWXYZ98765VWXYZ/ 2-1328561625299-323F62C3E26F95E9 29.99 EUR 1 8.5 lb Books MERCHANT Principal 2.5 EUR ...

26 | OpenTopic | Benutzerdefinierte Datenfelder verwenden 0525470948 Charles River Sports Academy Malachite 10090

Anhang

A Das IOPN-API-Schema Themen: •

Das IOPN-API-Schema

28 | OpenTopic | Das IOPN-API-Schema

Das IOPN-API-Schema Hier sehen Sie das Schema für die Instant Order Processing Notification API. Alternativ können Sie die iopn.xsdDatei herunterladen. Hinweis: Umsatzsteuerlich registrierte Verkäufer können die Rechnungsadresse des Käufers im BillingAddress-Feld der Benachrichtigung über versandbereite Bestellungen auslesen. In anderen Benachrichtigungen ist das BillingAddress-Feld nicht enthalten.

OpenTopic | Das IOPN-API-Schema | 29

30 | OpenTopic | Das IOPN-API-Schema name="CartCustomData" type="tns:MerchantCustomDataXML" name="ItemCustomData" type="tns:MerchantCustomDataXML" name="ShippingCustomData" type="tns:MerchantCustomDataXML"


OpenTopic | Das IOPN-API-Schema | 31 populated in the current version of IOPN. -->

32 | OpenTopic | Das IOPN-API-Schema

Anhang

B Häufig gestellte Fragen Themen: •

Häufig gestellte Fragen

Der folgende Bereich enthält die am häufigsten gestellten Fragen zur Instant Order Processing Notification API. • • • • • • • •

• • • • • • • •

Was ist die Instant Order Processing Notification API? Was sind Bestellbenachrichtigungen? Welche Vorteile hat die IOPN-API für mich? Welche Voraussetzungen gibt es für die Nutzung der IOPN-API? Wohin sendet die IOPN-API die Nachrichten? Welche Nachrichten kann ich empfangen und wann empfange ich diese? Warum erhalte ich keine Benachrichtigung von der IOPN-API? Warum habe ich noch vor der Bestellbenachrichtigung eine Benachrichtigung über eine versandbereite oder stornierte Bestellung erhalten? Warum habe ich die Benachrichtigung über eine stornierte Bestellung vor der Benachrichtigung über eine versandbereite Bestellung erhalten? Was mache ich, wenn ich zwei Benachrichtigungsanfragen mit derselben UUID erhalte? Was passiert, wenn mein Service oder Endpunkt nicht verfügbar ist? Was versteht man unter der 14-tägigen Exponential-Backoff-Regelung? Was sollte ich machen, wenn ich eine Benachrichtigung erhalte, die ich nicht verarbeiten kann? Wie kann ich die Echtheit von Bestellbenachrichtigungen feststellen? Warum habe ich eine Bestellbenachrichtigung erhalten, in der weniger Artikel stehen als im Einkaufswagen bestellt wurden? Ich habe eine Benachrichtigung zu einer neuen Bestellung erhalten. Sollte ich die Bestellung jetzt versenden?

34 | OpenTopic | Häufig gestellte Fragen

Häufig gestellte Fragen Was ist die Instant Order Processing Notifcation API? Mittels der Instant Order Processing Notification API (kurz IOPN-API) können Sie sofort über neue Bestellungen informiert werden, Ihren Lagerbestand nach Eingang der Benachrichtigung über eine versandbereite Bestellung reservieren (den bestellten Artikel aus der Liste der verfügbaren Produkte entfernen), und Sie können den Artikel wieder zum Lagerbestand hinzufügen, wenn Sie eine Benachrichtigung erhalten, dass die Bestellung storniert wurde.

Was sind Bestellbenachrichtigungen? Bestellbenachrichtigungen sind HTTPS-Anfragen, die einen Händler über neue "Bezahlen über Amazon"Bestellungen oder Statusänderungen von existierenden Bestellungen informiert. Diese Benachrichtigungen können an das interne Bestellverwaltungssystem des Händlers gesendet werden.

Welche Vorteile hat die IOPN-API für mich? Sie können Sie die Instant Order Processing Notification API nutzen, um sofortige Informationen zu den Bestellungen zu erhalten und diese automatisch mittels Ihres Bestellverwaltungssystems zu verarbeiten. Mittels der IOPN-API können Sie sofort über neue Bestellungen informiert werden, Ihren Lagerbestand nach Eingang der Information, dass die Bestellung versandbereit ist, reservieren (den bestellten Artikel aus der Liste der verfügbaren Produkte entfernen), und Sie können den Artikel wieder zum Lagerbestand hinzufügen, wenn Sie eine Benachrichtigung erhalten, dass die Bestellung storniert wurde.

Welche Voraussetzungen gelten für die Nutzung der IOPN-API? Damit Sie die Instant Order Processing Notification API nutzen können, muss Ihr System die folgenden Voraussetzungen erfüllen: 1. Wenn Sie die Standard-Integration nutzen, müssen Sie die order.xsd in der Version 2009-05-15 oder neuer verwenden. (Diese Version hier herunterladen.) 2. Sie müssen die iopn.xsd in der Version 2008-11-30 oder neuer verwenden. (Diese Version hier herunterladen.) 3. Sie müssen einen Webservice betreiben, der HTTPS-POST-Anfragen über Port 443 empfangen und verarbeiten kann. 4. Ihr HTTPS-Protokoll muss ein gültiges SSL-Zertifikat von einem vertrauenswürdigen Anbieter verwenden. Lesen Sie den Hilfe-Artikel SSL-Zertifikate und die Callback-API auf der Website von Amazon Payments, um eine Liste der akzeptierten Anbieter von SSL-Zertifikaten einzusehen. Weitere Informationen zur Aktivierung der Instant Order Processing Notification API finden Sie in diesem Handbuch unter IPON-APIs aktivieren.

Wohin sendet die IOPN-API die Nachrichten? Nachrichten von der IOPN-API werden an die Händler-URL oder die URL des Integrationsdienstleisters gesendet, die Sie in Seller Central oder im Rahmen der Inline-Integration festgelegt haben. Die Händler-URL ist die URL Ihrer Website, an die Sie die Bestellbenachrichtigungen erhalten möchten. Ihr Webservice muss die Benachrichtigungen an diese URL lesen und verarbeiten können. Wenn Sie die Händler-URL leer lassen, werden Sie keine Benachrichtigungen erhalten. Wenn Sie die URL des Integrationsdienstleisters eingetragen haben, werden die Benachrichtigungen auch an diese URL gesendet. Sie müssen mindestens einen dieser Endpunkt-URLs aktivieren, entweder die Händler-URL oder die URL des Integrationsdienstleisters. Sie können die Endpunkt-URLs in Seller Central festlegen.

OpenTopic | Häufig gestellte Fragen | 35

Welche Nachrichten kann ich empfangen und wann empfange ich diese? Sie können drei verschiedene Benachrichtigungen empfangen: 1. Neue Bestellung: Sie erhalten diese Benachrichtigung, wenn auf Ihrer Website eine neue Bestellung aufgegeben wurde. Diese Benachrichtigung bedeutet, dass Amazon Payments angefangen hat, die Bestellung intern zu verarbeiten. 2. Bestellung ist versandbereit: Sie erhalten diese Benachrichtigung, wenn die Bestellung laut der "Bezahlen über Amazon"-Bestellverwaltung versandbereit ist. 3. Bestellung wurde storniert: Sie erhalten diese Benachrichtigung, wenn die Bestellung während des Bestellprozesses entweder vom Käufer oder vom Händler storniert wurde. Sie erhalten diese Benachrichtigung auch dann, wenn Amazon Payments die Bestellung wegen Käuferbetrugs, fehlender Versandbestätigung, fehlender Autorisierung oder aus anderen Gründen storniert.

Warum erhalte ich keine Benachrichtigung von der IOPN-API? Sie müssen in Seller Central eine Endpunkt-URL eintragen, um die Instant Order Processing Notification API zu aktivieren. Für weitere Informationen lesen Sie bitte den Abschnitt IOPN-APIs aktivieren. Achten Sie bei der Eingabe der Endpunkt-URLs darauf, dass diese URLs für den Produktivmodus das https://Protokoll nutzen (Port 443). Für Sandbox-Konten können Sie entweder http:// oder https:// nutzen.

Warum habe ich noch vor der Bestellbenachrichtigung eine Benachrichtigung über eine versandbereite oder stornierte Bestellung erhalten? Falls der Endpunkt nicht erreichbar ist, wenn wir die erste Bestellbenachrichtigung versenden, aber kurz darauf wieder funktioniert, wenn wir die Benachrichtigung über eine versandbereite oder stornierte Bestellung versenden, dann kommen die Benachrichtigungen in der falschen Reihenfolge an. Wenn dies passiert, können Sie zwischen den folgenden Möglichkeiten wählen: 1. Bestätigen Sie die Benachrichtigung über eine versandbereite oder Bestellung nicht, wenn Sie die Bestellbenachrichtigung noch nicht erhalten haben. Senden Sie uns stattdessen eine "INTERNAL_ERROR (500)"-Nachricht, weil die Reihenfolge der Benachrichtigungen nicht stimmt. Wenn Sie den Eingang der Benachrichtigungen nicht bestätigen, wird Amazon Payments weiterhin versuchen, eine Benachrichtigungsbestätigung anzufordern. Die Benachrichtigungen werden synchronisiert, nachdem Sie die Bestellbenachrichtigung erhalten haben. 2. Da jede Benachrichtigung den vollständigen Einkaufswagen und die Bestelldetails enthält, können Sie Ihr Bestellverwaltungssystem auch mit den Informationen aus der Benachrichtigung über eine versandbereite oder stornierte Bestellung aktualisieren und die Bestellbenachrichtigung ignorieren, wenn Sie diese später erhalten.

Warum habe ich die Benachrichtigung über eine stornierte Bestellung vor der Benachrichtigung über eine versandbereite Bestellung erhalten? Falls der Endpunkt nicht erreichbar ist, wenn wir eine Benachrichtigung über eine versandbereite Bestellung versenden, aber kurz darauf wieder funktioniert, wenn wir eine Benachrichtigung über eine stornierte Bestellung versenden, dann kommen die Benachrichtigungen in der falschen Reihenfolge an. Falls dies passiert, dann ignorieren Sie bitte die "Bestellung versandbereit"-Benachrichtigung, da eine Bestellstornierung nicht mehr geändert werden kann.

Was mache ich, wenn ich zwei Benachrichtigungsanfragen mit derselben UUID erhalte? Die UUID ist für jede Anfrage eindeutig. Wenn Sie eine zweite Benachrichtigung mit derselben UUID erhalten, dann sollten Sie diese Benachrichtigung ignorieren, weil es sich hierbei um einen externen Replay-Angriff handeln könnte. Hinweis: Wenn erneut versucht wird, eine Benachrichtigung zu senden, ist in dieser die

36 | OpenTopic | Häufig gestellte Fragen NotificationReferenceID immer gleich, die UUID wird jedoch für jeden Versuch neu generiert.

Was passiert, wenn mein Service oder Endpunkt nicht verfügbar ist? Wenn die Benachrichtigung scheitert, weil eine Endpunkt-URL nicht erreichbar ist oder der Händler die Anfrage ablehnt, versucht Bezahlen über Amazon die Nachricht im Rahmen der 14-tägigen Exponential-Backoff-Regelung zuzustellen.

Was versteht man unter der 14-tägigen Exponential-Backoff-Regelung? Wenn eine Bestellbenachrichtigung nicht gesendet werden kann, weil die Endpunkt-URL des Händlers nicht erreichbar ist oder der Händler die Anfrage abgelehnt hat, dann versucht Bezahlen über Amazon über einen Zeitraum von 14 Tagen die Nachrichten zuzustellen. Der Zustellungsrhythmus unterliegt dabei einer exponentiellen Steigerung, d.h. die Wartezeit wird nach jedem neuen Versuch verdoppelt. Beispiel: Den ersten Neuversuch starten wir nach einer Minute. Den zweiten Neuversuch starten wir nach zwei Minuten, den dritten nach vier Minuten, usw. Wir versuchen 14 Tage lang, diese Benachrichtigungen zu senden. Wenn die Anfrage auch nach Ablauf der 14 Tage nicht zugestellt wird, stoppen wir die Zustellungsversuche.

Was sollte ich machen, wenn ich eine Benachrichtigung erhalte, die ich nicht verarbeiten kann? Falls Sie die erhaltenen Benachrichtigungen nicht verarbeiten können, müssen sie mit dem korrekten Fehlercode antworten: Name

Verwendungszweck

W3C-Definition

INTERNAL_ERROR (500)

Antworten Sie mit diesem Code, wenn der interne Servcie die Anfrage nicht verarbeiten kann.

Auf dem Server ist ein unerwarteter Fehler aufgetreten, der verhindert, dass die Anfrage verarbeitet werden kann.

SERVICE_UNAVAILABLE (503)

Antworten Sie mit diesem Code, wenn Ihr interner Service die Anfrage nicht verarbeiten kann, oder wenn Sie möchten, dass Amazon Payments erneut versucht, die Benachrichtigung zu senden. Neuversuche werden im Rahmen der Backoff-Regelung verschickt.

Der Server kann die Anfrage im Moment aufgrund einer temporären Überlastung oder aus Wartungsgründen nicht bearbeiten.

PERMISSION_DENIED (403)

Antworten Sie mit diesem Code, wenn Sie die Signatur nicht verifizieren können.

Der Server hat die Anfrage verstanden, weigert sich aber, diese zu verarbeiten

Die Definition stanmmen von Hypertext Transfer Protocol – HTTP/1.1 definitions (RFC2616 Fielding, et al.)

Wie kann ich die Echtheit von Bestellbenachrichtigungen feststellen? Nachdem Sie die Daten erhalten und geparst haben, sollten Sie die Signatur und den Zeitstempel prüfen, um sich zu versichern, dass die Anfrage gültig ist. Lesen Sie hierzu bitte den Abschnitt Gültigkeit der BenachrichtigungsAnfrage verifizieren.

OpenTopic | Häufig gestellte Fragen | 37

Warum habe ich eine Bestellbenachrichtigung erhalten, in der weniger Artikel stehen als im Einkaufswagen bestellt wurden? Wenn im Einkaufswagen Artikel mit unterschiedlichen Versandbedingungen sind, wird der Einkaufswagen in mehrere Bestellungen aufgeteilt. Wenn dieser Fall eintritt, erhalten Sie eine separate Benachrichtigung für jede Bestellung. Jede Benachrichtigung enthält die nach Versandmethode zusammengefassten Artikel derselben Bestellung.

Ich habe eine Benachrichtigung zu einer neuen Bestellung erhalten. Sollte ich die Bestellung jetzt versenden? Nein, versenden Sie die Bestellung noch nicht, wenn Sie lediglich eine Benachrichtigung über eine neue Bestellung erhalten. Diese Benachrichtigung informiert Sie darüber, dass eine Bestellung aufgegeben wurde, aber die Zahlung für die Bestellung wurde wahrscheinlich noch nicht verarbeitet. Versenden Sie die Bestellung erst, wenn Sie die Benachrichtigung erhalten, dass die Bestellung versandbereit ist.

38 | OpenTopic | Häufig gestellte Fragen