Incentives-API für Amazon Geschenkgutscheine

Bevor Sie mit der Integration beginnen können, müssen Sie Ihr Amazon Incentives-API-Konto einrichten. Erstellen Sie ein Incentives-API-Konto.

Die Incentives-API bietet Programmierendpunkte, mit denen Sie diese Aufgaben in Echtzeit ausführen können:

• Erstellen Sie Einlösungscodes, die auf der Amazon-Website als Währung zum Kauf von Produkten verwendet werden können.
• Aktivieren Sie physische Geschenkgutscheine.
• Schreiben Sie das Geschenkgutschein-Guthaben eines Kundenkontos über Ihre App oder Website gut.
• Schreiben Sie das Geschenkgutschein-Guthaben eines Kundenkontos an einem physischen Standort gut.

Ihre Software kann synchrone Anforderungen an Incentives-API-Endpunkte stellen. Wenn Ihre Anforderung zu einem Einlösungscode führt, können Sie diesen Code in einer von Amazon genehmigten Weise an einen Kunden übermitteln.

• Endpunkte
  • Sandbox-Endpunkte
  • Produktionsendpunkte
• Erstellen von Anforderungen an die Incentives-API
  • Incentives-API-Zwischenablage
  • AWS Signature Version 4: Beispielcode
  • Beispiele für die Incentives-API
  • Allgemeine Anforderungs-Header
  • Implementieren von Signature Version 4
    • Aufgabe 1: Kanonische Anforderung erstellen
    • Aufgabe 2: Zu signierende Zeichenfolge erstellen
    • Aufgabe 3: Signatur erstellen
• Beispiel für signierte Anforderung
• Behandeln von Fehlern
• Fehlerbehebung für den Signiercode Ihrer Signatur
• Sichere Datenübertragung
• API-Antwortänderungen
• Incentives-API-Portal
• Umgang mit Schlüsseln
  • Sicherheit für Zugangsdaten
  • Schlüsselrotation
• Richtlinien zur Datenspeicherung
• Drosselungsraten
• Fehlerbehandlung
  • Fehlercodes
• Wenden Sie sich am Amazon, wenn Sie technischen Support benötigen (Voraussetzung hierfür ist ein aktiver Vertrag).
• Rechtliche Hinweise

Endpunkte

Anforderungen von Ihrem Code an eine Incentives-API enthalten eine Basis-URL, die Teil einer vollständigen Endpunktadresse ist. Ihr Code sendet Anforderungen an nur eine Basis-URL, die sich nach dem Land Ihrer Geschäftstätigkeit richtet. Wir bieten auch eine Sandbox, in der Sie jeden beliebigen Incentives-API-Endpunkt ohne Konsequenzen aufrufen können. Die folgenden Tabellen zeigen die Sandbox- und Produktionsbasis-URL-Werte für Länder, in denen die Incentives-API verfügbar ist.

Hinweis: Die zugrunde liegenden IP-Adressen dieser Endpunkte ändern sich häufig je nach Geografie und Last. Nehmen Sie keine Hartcodierung von IP-Adressen in Ihrem Code oder in Ihrer Firewall-Whitelist vor. Verwenden Sie nur die hier angezeigten vollständigen DNS-Adressen, um unsere Endpunkte zu erreichen.

Sandbox-Endpunkte

Produktionsendpunkte

Erstellen von Anforderungen an die Incentives-API

Jede Anforderung an einen Endpunkt der Incentives-API muss mit Ihren Incentives-API-Sicherheitsanmeldedaten und dem Signature Version 4-Signaturalgorithmus digital signiert werden. Das korrekte Signieren mit Signature Version 4 kann beim Aufruf von Incentives-API-Endpunkten die schwierigste Hürde sein. In diesem Abschnitt werden Ressourcen beschrieben, die Sie zum Erstellen Ihres Signaturcodes verwenden.

Incentives-API-Zwischenablage

Sie können einige Incentives-API-Vorgänge in einer Sandbox mit der Incentives-API-Zwischenablage aufrufen. Durch Anzeigen der Details der Anforderung und der Antwort kann dieses Tool veranschaulichen, wie ein Aufruf eines Incentives-API-Vorgangs aussehen sollte.

Hinweis: Wenn eine Anforderung mit einem JSON-Text übergeben wird, zeigt die Zwischenablage nicht den content_type-Header an, die auf application/json gesetzt ist.

AWS Signature Version 4: Beispielcode

Signature Version 4 ist ein AWS-Standard. Die AWS-Dokumentation enthält Codeausschnitte, die mithilfe dieser Signatur einen Vorgang aufrufen können. Die folgende Tabelle zeigt Parameter, die Sie im Python-POST-Beispiel ändern können; dieses finden Sie unter Beispiele für den vollständigen Signierprozess in Version 4. Mit diesen Änderungen ruft der Python-Code den CreateGiftCard-Vorgang in der Nordamerika-Sandbox unter Verwendung von JSON-Text auf:

Weitere Ausschnitte in Java, C#, Python, Ruby und JavaScript finden Sie auch hier: Beispiele für das Ableiten eines Signaturschlüssels für Signature Version 4

Beispiele für die Incentives-API

Wir bieten auch Beispielcode in Java, C#, Python, Ruby, PHP und HTML (JavaScript) an. Diese Beispiele sind so angepasst, dass die meisten Incentives-API-Vorgänge aufgerufen werden.

• Java-Beispiel
  • Sie können das Anforderungstextformat auswählen, indem Sie die Zeile des nicht bevorzugten Formats kommentieren.

  • 

• C#-Beispiel
  • Setzen Sie im AwsAuthenticator-Konstruktor den Parameter namespace auf com.amazonaws.agcod.
• Python-Beispiel
• Ruby-Beispiel
• PHP-Beispiel
• HTML-Beispiel

Hinweise:

• Der Beispielcode bietet keine gute Fehlerbehandlung und ist daher nicht "produktionsbereit"; er dient lediglich der Orientierung.
• Der bzw. die geheime Schlüssel/Zugriffsschlüssel/PartnerId wird in diesem Quellcode im Klartext angezeigt.
• Dieser Quellcode und die darin enthaltenen geheimen Schlüssel könnten in einigen Szenarien enthüllt werden. Dies gilt einschließlich für Szenarien, in denen ein nicht behandelter Fehler zu einem außerplanmäßigen Verhalten im Programm führt.

Geben Sie vor dem Testen die folgenden Parameter unter Verwendung Ihrer eigenen spezifischen Werte an:

• partnerId – Acme1
• currencyCode – USD für US, EUR für EU, JPY für JP, CAD für CA, AUD für AU, TRY für TR, AED für UAE
• agcodAccessKey – ihr-Sicherheitsnachweis
• agcodSecretKey – ihr-Sicherheitsnachweis
• region – us-east-1 (variiert je nach Standort und Umgebung – siehe Regionen und Endpunkte)
• endpoint – (variiert je nach Standort und Umgebung – siehe Regionen und Endpunkte)

Allgemeine Anforderungs-Header

Die Incentives-API erfordert in jeder HTTP-Anforderung die folgenden Header.

Für x-amz-date/date ist die folgende Datums- und Uhrzeitangabe ein gültiger x-amz-date-Wert: 20120325T120000Z. Der x-amz-date-Header ist für alle Anforderungen optional. Wenn der date-Header im ISO 8601-Basisformat angegeben wird, ist x-amz-date nicht erforderlich. Weitere Informationen finden Sie unter Behandlung von Daten in Signature Version 4 in der Allgemeinen Referenz zu Amazon Web Services. Der Zeitstempel muss bei Eingang der Anforderung innerhalb von 15 Minuten nach der Amazon-Systemzeit liegen. Andernfalls schlägt die Anforderung mit dem Fehlercode RequestExpired fehl, um zu verhindern, dass jemand anderes Ihre Anforderungen wiedergibt.

Implementieren von Signature Version 4

Die oben aufgeführten Beispiele treffen möglicherweise nicht genau auf Ihr Szenario zu. Um Signature Version 4 von Grund auf neu zu implementieren, lesen Sie zuerst die folgenden Themen:

• AWS-Anforderungen mit Signature Version 4 signieren
• Beispiel: Eine einfache GET-Anforderung mit Parametern
• Fehler in AWS Signature Version 4 beheben

Jede REST-Vorgangsanforderung, die Ihr Code sendet, muss eine Signatur enthalten. Um eine Anforderung zu signieren, erstellen Sie eine Zeichenfolge, die den Text Ihrer Anforderung zusammen mit Ihrem geheimen Zugriffsschlüssel enthält. Sie übergeben diese Zeichenfolge an eine kryptografische Hash-Funktion, die einen Hash-Wert zurückgibt. Sie fügen diesen Hash-Wert in das Signature-Feld des Autorisierungs-Headers Ihrer REST-Vorgangsanforderung ein. Bevor Sie Ihre Anforderung bearbeiten, berechnen unsere Dienste die Signatur mit den gleichen Eingaben neu und bestätigen, dass Ihr Autorisierungs-Hash-Wert unserer eigenen Berechnung entspricht.

Das API-Gateway unterstützt die Authentifizierung mit AWS Signature Version 4. Der Prozess zur Berechnung einer Signatur kann in drei Aufgaben unterteilt werden:

Aufgabe 1: Kanonische Anforderung erstellen

Erstellen Sie Ihre HTTP-Anforderung in dem kanonischen Format, das in Aufgabe 1 beschrieben wird: Erstellen Sie eine kanonische Anforderung für Signature Version 4 in der Allgemeinen Referenz zu Amazon Web Services.

Aufgabe 2: Zu signierende Zeichenfolge erstellen

Erstellen Sie eine Zeichenfolge, die Sie als einen der Eingabewerte für Ihre kryptografische Hash-Funktion verwenden. Die Zeichenfolge, die als zu signierende Zeichenfolge bezeichnet wird, ist eine Verkettung des Namens des Hash-Algorithmus, des Anforderungsdatums, einer Zeichenfolge für den Geltungsumfang der Zugangsdaten und der kanonischen Anforderung aus der vorherigen Aufgabe. Die Bereichszeichenfolge für Zugangsdaten selbst ist eine Verkettung von Datums-, Regions- und Dienstinformationen.

Geben Sie für den Parameter x-amz-credential den Code für den Endpunkt an, an den Sie die Anforderung senden möchten, z. B. us-east-1. Suchen Sie Ihre Region in den Endpunkt-Tabellen. Beispiel:

x-amz-credential=AKIAIGHKAVYIDBOH3O3A/20170118/us-east-1/AGCODService/aws4_request

Wichtig: Für Region, Dienstname und die spezielle Abschlusszeichenfolge müssen Sie die Kleinschreibung verwenden. Der x-amz-credential-Header wird verwendet, wenn Authentifizierungsparameter zur Abfragezeichenfolge hinzugefügt werden. Sie werden dem einzelnen Autorisierungs-Header genauso einfach hinzugefügt, und in diesem Fall wird x-amz-credential nicht angezeigt. Es ist also ein wenig verwirrend, x-amz-credential zu erwähnen, ein Schlüsselwort, das nur in einer bestimmten Instanz verwendet wird und nicht erforderlich ist. Sein Wert ist erforderlich, aber x-amz-credential ist nur erforderlich, wenn für die Durchführung der Authentifizierung Abfragezeichenfolgenparameter verwendet werden.

Aufgabe 3: Signatur erstellen

Erstellen Sie eine Signatur für Ihre Anforderung mithilfe einer kryptografischen Hash-Funktion, die zwei Eingabezeichenfolgen akzeptiert: die zu signierende Zeichenfolge und einen abgeleiteten Schlüssel. Der abgeleitete Schlüssel wird berechnet, indem Sie mit Ihrem geheimen Zugriffsschlüssel beginnen und die Zugangsdatenbereichszeichenfolge verwenden, um eine Reihe Hash-basierter Nachrichtenauthentifizierungscodes (HMACs) zu erstellen. Das folgende Diagramm veranschaulicht den allgemeinen Prozess der Berechnung einer Signatur:

Beispiel für signierte Anforderung

Zu signierende Nutzlast

{"loadBalanceRequestId":"Amazon123456","partnerId":"Amazon","amount":{"currencyCode":"USD","value":"1000"},"transactionSource":{"sourceId":"Customer Service"},"account":{"id":"amz1.account.123512341234","type":"2"}}

Hash-Nutzlast

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1 

Kanonische Anforderung (Leerzeilen einschließen)

POST /LoadAmazonBalance

accept: application/json
content-type: application/json
host: agcod-v2-gamma.amazon.com
x-amz-date: 20160708T073147Z
x-amz-target: com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target 24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Gehashte kanonische Anforderung

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14 

Zu signierende Zeichenfolge

AWS4-HMAC-SHA256 
20160708T073147Z 
20160708/us-east-1/AGCODService/aws4_request 
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14 

Abgeleiteter Signaturschlüssel

780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453 

Signatur

Ihre Signatur ist nicht die Gleiche, da Sie unterschiedliche Zugangsdaten für Sicherheitszugriffsschlüssel haben, hat aber das folgende Format:

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a

Signierte Nutzlast

POST /LoadAmazonBalance HTTP/1.1 
accept:application/json 
content-type:application/json 
host:agcod-v2-gamma.amazon.com 
x-amz-date:20160708T073147Z 
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance 
Authorization:AWS4-HMAC-SHA256 Credential=<AWS Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a 
{"loadBalanceRequestId":"Amazon123456","partnerId":"Amazon","amount":{"currencyCode":"USD","value":"1000"},"transactionSource":{"sourceId":"Customer Service"},"account":{"id":"amz1.account.123512341234","type":"2"}}

Behandeln von Fehlern

Jede vom Webdienst-Gateway gesendete Antwort verfügt über ein zugehöriges Statuselement, das den Ausführungsstatus für den jeweiligen Vorgang beschreibt. Es gibt drei Statuswerte: SUCCESS, FAILURE und RESEND. Weitere Informationen finden Sie unter Fehlerbehandlung, insbesondere für die Verarbeitung des RESEND-Ergebnisses mit Wiederholungslogik.

Fehlerbehebung für den Signiercode Ihrer Signatur

Hier können Sie die folgenden häufigsten Codierungsfehler nachlesen: http://docs.aws.amazon.com/general/latest/gr/signature-v4-examples.html

Häufige Codierungsfehler sind:

• Versehentliches Vertauschen des Schlüssels und der Daten bei der Berechnung von Zwischenschlüsseln. Als Ergebnis der Berechnung des vorherigen Schritts kommt der Schlüssel heraus, nicht die Daten. Lesen Sie sorgfältig die Dokumentation für Ihre kryptografischen Primitive, um sicherzustellen, dass Sie die Parameter in der richtigen Reihenfolge platzieren.
• Vergessen, dem Schlüssel für den ersten Schritt die Zeichenfolge "AWS" voranzustellen. Es ist möglich, die Schlüsselableitung mit einer "For-Schleife" oder einem Iterator zu implementieren. Vergessen Sie dabei nicht, die erste Iteration als Sonderfall anzugeben, so dass sie die Zeichenfolge "AWS" enthält.
• Vergessen, die Option asBytes für die JavaScript-Funktion HMAC.Crypto zu verwenden. Wenn Sie die Option asBytes nicht verwenden, führt die HMAC-Implementierung standardmäßig eine zusätzliche Hex-Codierung durch.
• Stellen Sie sicher, dass die Anforderungszeichenfolge in Ihrer Anforderung sowohl richtig sortiert als auch codiert ist, dass die Headernamen in Kleinbuchstaben umgewandelt wurden und dass die Header nach Zeichencode sortiert wurden. Siehe Kanonische Anforderung für Signature Version 4 erstellen.
• Für JSON-Text-Anforderungen ist nur content_type mit der Einstellung application/json erfolgreich.

Sichere Datenübertragung

Incentives-API-Endpunkte werden NUR über einen sicheren Port (HTTPS) geöffnet und der gesamte Datenverkehr über diesen Kanal wird mit SSL/TLS 1.2 geschützt. Dieses Industriestandard-Protokoll verschlüsselt Geschenkgutscheindaten während der Übertragung. In Ihren Systemen müssen Sie Ihre eigenen sicheren Mechanismen bereitstellen, um den unberechtigten Zugriff auf von SSL/TLS 1.2 verwendete Verschlüsselungsschlüssel zu verhindern.

Wichtig: API-Anforderungen müssen TLS 1.2 oder höher verwenden.

API-Antwortänderungen

Antworten von Incentives-API-Endpunkten enthalten häufig Informationen im XML- oder JSON-Datenaustauschformat. In Zukunft werden diesen Antworten möglicherweise neue Attribute hinzugefügt, und Elemente können in einer anderen Reihenfolge erscheinen. Ihr Code sollte zukünftige Änderungen im XML oder JSON eines Antworttextes angemessen mithilfe eines XML- oder JSON-Parsers verarbeiten. XPath analysiert beispielsweise Werte aus XML-Inhalten mithilfe einer Ausdruckssyntax. Eine Parserbibliothek ist zuverlässiger, wenn sich das Schema eines XML- oder JSON-Antworttextes ändert oder wenn es wächst.

Incentives-API-Portal

Im Incentives-API-Portal haben Sie folgende Möglichkeiten:

• Kontostand, durchschnittliche tägliche Ausgaben (in den letzten 14 Tagen), verbleibende Tage (basierend auf den durchschnittlichen Ausgaben) und Warnungen anzeigen.
• Detaillierte Transaktionsaktivitäten im Browser oder als Download anzeigen.
• Warnungen für niedrigen Kontostand festlegen.
• Amazon benachrichtigen, wenn Sie eine Zahlung ausgeführt haben.
• (Nur Administratoren) Neue Zugriffsschlüssel erstellen und vorhandene Schlüssel steuern.

Umgang mit Schlüsseln

Zugriffsschlüssel sind Anmeldedaten, mit denen Sie Ihre Programmabfragen bei einem beliebigen Incentives-API-Endpunkt signieren. Wie bei einem Benutzernamen und Kennwort müssen Sie sowohl die Zugriffsschlüssel-ID als auch den geheimen Zugriffsschlüssel zusammen verwenden, um alle Ihre Abfragen zu authentifizieren.

Ein Partnerkonto mit Administratorberechtigungen kann neue Zugriffsschlüssel und vorhandene Schlüssel über das Incentives-API-Portal auf der Seite API-Sicherheitsanmeldedaten steuern. (Für ein Partnerkonto, das keine Administratorberechtigungen besitzt, kann diese Seite nicht angezeigt werden. Sie können einen Zugriff für einen Kontoadministrator per E-Mail an incentives-api@amazon.com bei uns beantragen.)

Sicherheit für Zugangsdaten

Die auf der Seite API-Sicherheitsanmeldeinformationen angegebenen Zugriffsschlüssel und geheimen Schlüssel müssen vor unbefugtem Zugriff und unbeabsichtigter Freigabe geschützt sein. Dies gilt sowohl für Produktions- als auch für Sandbox-Zugangsdaten. Die Sicherheit Ihres Systems und Ihrer Geldbeträge basiert auf einem sicheren Umgang mit diesen Schlüsseln. Teilen Sie Ihre Schlüssel nicht.

Schlüsselrotation

Die regelmäßige Änderung von Zugriffsschlüsseln ist ein bewährtes Sicherheitsverfahren, das die geschäftlichen Auswirkungen eines gefährdeten Schlüssels verringert. Als Best Practice für die Sicherheit empfehlen wir Ihnen eine regelmäßige Rotation (Änderung) Ihrer Zugriffsschlüssel. Mit einer regelmäßig ausgeführten Änderungsroutine stellen Sie zudem sicher, dass es bei den Abläufen rund um die Schlüsselrotation keine Probleme gibt, und Ihr Unternehmen erhält die Gewissheit, dass der Ablauf sicher ist.

Sie sollten Ihre Zugriffsschlüssel mindestens alle 180 Tage (6 Monate) ändern. 30 Tage vor diesem Zeitpunkt erhalten Sie eine Erinnerungs-E-Mail. Bei Fragen wenden Sie sich bitte an Ihren Account Manager oder an incentives-api@amazon.com.

Gehen Sie folgendermaßen vor, um Ihre Zugriffsschlüssel zu ändern:

1. Klicken Sie im Incentives-API-Portal auf API-Sicherheitsanmeldedaten.
2. Klicken Sie auf Neuen Zugriffsschlüssel erstellen.
3. Aktualisieren Sie alle Anwendungen für die Verwendung des neuen Zugriffsschlüssels.
4. Vergewissern Sie sich mithilfe der neuen Schlüsselwerte, dass alle Anforderungen an Incentives-API-Vorgänge erfolgreich sind.
5. Klicken Sie für den ursprünglichen Schlüssel auf Deaktivieren.
6. Bestätigen Sie noch einmal mit den neuen Schlüsselwerten, dass alle Anforderungen an Incentives-API-Vorgänge erfolgreich sind. Prüfen Sie dies genau! Sobald ein Zugriffsschlüssel gelöscht wurde, kann er nicht wiederhergestellt werden.
7. Klicken Sie für den ursprünglichen Schlüssel auf Löschen.

Der neue Schlüssel wird jetzt verwendet und der ursprüngliche Schlüssel ist jetzt inaktiv und kann nicht mehr verwendet werden.

Richtlinien zur Datenspeicherung

In diesem Abschnitt werden einige Best Practices für die Verarbeitung von CreateGiftCard-Ergebnissen beschrieben, insbesondere von gcClaimCode-Werten.

Lesen Sie auch die Datensicherheitsanforderungen in den Einkaufs- und Vertriebsbedingungen für Amazon-Firmengeschenkgutscheine, einschließlich der Best Practices für Sicherheit in den Richtlinien für Firmengeschenkgutscheine.

in den Nutzungsbedingungen für die Amazon Incentives-API unter https://www.amazon.com/gp/help/customer/display.html?nodeId=202120960.

Richtlinien für das Anfordern und Speichern von Geschenkgutschein-Einlösungscodes, die von einem erfolgreichen Aufruf von CreateGiftCard zurückgegeben wurden:

• Ihr Clientcode generiert für jeden neuen Aufruf des CreateGiftCard-Vorgangs einen eindeutigen creationRequestId-Wert.
• Ihr Clientcode sollte die Werte creationRequestId, amount und currencyCode speichern, die in jeder Anforderung verwendet werden.
• Amazon speichert jeden gcClaimCode. Nachdem Sie einen Geschenkgutschein-Einlösungscode generiert haben, kann Ihr Code denselben Einlösungscode erneut abrufen, indem er eine neue Anforderung an CreateGiftCard mit denselben creationRequestId-, amount- und currency-Codewerten übermittelt. Dies kann eine sicherere Alternative zum Speichern von Geschenkgutschein-Einlösungscodes in Ihrer Datenbank sein.
• Einlösungscodes sollten Sie nicht speichern. Wenn Ihr Code vorübergehend Geschenkgutschein-Einlösungscodes speichert, müssen diese Werte entfernt werden, nachdem Sie den Geschenkgutschein-Einlösungscode an den Kunden geliefert haben. (Siehe Sicherheit.)
• Wenn Sie einen Geschenkgutschein-Einlösungscode stornieren müssen, muss Ihr Code innerhalb von 15 Minuten nach der Erstellung des Codes CancelGiftCard aufrufen.

Drosselungsraten

AGCOD drosselt eingehende Anforderungen bzw. lehnt sie ab, um einen Missbrauch des Systems zu verhindern. Die Anforderungsrate darf nicht mehr als 10 pro Sekunde betragen, einschließlich aller Transaktionsarten.

Wenn Anforderungen aus Ihrem Code eine Drosselungsrate überschreiten, schlägt Ihre Anforderung fehl und eine ThrottlingException wird zurückgegeben:

<ThrottlingException>
  <Message>Rate exceeded</Message>
</ThrottlingException>

Fehlerbehandlung

Jede vom AGCOD-Gateway gesendete Antwort verfügt über ein zugehöriges Statuselement, das den Ausführungsstatus für den jeweiligen Vorgang beschreibt. Es gibt drei statusCode-Werte: SUCCESS, FAILURE und RESEND.

SUCCESS

Eine Vorgangsantwort enthält den statusCode-Wert SUCCESS, wenn der Vorgang erfolgreich ist.

FAILURE

Eine Vorgangsantwort enthält den statusCode FAILURE, wenn die Anforderung von der Incentives-API nicht eingelöst werden kann. Diese Statusantwort kann sich auf ungültige Anforderungsdaten oder einen Geschäftslogikfehler beziehen, der vom Partner überprüft werden muss. Das Feld errorCode wird in solchen Fällen mit zusätzlichen Angaben zum Fehler ausgefüllt.

RESEND

Eine Vorgangsantwort enthält einen statusCode von RESEND und einen F400-Fehler, wenn ein temporärer Systemfehler vorliegt, der wahrscheinlich durch Wiederholung der Anforderung behoben werden kann. Es ist wichtig, dass Ihr Code eine Wiederholungslogik enthält, da ein F400-Fehler ein "unbekannter Zustand" ist, der zu Gebühren für Ihr Konto führen kann. Der RESEND-Fehler sollte nicht als Versagen interpretiert werden.

Hinweis: Die folgenden Schritte zeigen die Backoff-Strategie für einen Aufruf von ActivateGiftCard/DeactivateGiftCard. Ihr Code sollte diese Backoff-Strategie auch für Aufrufe von CreateGiftCard/CancelGiftCard und LoadAmazonBalance/VoidAmazonBalanceLoad verwenden.

1. Wenn Ihre Anforderung eine F400-Fehlermeldung zurückgibt und Sie denselben ActivateGiftCard-Vorgang erneut versuchen können, wiederholen Sie einfach diesen Vorgang. Wenn Sie den Vorgang nicht wiederholen können, fahren Sie mit Schritt 2 fort.
2. Senden Sie einen DeactivateGiftCard-Vorgang unter Verwendung desselben *requestId-Werts.
3. Wenn der Aufruf von DeactivateGiftCard SUCCESS zurückgibt, rufen Sie ActivateGiftCard erneut mit einem neuen *requestId-Wert auf.
4. Wenn der Aufruf von DeactivateGiftCard fehlschlägt, pausieren Sie eine Sekunde und senden Sie die gleiche DeactivateGiftCard-Anforderung erneut.
5. Wenn zehn Sekunden ohne eine erfolgreiche DeactivateGiftCard-Anforderung vergehen, erhöhen Sie die Verzögerung mit einem exponentiellen Backoff-Schema.
6. Wiederholen Sie den Vorgang nach 24 Stunden nicht mehr und senden Sie stattdessen eine E-Mail mit Einzelheiten zu den fehlgeschlagenen Vorgängen an Amazon.

Fehlercodes

Für Fehlercodes verwenden wir als Konvention F2XX-Codes zur Bezeichnung von Fehlern, die in Ihrer Anforderung enthalten sind, und F1XX-Codes für Fehler, deren Ursache auf der Seite von Amazon liegt.

Wir haben Simulations-Fehleranforderungs-IDs zur Verfügung gestellt, um bestimmte Fehlerantworten mit den Aufrufen Create/Cancel zu simulieren. Wenn eine Fehlerantwort simuliert wird, muss die Simulations-Fehleranforderungs-ID an das Feld creationRequestId übergeben werden, ähnlich wie eine normale Anforderungs-ID. Die für die übrigen Felder übergebenen Werte werden in der Antwort einfach wiederholt. Um eine erfolgreiche Antwort zu simulieren, kann der Wert F1000 für die Simulations-Fehleranforderungs-ID übergeben werden. Weitere Informationen finden Sie im Abschnitt "Beispiele für Testsimulationen".

Wenden Sie sich am Amazon, wenn Sie technischen Support benötigen (Voraussetzung hierfür ist ein aktiver Vertrag).

Während des gesamten Entwicklungs- und Integrationsprozesses können Sie sich mit technischen Fragen an Amazon wenden.

Wenn Sie keine aktive Vereinbarung geschlossen und keinen Sandbox-Zugriff erhalten haben, werden Sie von den Entwicklern, die diesen Alias überwachen, wahrscheinlich nicht erkannt. Es ist wichtig, dass Sie sich an Ihren Account Manager wenden, um die erforderlichen Schritte für den Erhalt des Sandbox-Zugriffs durchzuführen.

Geben Sie in Ihrer Kommunikation mit unseren Entwicklern unbedingt Ihre Partner-ID an, damit diese Ihr Konto leicht auffinden können. Bitte machen Sie die folgenden Angaben in Ihrer Kommunikation so vollständig wie möglich (soweit zutreffend):

• Vollständiges Anforderung-Antwort-Paar Ihres Aufrufs der Incentives-API
• Vollständige für die Anforderung verwendete Endpunkt-URL (einschließlich der Server-URL)
• Den StringToSign-Wert, der in der Anforderung verwendet wird, sofern nicht bereits in der Anforderung/Antwort oben aufgeführt
• Die entsprechende Signatur des verwendeten StringToSign-Werts, falls nicht bereits in der obigen Anforderung/Antwort aufgeführt
• Ungefähre Zeit (mit Zeitzone), die in Ihrer Anforderung verwendet wird (die Zeitzone, die auf dem Computer konfiguriert ist, der die obige Anforderung stellt)
• Verwendete Programmiersprache
• Haben Sie kürzlich Änderungen (an der Programmierung und/oder Infrastruktur) vorgenommen?
• Screenshot des Fehlers

Rechtliche Hinweise

Durch die Integration und Nutzung der Incentives-API erklären Sie sich (im eigenen Namen oder im Namen des Unternehmens, das Sie vertreten) damit einverstanden, an die Einkaufs- und Vertriebsbedingungen für Amazon-Firmengeschenkgutscheine gebunden zu sein, die auf https://www.amazon.com/gp/help/customer/display.html?nodeId=202120960 angegeben sind.