Gutscheincodes von Amazon auf Nachfrage (AGCOD) Weberstellung Technische Spezifikation für die Integration August 2018: Diese Spezifikation ist veraltet. Bitte verwenden Sie die folgenden Links für die neueste Version (basierend auf der Sprache):  Englisch - https://s3-us-west-2.amazonaws.com/incentives-apisetup/index.html#integrate  Französisch - https://s3-us-west-2.amazonaws.com/incentivesapi-setup/index-FR.html#integrate  Japanisch - https://s3-us-west-2.amazonaws.com/incentivesapi-setup/index-JP.html#integrate

Mit Gutscheincodes von Amazon auf Nachfrage (Amazon Gift Codes On Demand, AGCOD) haben Partner und unabhängige Entwickler die Möglichkeit, Amazon-Gutscheincodes in Echtzeit und auf Nachfrage zu erstellen und zu vertreiben. Beispiele für geeignete Anwendungsfälle sind das Einfügen von Gutscheincodes in

elektronische Geschenkkarten, Gruppengeschenke, die Echtzeit-Einlösung von Gutscheincodes im Rahmen von Treueprogrammen (z. B. Bonus- oder Punkteprogrammen) usw.

Inhalte I.

Was sind Gutscheincodes von Amazon auf Nachfrage (AGCOD)? ....................................................... 4 1.

Zusammenfassung ............................................................................................................................ 4

2.

Zielgruppe ......................................................................................................................................... 4

3.

Überblick über AGCOD ...................................................................................................................... 4

4.

Unterstützte Vorgänge und Anfragen-/Antwortbeispiele ................................................................ 4 (a)

Definitionen .............................................................................................................................. 5

5.

Fehlerbehandlung ............................................................................................................................. 9

6.

Digitale Signaturen: Signiervorgang ................................................................................................ 10

7.

Grundlegender Ablauf..................................................................................................................... 11

8.

Beispiele für HTTP POST-Anfragen/-Antworten ............................................................................. 11

9.

Sicherheit ........................................................................................................................................ 11 (a)

Sichere Datenübertragung ...................................................................................................... 12

(b)

Zugriffskontrolle ...................................................................................................................... 12

10.

Referenzdokumente ................................................................................................................... 12

II.

Überblick über den Integrationsvorgang ............................................................................................ 12

III.

Registrierung und einmalige Einrichtung ........................................................................................ 13

1.

Einrichtung von AWS-Konten .......................................................................................................... 14

2.

Zuweisung der Partner-ID ............................................................................................................... 14

3.

Maximaler Transaktionsbetrag ....................................................................................................... 14

4.

Preisnachlässe ................................................................................................................................. 14

IV.

Entwicklung und Integration ........................................................................................................... 15 Seite 2

1.

Entwicklung und Testen in der Sandbox-Umgebung ...................................................................... 15

2.

Aktivierung der Produktion ............................................................................................................. 16

V.

Technische Unterstützung durch Amazon (aktiver Vertrag erforderlich) .......................................... 17

VI.

Anfrage-/Antwortbeispiele ............................................................................................................. 17

VII.

Änderungsverlauf dieses Dokuments ............................................................................................. 17

Seite 3

I.

Was sind Gutscheincodes von Amazon auf Nachfrage (AGCOD)?

1. Zusammenfassung Gutscheincodes von Amazon können von externen Partnern über eine Webservice-Schnittstelle gekauft und dann an ihre Kunden weitervertrieben werden. Bei AGCOD handelt es sich um ein Mehrkomponentensystem, über welches Gutscheincodes in Echtzeit erworben werden können. Im vorliegenden Dokument wird die Integration der AGCOD-API beschrieben.

2. Zielgruppe Das vorliegende Dokument wurde für Entwickler und externe Partner verfasst, die mit Amazon eine vertragliche Vereinbarung zum Kauf von Amazon-Gutscheincodes abschließen. Dieses Dokument setzt ausreichende Kenntnisse über Webservice-Technologien (XML, RESTful-Protokolle usw.), grundlegende Sicherheitskonzepte (Verschlüsselung, digitale Signaturen usw.) und serviceorientierte Architekturen (Service Oriented Architectures, SOA) voraus.

3. Überblick über AGCOD Gutscheincodes/Geschenkkarten von Amazon können auf der Website von Amazon als Währung beim Kauf von Produkten genutzt werden. Mit dem AGCOD-Gateway wird eine Programmierschnittstelle bereitgestellt, über die Partner in Echtzeit Gutscheincodes erstellen können. Partner können synchrone Anfragen an den AGCOD-Endpunkt stellen und dabei den Wert des Gutscheincodes angeben, den sie erstellen möchten. Die AGCOD-API antwortet mit einem Status, der auf einen erfolgreichen oder fehlerhaften Vorgang hinweist. Im Fall einer erfolgreichen Anfrage wird ein Einlösungscode erstellt, den die Partner dann auf eine von Amazon zugelassene Weise an ihre Kunden weitergeben können. Die Finanzierung der Geschenkkarten erfolgt über das Zahlungskonto des Partners per Überweisung von Guthaben auf das Bankkonto von Amazon. Weitere Informationen finden Sie im Anhang 1 "Detaillierte Architektur des AGCOD-Gateway-Service" im Dokument Häufig gestellte Fragen und Anhänge.

4. Unterstützte Vorgänge und Anfragen-/Antwortbeispiele Das AGCOD-Gateway verarbeitet Echtzeitanfragen von Partnern zur Erstellung/Stornierung von Gutscheincodes. Dieser öffentlich zugängliche Webservice unterstützt RESTful-Anfragen über HTTPS.

Seite 4

(a) Definitionen 1. partnerId: Eine eindeutige Kennung, die vom Amazon-Team für Gutscheincodes vergeben wird (Groß-/Kleinschreibung muss beachtet werden: 1. Buchstabe ist ein Großbuchstabe, die nächsten vier sind Kleinbuchstaben). Dieser Wert ist Teil der Payload jeder AGCOD-Gateway-Anfrage. 2. creationRequestId: Eine eindeutige Kennung für jeden CreateGiftCard-Aufruf, der zur Erstellung eines Gutscheincodes führt. Der Partner muss für jede Erstellungsanfrage einen neuen Wert generieren (außer bei Wiederholungen). Damit diese Transaktionskennung global eindeutig ist, müssen folgende Voraussetzungen erfüllt sein:  

Der Partner muss einen alphanumerischen Wert generieren, der in seinen Systemen eindeutig ist. Diese Kennung darf aus maximal 19 alphanumerischen Zeichen bestehen. Die creationRequestId muss mit der partnerID beginnen.

Beispiel: Wenn Ihre partnerID "Amzn1" lautet, muss Ihre creationRequestId mit "Amzn1" beginnen und kann beliebige weitere Zeichen enthalten (z. B. "Amzn154321"). Da die API idempotent ist, gibt das AGCOD-Gateway bei Übermittlung einer Anfrage mit einer bereits verwendeten creationRequestId den ursprünglichen Status an, der bei der ersten Verwendung der creationRequestId erstellt wurde. 3. CreateGiftCardResponse/CancelGiftCardResponse: Das AGCOD-Gateway generiert eine Statusantwort bei jeder erfolgreichen Anfrage zum Erstellen/Stornieren eines Gutscheincodes. 4. Transaktion: Als Transaktion wird jede Anfrage mit Antwort bezeichnet, die zur Erstellung/Stornierung eines Gutscheincodes in den Systemen von Amazon führt.

(i) CreateGiftCard Der Partner übermittelt eine creationRequestId zur eindeutigen Kennzeichnung der Erstellungsanfrage sowie weitere Details wie Betrag, Währung usw. (neben den Metadaten für diese Anfrage, Authentifizierungsinformationen usw.). Weitere Informationen finden Sie im Anhang 2 "Meldungsschema des AGCOD-Gateway-Service" im Dokument Häufig gestellte Fragen und Anhänge. Der Vorgang umfasst die folgenden Schritte: 1. Der Kunde sendet eine CreateGiftCardRequest-Meldung an das AGCODGateway. 2. Amazon bestätigt, dass im Vorauszahlungskonto ausreichend Guthaben für die Anfrage vorhanden ist. 3. Amazon zieht den Bestellbetrag ab und antwortet mit einer synchronen CreateGiftCardResponse-Meldung, die den Live-Einlösungscode für den Seite 5

Gutscheincode, das Ablaufdatum (nicht in den USA) sowie die gcId enthält. Der Partner muss die creationRequestId, die gcId, den Betrag und den Währungscode für künftige Kommunikationszwecke und zur Fehlerbehebung speichern. Beispielmeldung: POST /CreateGiftCard HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-eu-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;xamz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 AwssbTSpecTest001AwssbEUR 1.00 RESPONSE:

W3GU-YD4NGH-88C8 EUR 1.0 Fulfilled A3B6AC387ESRIX AwssbTSpecTest001 Mon Jun 09 21:59:59 UTC 2025 SUCCESS

Der Vorgang ist idempotent. Das heißt, wenn das AGCOD-Gateway mehr als eine solcher Anfragen mit derselben creationRequestId empfängt, resultiert die erste Anfrage in der Erstellung eines neuen Gutscheincodes, während alle folgenden Antworten den ursprünglich erstellten Gutscheincode zurückgeben. Sie werden nicht als separate Transaktion behandelt. Beachten Sie, dass durch einen CreateGiftCard-Aufruf nur ein Gutscheincode erstellt wird. (Die gleichzeitige Erstellung mehrerer Gutscheincodes wird derzeit nicht unterstützt.) Optional - externes Referenzfeld – Eigenschaften

Seite 6

Partner können im Zuge der Gutscheincodeanfrage das externe Referenzfeld verwenden, um Ihre eigene Referenzkennung als String weiterzugeben (bis zu 100 Zeichen, Unicode wird unterstützt). Das externe Referenzfeld kann verwendet werden, um die Zuordnung und Verfolgung folgender Eigenschaften zu erleichtern: Versicherungsansprüche, Kioske, Kundenfälle, Bestell IDs, Kundenkonten von Händlern oder zum Speichern von Informationen, etc. Nur undurchsichtige Referenzen ohne natürlichen Sprachinhalt sind zulässig in diesem Bereich. Die Kennung, welche zugeteilt wird, bleibt in dem Payment Tracker-Portal identisch und kann so jederzeit zugeordnet werden. Die folgende Beispielmeldung unterstreicht die Änderung, welche notwendig ist, um dem externen Refernzfeld gerecht zu werden. Beispielmeldung: POST /CreateGiftCard HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-eu-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;xamz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 AwssbTSpecTest001AwssbEUR 1.00889jj14797

(ii) CancelGiftCard Der Partner kann einen Gutscheincode stornieren, solange er noch nicht von einem Kunden von Amazon eingelöst wurde. Für die Stornierung eines Gutscheincodes werden die ursprüngliche creationRequestId, die für die Erstellung des Gutscheincodes verwendet wurde, und die GCID aus der erfolgreichen gcCreateResponse-Meldung benötigt. Hinweis: dieser Vorgang nur innerhalb von 15 Minuten nach dem Erstellen des Anrufs ausgeführt werden kann. Nach 15 Minuten kann der Code nicht mehr storniert werden und die Gebühren werden von Ihrem Prepaid-Guthaben abgebucht. Der Partner sendet eine CancelGiftCard-Anfrage und das AGCOD-Gateway antwortet mit einer synchronen CancelGiftCardResponse. Die beiden Vorgänge CreateGiftCard und CancelGiftCard sind idempotent. Wenn das AGCOD-Gateway mehr als eine solcher Anfragen mit derselben creationRequestId empfängt, resultiert die erste Anfrage Seite 7

in der Erstellung/Stornierung der Gutscheincode-Anfrage, während alle folgenden Antworten zu einem "NO-OP" führen. (Sie werden nicht als separate Transaktion behandelt.) Beispielmeldung: POST /CancelGiftCard HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-eu-gamma.amazon.com x-amz-date:20130910T222449Z x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;xamz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87 AwssbTSpecTest001AwssbA3B6AC387ESRIX RESPONSE: AwssbTSpecTest001 SUCCESS A2GCN9BRX5QS76

(iii) GetAvailbleFunds Diese Funktion ermöglicht das Einsehen Ihres aktuellen Amazon Incentives Kontostands. Die Funktion stellt eine Alternative zur Kontoeinsicht über den Portal-Login dar. Ein möglicher Anwendungsfall für diese Funktion ist die Entwicklung eines maßgeschneiderten Warnsystems oder die regelmäßige Prüfung des Kontostands. Achtung: Dieser Anfrage-Typ (Request Type) ist auf 1 Transaktion pro Sekunde (TPS) beschränkt. Anfrage mit einer höheren Rate werden von unserem System ignoriert. Da es in der Sandbox keinen tatsächlichen Kontostand gibt, gibt der 'GetAvailbleFunds' Vorgang immer eine Nullbilanz zurück. Beispielmeldung: POST /GetAvailableFunds HTTP/1.1 accept:charset=UTF-8 content-type:charset=UTF-8 host:agcod-v2-eu-gamma.amazon.com x-amz-date:20170915T200959Z x-amz-target:com.amazonaws.agcod.AGCODService.GetAvailableFunds Authorization:AWS4-HMAC-SHA256 Credential=AKIAI9ZN2Z6XI463M2SA/20170915/euwest-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;xamz-date;x-amztarget,Signature=78e0971a383cdfb0cc287c277984498e7e147ff759c4a359eb632074d

Seite 8

39b3e55 Aptuk RESPONSE: GBP 10.0 20170915T200959Z SUCCESS

(iv) GetGiftCardActivityPage Der Partner kann sich eine Liste mit Transaktionen (bis zu 1.000 pro Aufruf) für einen bestimmten Zeitraum anzeigen lassen. Beim API-Aufruf wird dieser Zeitraum eingeschränkt, sodass nur Transaktionen angezeigt werden, die mindestens 30 Minuten (und bis zu 90 Tage) alt sind. Wenn beispielsweise aktuell der 01.04.2015 13:00 Uhr ist, kann der Partner Transaktionen vom 01.01.2015 12:30 Uhr bis zum 01.04.2015 12:30 Uhr abrufen. Die GetGiftCardActivityPage-API sollte den Schwellenwert von einem Aufruf pro Minute nicht überschreiten (d. h., die API sollte maximal einmal pro Minute aufgerufen werden; einmalige aufeinanderfolgende Wiederholungsanfragen, z. B. aufgrund einer Zeitüberschreitung, sind zulässig). Dieser Vorgang kann für einzelne Partner gesperrt werden, wenn der oben genannte Schwellenwert auf eine Weise überschritten wird, die die Verfügbarkeit des Systems für andere Vorgangsaufrufe beeinträchtigt (d. h., das System wird mit unzähligen Anfragen überflutet, die einen so genannten Denial of Service auslösen). Die Kennzeichnung "showNoOps" gibt Aufschluss darüber, ob die zurückgegebenen Ergebnisse idempotente Vorgänge enthalten würden. Weitere Informationen und Anfragenbeispiele einschließlich digitaler Signaturen finden Sie im Anhang 4 "Beispielcode und Beispielanfragen/-antworten" im Dokument Häufig gestellte Fragen und Anhänge. Die oben aufgeführten Beispiele wurden mit den im Anhang bereitgestellten Beispielcodes erstellt.

5. Fehlerbehandlung Jeder vom AGCOD-Gateway gesendeten Antwort ist ein Status-Element zugewiesen, das den Ausführungsstatus des jeweiligen Vorgangs beschreibt. Es gibt drei statusCode-Werte: SUCCESS/FAILURE/RESEND.

(i) statusCode: SUCCESS Ein statusCode mit dem Wert SUCCESS wird zurückgegeben, wenn der Vorgang erfolgreich war. Seite 9

(ii) statusCode: FAILURE Ein statusCode mit dem Wert FAILURE wird zurückgegeben, wenn die Anfrage vom AGCOD-Gateway nicht verarbeitet werden kann. Diese Statusantwort kann bei ungültigen Anfragedaten oder einem Fehler in der Geschäftslogik, der vom Partner geprüft werden muss, zurückgegeben werden. Das Feld errorCode wird in solchen Fällen automatisch ausgefüllt und zeigt zusätzliche Details zum Fehler an.

(iii) statusCode: RESEND Ein statusCode mit dem Wert RESEND wird bei einem temporären/behebbaren Systemfehler zurückgegeben, der vom Partner durch das Wiederholen der Anfrage behoben werden kann. Das Feld errorCode wird in solchen Fällen automatisch ausgefüllt und zeigt zusätzliche Details zum Fehler an. Der RESEND-Wert sollte nicht als Fehler interpretiert werden. Er bedeutet lediglich, dass zum Zeitpunkt der Übermittlung kein Vorgangsstatus bestimmt werden konnte. In solchen Fällen wird erwartet, dass der Partner die Anfrage mit denselben Eingabedaten wie bei der ursprünglichen Anfrage wiederholt, bis ein endgültiger Antwortstatus (SUCCESS oder FAILURE) angezeigt wird. Wenn Nachrichten zwischen Servern aufgrund von Netzwerkproblemen unterbrochen werden, kann dies zu einem F400-Fehler führen. Ein F400-Fehler ist ein „unbekannter Status“ und kann Abbuchungen von Ihrem Konto verursachen. Daher ist es wichtig, dass Ihr Computercode so lange läuft bis Sie eine Success- oder Failureantwort erhalten. Der Partner sollte die Wiederholungsversuche drosseln, um eine Überflutung des AGCOD-Gateway zu vermeiden. Wir empfehlen eine einfache Methode wie ein exponentielles Backoff-Schema.

(iv) Fehlercodes Wir verwenden F2XX-Codes zur Angabe von Fehlern, die vom Partner verursacht wurden, und F1XXCodes, wenn die Fehlerursache auf der Seite von Amazon liegt. Wir haben Anfragen-IDs für Pseudofehler bereitgestellt, damit Sie bestimmte Fehlerantworten auf Erstellungs-/Stornierungsanfragen simulieren können. Bei der Simulation einer Fehlerantwort muss die Anfragen-ID des Pseudofehlers ähnlich wie eine normale Anfragen-ID in das Feld creationRequestId eingegeben werden. Die in die restlichen Felder eingegebenen Werte werden einfach in der Antwort zurückgegeben. Für die Simulation einer erfolgreichen Antwort kann der Wert F1000 als Anfragen-ID für den Pseudofehler eingegeben werden. Weitere Informationen finden Sie im Abschnitt "Simulieren von Testergebnissen" und im Anhang 8 "Fehlerbehandlung" im Dokument Häufig gestellte Fragen und Anhänge.

6. Digitale Signaturen: Signiervorgang Jede Anfrage an das AGCOD-Gateway muss unter Verwendung der AWS-Zugriffskennungen und Anmeldedaten digital signiert werden. Seite 10

Das AGCOD-Gateway unterstützt den Version-4-Signaturalgorithmus. Generieren von digitalen Signaturen für HTTP-Anfragen. Anweisungen zum Signieren von AWS-API-Anfragen finden Sie im öffentlich verfügbaren AWSEntwicklerleitfaden in den Artikeln zu den folgenden Themen: Signieren von AWS-Anfragen mithilfe der Version-4-Signatur, Beispiele für signierte Version-4-Signaturanfragen , Beispiele für die Ableitung eines Version-4-Signaturschlüssels, Testsuite, Fehlerbehebung bei Version-4-Signaturproblemen in AWS.

7. Grundlegender Ablauf Weitere Informationen finden Sie im Anhang 3 "Grundlegender Ablauf von Anfragen zur Erstellung/Stornierung von Geschenkkarten" im Dokument Häufig gestellte Fragen und Anhänge.

8. Beispiele für HTTP POST-Anfragen/-Antworten Weitere Informationen finden Sie im Anhang 4 "Beispielcode und Beispielanfragen/-antworten" im Dokument Häufig gestellte Fragen und Anhänge.

9. Sicherheit Einlösungscodes für Gutscheincodes haben einen Geldwert und müssen daher sehr sicher behandelt werden. Wir empfehlen den Einsatz von Überwachungsmechanismen, um einen sicheren Umgang mit sensiblen Daten (Einlösungscodes für Gutscheincodes, AWS-Anmeldedaten usw.) sicherzustellen. Hierzu zählt die Einrichtung ordnungsgemäßer Audit-Kontrollen der Dateisysteme/Datenbanken, in denen sensible Daten gespeichert sind. Partner sollten außerdem regelmäßig das Kennwort ihres AWS-Kontos ändern. Zudem haben Partner im AWS-Portal die Möglichkeit, jederzeit einen neuen AWS Access Key zu generieren. AGCOD unterstützt jedoch keine automatische Schlüsselrotation. Wir empfehlen AGCOD-Partnern, diese Funktion NICHT zum erneuten Generieren des AWS Access Key zu verwenden. Wenn Sie den AWS Access Key ändern möchten, kündigen Sie dies bitte mindestens eine Woche im Voraus an und sprechen Sie dies mit Ihrem Kontoadministrator ab, um Unterbrechungen so gering wie möglich zu halten.   

Einlösungscodes müssen bei der Übermittlung zwischen Amazon und dem Partner vertraulich behandelt werden. Einlösungscodes müssen innerhalb des Systems des Partners vertraulich behandelt werden. Am Standort des Partners, an dem Einlösungscodes gehandhabt werden (bei der Übermittlung oder ruhend), müssen sichere Methoden zur Handhabung von Daten implementiert sein.

Hinweis: Der Partner ist für die Einlösungscodes verantwortlich, sobald das AGCOD-Gateway erfolgreich auf die CreateGiftCard-Anfrage des Partners antwortet.

Seite 11

(a) Sichere Datenübertragung Das AGCOD-Gateway ist NUR über einen sicheren Port (HTTPS) zugänglich und jeglicher Datenverkehr über diesen Kanal muss mit SSL verschlüsselt sein. Dadurch kann die Vertraulichkeit der Gutscheincodedaten während der Übermittlung sichergestellt werden. Der Partner ist zur Implementierung eigener Sicherheitsmechanismen in seinen Systemen verpflichtet. Wichtig: Nach dem 30. Juni, 2018 werden all API Anfragen nicht mehr funktionieren, wenn sie nicht mit TLA 1.2 kompatibel sind.

(b) Zugriffskontrolle Die Vorgänge des AGCOD-Gateway unterliegen einer Zugriffskontrolle. Damit ein Partner erfolgreich Anfragen an das AGCOD-Gateway senden kann, muss er eine vertragliche Vereinbarung mit dem für Geschenkkarten zuständigen Team bei Amazon abschließen und sich für ein AWS-Konto registrieren. (Weitere Informationen zur Einrichtung von AWS-Konten finden Sie in Abschnitt III.)

10.

Referenzdokumente

Ausführlichere Informationen und Anweisungen zum JSON-Datenformat sowie zum Senden von HTTP POST-Anfragen an Amazon DynamoDB (das als AGCOD-Gateway verwendet wird) finden Sie im DynamoDB-Entwicklerleitfaden im Abschnitt zur Amazon DynamoDB-API. (Das AGCOD-Gateway verwendet teilweise dasselbe Backend wie DynamoDB.)

II.

Überblick über den Integrationsvorgang

Führen Sie die folgenden grundlegenden Schritte aus, um das AGCOD-Gateway zu integrieren. (Eine ausführlichere Vorgehensweise finden Sie in Abschnitt III): Schritt 1 – Kontoregistrierung und einmalige Einrichtung: Erstellen Sie ein Sandbox- und ein Produktionskonto in AWS und teilen Sie Amazon einige grundlegende Informationen (E-MailAdressen) für diese Konten mit. Schritt 2 – Bereitstellung des Sandbox-Zugriffs: Teilen Sie Ihrem Kontoadministrator die E-MailAdressen mit, die mit Ihren AWS-Konten verknüpft sind, um Zugriff auf unsere Sandbox-Umgebung zu erhalten (Sandbox-Zugriff muss von Amazon gewährt werden).

Seite 12

Sie erhalten von Amazon eine 5-stellige Partner-ID. Senden Sie die angeforderten Kontoinformationen im nachfolgend dargestellten Format an Amazon: Beispiele E-Mail-Adresse des AWS-Kontos Partner-ID

Test (Sandbox) [email protected]

Produktion [email protected]

Awssb

Awssb

Schritt 3 – Entwicklungsbeginn und Testen der Anwendung in der Sandbox-Umgebung unter Verwendung Ihrer Partner-ID und der AWS-Kontos. Schritt 4 – Zertifizierung: Sobald der Code vollständig ist, informieren Sie Ihren Kontoadministrator. Der Zertifizierungsvorgang bei Amazon beginnt und es wird geprüft, ob das integrierte System erwartungsgemäß in der Sandbox-Umgebung ausgeführt wird. Schritt 5 – Aktivierung der Produktion: Nach der erfolgreichen Zertifizierung aktivieren Sie gemeinsam mit Amazon Ihr AGCOD-Konto in der Produktionsumgebung. Hinweis: Die AGCOD-Zertifizierung beinhaltet keine Zustimmung zur Benutzererfahrung oder zur Nutzung der Marke Amazon (d. h. der Logos von und Kennzeichnungen durch Amazon) in Ihrer Anwendung. Eine solche Zustimmung wird in einem separaten Vorgang gewährt. Weitere Details finden Sie im Ressourcenzentrum von Amazon unter dem Thema der Markennutzung bei Geschenkkarten durch Großkunden: Land USA Kanada Vereinigtes Königreich Frankreich Deutschland Spanien Italien Japan China

III.

Link US CA UK FR DE ES IT JP CN

Registrierung und einmalige Einrichtung

Damit Sie mit dem AGCOD-System arbeiten können, muss die folgende Einrichtung einmalig durchgeführt werden.

Seite 13

1. Einrichtung von AWS-Konten In den AGCOD-Komponenten unterliegen alle eingehenden Anfragen von Partnern einer Zugriffskontrolle. Führen Sie die nachfolgenden Schritte aus, um Zugriff zu erhalten und Anfragen senden zu können: i.

Öffnen Sie die Seite http://aws.amazon.com und klicken Sie auf die Schaltfläche "Registrieren". Hinweis: Verwenden Sie eine gültige E-Mail-Adresse mit der Domäne Ihres Unternehmens, z. B. @ihrunternehmen.de, auf die Ihre Entwickler/Betreiber zugreifen können. (Öffentliche E-MailAdressen wie @hotmail.de, @yahoo.de, @msn.de, @gmail.de usw. sind nicht zulässig.) Klicken Sie auf den Link "Konto anlegen", wenn Sie während der Registrierung dazu aufgefordert werden. ** Kreditkartendaten werden nur zur Identitätsprüfung benötigt. Es werden keine Beträge berechnet, wenn das AWS-Konto nur für den AGCOD-Service verwendet wird.

ii.

Registrieren Sie sich mit zwei separaten AWS-Konten, einem für Sandbox und einem für Produktion. Es empfiehlt sich, E-Mail-Adressen wie z. B. "[email protected]" und "[email protected]" einzurichten.

iii.

Melden Sie sich nach der Erstellung der AWS-Konten mit der ersten E-Mail-Adresse und dem zugehörigen Kennwort beim AWS-Portal unter http://aws.amazon.com an, klicken Sie oben rechts im Bildschirm auf den Link "Anmeldeinformationen" (siehe Screenshot) und prüfen Sie, ob die Access Key ID angezeigt wird. Falls nicht, klicken Sie auf den Link zum Erstellen eines neuen Access Key, damit ein neuer Access Key generiert wird. (AGCOD unterstützt an dieser Stelle nicht die Option der Identitäts- und Zugriffsverwaltung. Verwenden Sie diese Option NICHT zur Erstellung des AWS Access Key.) Hinweis: Stellen Sie sicher, dass Sie sich vom ersten Konto abmelden, den Browser schließen und sich dann mit der zweiten E-Mail-Adresse und dem zugehörigen Kennwort unter http://aws.amazon.com anmelden.

2. Zuweisung der Partner-ID Von Ihrem Kontoadministrator erhalten Sie eine eindeutige 5-stellige Partner-ID (Groß-/Kleinschreibung beachten). Diese Kennung muss in allen Anfragen an den AGCOD-Service verwendet werden. Wenn Sie keine Partner-ID erhalten haben, wenden Sie sich bitte an Ihren Kontoadministrator.

3. Maximaler Transaktionsbetrag

4. Preisnachlässe Ihren Preisnachlass (sofern vereinbart) finden Sie in Ihrem Vertrag mit Amazon. Wenn Sie an den Vertragsverhandlungen nicht beteiligt waren, erhalten Sie Informationen zum Preisnachlass vom Seite 14

zuständigen Team oder Ihrem Kontoadministrator. In der Entwicklungs- und Testphase benötigen Sie diese Informationen, um zu prüfen, ob beim Erstellen/Stornieren von Gutscheincodes die richtigen Beträge berechnet und gutgeschrieben werden.

IV.

Entwicklung und Integration

1. Entwicklung und Testen in der Sandbox-Umgebung (i) Zugriff auf die Sandbox Verwenden Sie die Sandbox-Umgebung für die Entwicklung und für Integrationstests. Eine Liste mit den Sandbox- und Produktionsendpunkten finden Sie im Anhang 7 im Dokument Häufig gestellte Fragen und Anhänge. Hinweis: Der Sandbox-Zugriff wird gewährt, sobald Sie Ihrem Kontoadministrator mitgeteilt haben, dass Ihre Sandbox- und Produktionskonten für AWS erstellt wurden.

(ii) Entwicklung und Testen Nachdem der Zugriff auf die Sandbox-Umgebung gewährt wurde, kann der Partner mit der Entwicklung und dem Testen von Code beginnen. Wir stellen voll funktionsfähige Beispielcodes für C#, Java, Python, JavaScript, Ruby und PHP zur Verfügung. Weitere Informationen finden Sie im Anhang 4 im Dokument Häufig gestellte Fragen und Anhänge. Sie können die AGCOD-API auf der nachfolgenden, voll funktionsfähigen Onlineseite unter Verwendung Ihrer AWS-Anmeldedaten und Ihrer zugewiesenen Partner-ID ganz ohne Entwicklungsarbeit/Codierung testen. https://s3.amazonaws.com/AGCOD/htmlSDKv2/htmlSDKv2_NAEUFE/index.html

Seite 15

Nachdem der Code vollständig entwickelt und getestet wurde, kann der Partner mit der Zertifizierung fortfahren. An dieser Stelle muss der Partner die folgenden Fragen mit "JA" beantworten können: 1. Sind Sie sicher, dass die technischen Spezifikationen von Amazon vollständig eingehalten wurden und Sie keine Fragen in Zusammenhang mit diesen Spezifikationen haben, die Sie bei der Zertifizierung stellen möchten? 2. Haben Sie alle vorhandenen AGCOD-Gateway-APIs (CreateGiftCard, CancelGiftCard) vollständig implementiert? 3. Wurde Ihr Code ausreichend getestet? Ihr Qualitätssicherungsprozess sollte eine ausgewogene Mischung aus Entwicklereinheitstests und (internen) QS-Integrationstests umfassen. 4. Sind Sie sicher, dass der Zertifizierungsprozess problemlos und ohne zusätzliche Fehler oder Codeänderungen verlaufen wird? 5. Werden Sie die Zertifizierung in Produktions- bzw. produktionsnahen Softwareprogrammen und Systemen und bei minimaler manueller Intervention ausführen? 6. Wissen Sie, ob und welchen Preisnachlass Sie für Gutscheincodes erhalten? 7. Sind Sie sicher, dass die erforderlichen internen Prozesse implementiert wurden, um sicherzustellen, dass Ihr Konto stets über das erforderliche Guthaben für den Kauf Geschenkkarten verfügt? Wenn Sie eine dieser Fragen nicht sicher mit "JA" beantworten können, wenden Sie sich bitte an [email protected].

(iii) Zertifizierung in der Sandbox Wenn der Partner die Vollständigkeit des Codes bestätigt und die Anwendung hinreichend intern getestet hat, beginnt Amazon mit dem Zertifizierungsvorgang. Amazon stellt ein Zertifizierungsdokument mit Szenarien aus, die in der Sandbox-Umgebung ausgeführt werden, um sicherzustellen, dass das System des Partners gemäß den geltenden Spezifikationen implementiert wurde.

2. Aktivierung der Produktion Nach der erfolgreichen Zertifizierung in der Sandbox-Umgebung erhält der Partner während des Produktions-Aktivierungsaufrufs durch Amazon Zugriff auf den Produktions-Endpunkt. Im Laufe dieses Aktivierungsaufrufs werden einige Produktions-Testszenarios durchlaufen, um eine erfolgreiche Aktivierung sicherzustellen. Nach erfolgreichem Abschluss dieser Testszenarios ist der Partner produktionsbereit und aufgenommen.

Seite 16

V. Technische Unterstützung durch Amazon (aktiver Vertrag erforderlich) Wenden Sie sich während des Entwicklungs- und Integrationsprozesses mit technischen Fragen per EMail an [email protected]. Hilfreiche Fallszenarien und Hinweise zur allgemeinen Fehlerbehebung finden Sie im Dokument Häufig gestellte Fragen und Anhänge. Bitte beachten Sie Folgendes: Wenn Sie keinen aktiven Vertrag besitzen und keinen Sandbox-Zugang erhalten haben, werden Sie von den Entwicklern, die diesen Alias überwachen, wahrscheinlich nicht erkannt. Arbeiten Sie mit Ihrem Kontoadministrator zusammen und führen Sie die erforderlichen Schritte aus, um Zugriff auf die Sandbox-Umgebung zu erhalten. Verwenden Sie bei der Kommunikation mit unseren Entwicklern unbedingt Ihre Partner-ID, damit diese Ihr Konto schnell identifizieren können. Geben Sie außerdem so viele der folgenden Informationen an wie möglich (sofern zutreffend):          

VI.

Vollständiges Paar aus Anfrage und Antwort Ihres AGCOD-API-Aufrufs Vollständige Endpunkt-URL (einschließlich Server-URL), die für die Anfrage verwendet wurde In der Anfrage verwendeter StringToSign, sofern nicht schon in der Anfrage/Antwort oben enthalten Entsprechende Signatur des verwendeten StringToSign, sofern nicht schon in der Anfrage/Antwort oben enthalten Ungefähre Uhrzeit der Anfrage (mit Zeitzone, die auf dem Rechner konfiguriert ist, von dem die oben genannte Anfrage gesendet wurde) Verwendete Programmiersprache Kürzlich vorgenommene Änderungen Ihrerseits (bzgl. Programmierung und Infrastruktur) Screenshot des Fehlers E-Mail-Adresse/Telefonnummer der technischen Ansprechperson des Partners Zeitzone des Partners

Anfrage-/Antwortbeispiele

Anfragenbeispiele einschließlich digitaler Signaturen finden Sie im Anhang 4 "Beispielcode und Beispielanfragen/-antworten" im Dokument Häufig gestellte Fragen und Anhänge. Die aufgeführten Beispiele wurden mit den im Anhang bereitgestellten Beispielcodes erstellt.

VII. Änderungsverlauf dieses Dokuments Datum

Version

Änderungen

Seite 17

23.02.15

1.01

Dokumenterstellung

11.06.15

1.02

Geringfügige Änderungen

11.09.17

1.03

Add external reference

18.09.17

1.04

Add balance inquiry

21.11.17

1.05

Added 15 minute cancellation rule

Seite 18