Einlösungscodes erstellen

Stellen Sie sicher, dass Sie Ihr Amazon Incentives-API-Konto einrichten, bevor Sie mit der Integration beginnen. Erstellen Sie ein Incentives API-Konto.

Mit der Incentives-API können Sie Einlösungscodes für Amazon-Geschenkgutscheine schnell über das Internet erstellen und verteilen.

Sie können Einlösungscodes für Amazon-Geschenkgutscheine über einen Webservice kaufen und diese Codes an Ihre Kunden verteilen. In diesem Dokument wird beschrieben, wie Entwickler die AGCOD-API zur Erstellung von Einlösungscodes für Amazon-Geschenkgutscheine verwenden können. Sie können diese Codes auf verschiedene Arten verwenden, einschließlich:

• Einfügen von Einlösungscodes in elektronische Geschenkgutscheine
• Gruppengeschenke
• Echtzeit-Einlösung von Einlösungscodes in Treueprogrammen (z. B. Punkteprogramme)

• Arbeitsabläufe
  • CreateGiftCard
    • Erforderlich für Wiederverkäufer: ProgramID
    • Erforderlich für Warengutscheine: productType
    • Zusätzliche Anforderungen an Standorte mit Geschäfts- und Verkaufsräumen
    • Optional: externes Referenzattribut
    • Antwortfelder
  • CancelGiftCard
  • GetAvailableFunds
  • Beispielanfragen mit Signaturdetails
    • Erforderliche Parameter
    • CreateGiftCard
      • Beispiel-HTTP POST-Anforderung für CreateGiftCard mit JSON-Nutzlast
      • Beispiel-HTTP POST-Anforderung für CreateGiftCard mit XML-Nutzlast
      • Beispiel-Antwort für CreateGiftCard
    • CancelGiftCard
      • Beispiel-HTTP POST-Anforderung für CancelGiftCard mit JSON-Nutzlast
      • Beispiel-HTTP POST-Anforderung für CancelGiftCard mit XML-Nutzlast
      • Beispiel-Antwort für CancelGiftCard
    • V4-Signatur-Beispiel mit bekannter Antwort
• Fehlerbehandlung
  • Fehlercodes
• Einlösungscodes für Geschenkgutscheine bearbeiten
• Limits für Transaktionsbeträge
• Testskript für digitale Codes erstellen

Arbeitsabläufe

Ihr Code stellt signierte HTTP POST-Anforderungen an unsere Endpunkte, um Einlösungscodes zu erstellen oder zu stornieren. (Wir akzeptieren keine SOAP-Anforderungen.) Der Hauptteil Ihrer HTTP-Anforderungen enthält JSON oder XML.

Hinweis: Jede Anforderung an einen Incentives-API-Vorgangsendpunkt muss mit Ihren Incentives-API-Sicherheitsanmeldedaten und dem Signaturalgorithmus von Signature Version 4 digital signiert werden.

In der folgenden Tabelle werden Konzepte und Elemente beschrieben, die Sie beim Aufruf dieser Endpunkte verwenden:

Damit die creationRequestId global eindeutig bleibt, folgen Sie den folgenden Anforderungen:

• Generieren Sie einen alphanumerischen Wert, der innerhalb Ihres Systems eindeutig ist. Diese ID kann bis zu 40 alphanumerische Zeichen enthalten.
• Beginnen Sie den Wert creationRequestId mit Ihrer partnerID.

Beispiel: Wenn Ihre partnerID Amzn1 lautet, muss Ihre creationRequestId mit Amzn1 und beliebigen Zusatzzeichen beginnen, die Sie für Ihrer ID möchten (Beispiel: Amzn154321). Da die API idempotent ist, gibt die Incentives-API, wenn eine Anforderung mit einer zuvor verwendeten creationRequestId eingesendet wird, den ursprünglichen Status zurück, der bei der ersten Verwendung der creationRequestId erstellt wurde.

CreateGiftCard

Der CreateGiftCard-Vorgang erstellt einen Live-Einlösungscode für Geschenkgutscheine und zieht den Betrag vom Vorauszahlungskonto ab. Die Antwort enthält Details, die Sie speichern müssen.

Der creationRequestId-Wert identifiziert jede Erstellungsanforderung eindeutig zusammen mit anderen Details wie Betrag, Währung usw. (zusätzlich zu den Metadaten zu dieser Anforderung, Authentifizierungsinformationen usw.).

Um diesen Vorgang auszuführen, müssen die folgenden Schritte ausgeführt werden:

1. Der Kunde sendet eine CreateGiftCard-Anforderung an die Incentives-API.
2. Amazon bestätigt ausreichende Guthaben für die Anforderung durch Überprüfung des Vorauszahlungskontos.
3. Amazon zieht den Bestellbetrag ab und antwortet mit einer synchronen CreateGiftCard-Antwortnachricht, die gcClaimCode (den Einlösungscode für Live-Geschenkgutscheine) und gcExpirationDate (Ablaufdatum, gilt nicht für Geschenkgutscheine, die in den USA, Kanada und Australien erstellt wurden) enthält.
4. Ihr Code muss die Werte creationRequestID, amount und currencyCode speichern und den gcClaimCode sicher behandeln. Weitere Informationen finden Sie unter Richtlinien zur Datenspeicherung.

Beispielanforderung

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/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

Beispielantwort

<CreateGiftCardResponse>
    <gcClaimCode>W3GU-YD4NGH-88C8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>EUR</currencyCode>
            <amount>1.00</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A3B6AC387ESRIX</gcId>
    <creationRequestId> AwssbTSpecTest001</creationRequestId>
    <gcExpirationDate>Mon Jun 09 21:59:59 UTC 2025</gcExpirationDate>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

Dieser Vorgang ist idempotent. Wenn die Incentives-API also mehr als eine Anforderung mit derselben creationRequestId erhält, führt nur die erste Anforderung zur Erstellung eines neuen Geschenkgutscheins, und alle nachfolgenden Antworten geben denselben ursprünglichen Geschenkgutschein zurück. Sie werden nicht als unterschiedliche Transaktionen behandelt.

Ein Aufruf des CreateGiftCard-Aufrufs führt dazu, dass nur ein Einlösungscode für Geschenkgutscheine erstellt wird (die Massenerstellung wird derzeit nicht unterstützt).

Erforderlich für Wiederverkäufer: ProgramID

Sie können das Feld programID verwenden, um Client- und Anwendungsfalltransaktionen zu verfolgen. Die programID ist eine genehmigte Kennung, die von Amazon im Rahmen eines Einreichungsverfahrens bereitgestellt wird. Sie müssen zunächst Kunden- und Anwendungsfallinformationen über unseren Partnerantragsprozess übermitteln. Genehmigte Übermittlungen erhalten eine Referenznummer namens programID, die Ihr Code bei jedem Transaktionsaufruf der API enthält. Die programID ist alphanumerisch und kann bis zu 100 Zeichen lang sein.

In der folgenden Beispielmeldung werden die Änderungen hervorgehoben, die erforderlich sind, um das Feld programID aufzunehmen.

<CreateGiftCardRequest>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <partnerId>Awssb</partnerId>
  <value>
    <currencyCode>EUR</currencyCode>
    <amount>1.00</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</CreateGiftCardRequest>

Erforderlich für Warengutscheine: productType

Das Feld productType ist für die Erstellung eines Amazon-Einlösungscodes für Warengutscheine erforderlich. Sie müssen eine Berechtigung erhalten, um dieses Feld zu verwenden. Dieses Feld ist für jeden Warengutscheintyp unterschiedlich und eindeutig. Wenn dieses optionale Feld nicht übergeben wird, wird der zurückgegebene Einlösungscode für einen Amazon-Geschenkgutschein verwendet. Dieses Attribut ist alphanumerisch mit einer maximalen Länge von 50 Zeichen.

Hinweis: Nur autorisierte Partner können Warengutscheine erstellen. Wenden Sie sich an Ihren Account Manager, um mehr zu erfahren.

Verfügbare productType finden Sie in dieser Tabelle.

<CreateGiftCardRequest>
  <creationRequestId>Humana_2018072650</creationRequestId>
  <partnerId>Humana</partnerId>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>25</amount>
  </value>
  <productType>bookPV</productType>
</CreateGiftCardRequest>

Zusätzliche Anforderungen an Standorte mit Geschäfts- und Verkaufsräumen

Jeder Aufruf von CreateGiftCard, der an einem Standort mit Geschäfts- und Verkaufsräumen stattfindet, muss Details des Ortes enthalten, an dem die Transaktion stattgefunden hat. Anforderungen an diese Endpunkte können ein transactionSource-Objekt enthalten, das den physischen Speicherort des Ereignisses beschreibt.

Es gibt zwei Möglichkeiten zum Senden von Shopstandortdaten an Amazon:

1. Langform – Ein Partner stellt für jede Transaktion spezifische Shopstandortdaten bereit (muss sourceId, institutionId und sourceDetails enthalten)
2. Kurzform – Ein Partner stellt nur die sourceId und institutionId in der API-Anforderung zur Verfügung. Es muss eine separate Standortzuordnungsdatei gesendet werden, die diese Bezeichner physischen Standorten zuordnet. Anweisungen zur Standortzuordnungsdatei finden Sie in dieser Tabelle.

Ein Beispiel der Nutzlast in der "Langform" für die Transaktionsquelle im XML- und JSON-Format ist unten dargestellt. Beachten Sie, dass sourceDetails als JSON-Blob formatiert werden muss. Im JSON-Beispiel verwendet das JSON-Blob den umgekehrten Schrägstrich, um Anführungszeichen zu escapen.

Beispiel für die Langform eines XML-Hauptteils (beachten Sie, dass der sourceDetails-Wert als JSON-Blob formatiert werden muss):

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

Beispiel für die Kurzform eines XML-Hauptteils:

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

Beispiel für die Kurzform eines JSON-Hauptteils:

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceId": "59990492",
    "institutionId": "99990492"
  }
}

Beispiel für die Langform eines JSON-Hauptteils:

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}",
    "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"
  }
}

Optional: externes Referenzattribut

Sie können das Feld externalReference verwenden, um Ihre eigene Referenzkennung als Zeichenfolge zu übergeben, wenn Sie Einlösungscode-Anforderungen stellen (bis zu 100 Unicode-Zeichen). Das Feld externalReference kann verwendet werden, um eine komfortable Zuordnung zu speichern, die Ihnen bei der Verfolgung hilft. Beispielsweise können Sie Versicherungsansprüche, Verkaufsstände, Kundenfälle, Bestellnummern, Kundenkonten für Wiederverkäufer oder Informationen zu Shops im Feld externalReference angeben.

Hinweis: In diesem Feld sind nur undurchsichtige Auftragsverweise ohne Inhalte in natürlicher Sprache zulässig.

Der im Feld externalReference übergebene Bezeichner wird mit der Transaktion im Incentives-API-Portal, im Download der Detailaktivität, angezeigt.

Das folgende Beispiel enthält ein Feld externalReference.

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/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
    <externalReference>889jj14797</externalReference>
</CreateGiftCardRequest>

Antwortfelder

Diese Elemente können im Antworthauptteil eines erfolgreichen Aufrufs des CreateGiftCard-Vorgangs angezeigt werden.

Sie können einen vorhandenen gcClaimCode später erneut anfordern, indem Sie CreateGiftCard erneut mit denselben creationRequestId-, currencyCode- und amount-Werten aufrufen.

Der CreateGiftCard-Endpunkt gibt den aktuellen cardStatus eines Einlösungscodes zurück.

Fulfilled – Der Einlösungscode wurde erfolgreich erstellt.

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

RefundedToUrchaser – Der Einlösungscode wurde erfolgreich storniert und bei einem vorherigen Aufruf von CancelGiftCard erstattet.

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>RefundedToPurchaser</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

Expired – Der Einlösungscode wurde nicht vor dem Ablaufdatum beansprucht.

<CreateGiftCardResponse>
    <gcClaimCode>G22G-WACQNJ-27S8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>JPY</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Expired</cardStatus>
    </cardInfo>
    <gcId>A2BWWZ1SGEZF2F</gcId>
    <creationRequestId>Awssb-ABR-10</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

CancelGiftCard

Sie können einen Geschenkgutschein stornieren, solange der Geschenkgutschein nicht von einem Amazon-Kunden beansprucht wird. Die ursprüngliche creationRequestId, die zum Erstellen des Geschenkgutscheins verwendet wird, ist erforderlich, um einen Geschenkgutschein zu stornieren.

Hinweis: Dieser Vorgang kann nur innerhalb von 15 Minuten nach dem Zeitstempel der Erstellungsanforderung ausgeführt werden. Nach Ablauf des Zeitraums kann der Einlösungscode nicht storniert werden, und die Gebühren werden von Ihrem vorausbezahlten Guthaben abgezogen.

Um diesen Vorgang auszuführen, senden Sie eine CancelGiftCard-Anforderung. Daraufhin antwortet die Incentives-API mit einer synchronen CancelGiftCardResponse.

Sowohl der CreateGiftCard- als auch der CancelGiftCard-Vorgang sind idempotent. Wenn also die Incentives-API mehr als eine solche Anforderung mit derselben creationRequestId erhält, führt die erste Anforderung zur Erstellung/Stornierung der Geschenkgutscheinanforderung, während alle nachfolgenden Antworten nichts erreichen und nicht als eine eindeutige Transaktion behandelt werden.

Beispielanforderung

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/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
</CancelGiftCardRequest>

Beispielantwort

<CancelGiftCardResponse>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <status>SUCCESS</status>
</CancelGiftCardResponse>

GetAvailableFunds

Dieser Vorgang gibt den Betrag an Guthaben zurück, der derzeit in Ihrem Amazon Incentives-Konto verfügbar ist. Er bietet eine Alternative zur Anmeldung im Incentives-API-Portal, um das verfügbare Guthaben anzuzeigen. Mit diesem Vorgang können Sie Ihr Guthaben überwachen und Warnungen auslösen.

Hinweise:

• Dieser Vorgang ist auf eine Transaktion pro Sekunde gedrosselt. Versuche, Anforderungen mit einer höheren Geschwindigkeit zu senden, werden ignoriert.
• Da in einer Sandbox kein tatsächlicher Kontosaldo vorhanden ist, gibt der GetAvailableFunds-Vorgang immer einen Null-Saldo zurück.

Beispielanforderung

POST 
/GetAvailableFunds HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.GetAvailableFunds
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657

{"partnerId": "Aptuk"}

  Beispielantwort

{
"availableFunds":{
"amount":10.0,
"currencyCode":"USD"
},
"status":"SUCCESS",
"timestamp":20170915T200959Z
}

Beispielanfragen mit Signaturdetails

Dieser Abschnitt zeigt Beispielaufrufe von CreateGiftCard und CancelGiftCard, einschließlich Beispielsignaturwerte.

Erforderliche Parameter

Hinweis: Der Währungswert (USD, GBP, EUR, JPY, AUD, TRY, AED) kann je nach Gebietsschema variieren.

Kanonische Kopfzeilen können wie folgt aussehen:

    accept:application/json
    content-type:application/json
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T222620Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

oder so:

    content-type:application/x-www-form-urlencoded; charset=UTF-8
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T221949Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

CreateGiftCard

Hinweis: Die folgenden Beispiele wurden mit einem Amazon-Testkonto erstellt. Sie sollten Ihre eigenen Zugriffskennungen (accessKeyID, partnerID, requestID) verwenden.

Beispiel-HTTP POST-Anforderung für CreateGiftCard mit JSON-Nutzlast

PAYLOAD

{"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "value": {"currencyCode": "USD", "amount": 1.00}}

HASHED PAYLOAD

6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

CANONICAL REQUEST

POST
/CreateGiftCard

accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

HASHED CANONICAL REQUEST

447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222620Z
20130910/us-east-1/AGCODService/aws4_request
447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71
{"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "value": {"currencyCode": "USD", "amount": 1.00}}

Beispiel-HTTP POST-Anforderung für CreateGiftCard mit XML-Nutzlast

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

CANONICAL REQUEST

POST
/CreateGiftCard

accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

HASHED CANONICAL REQUEST

4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T221949Z
20130910/us-east-1/AGCODService/aws4_request
4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

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-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

Beispiel-Antwort für CreateGiftCard

JSON-Antworthauptteil

{
  "cardInfo": {
    "cardNumber": null,
    "cardStatus": "RefundedToPurchaser",
    "expirationDate": null,
    "value": {
      "amount": 1,
      "currencyCode": "USD"
    }
  },
  "creationRequestId": "AwssbTSpecTest001",
  "gcClaimCode": "Z7NV-LBBG39-75MU",
  "gcExpirationDate": null,
  "gcId": "A2GCN9BRX5QS76",
  "status": "SUCCESS"
}

XML-Antworthauptteil

<CreateGiftCardResponse>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <cardInfo>
    <value>
      <amount>1.0</amount>
      <currencyCode>USD</currencyCode>
    </value>
    <cardStatus>Fulfilled</cardStatus>
  </cardInfo>
  <status>SUCCESS</status>
  <gcId>A2GCN9BRX5QS76</gcId>
  <gcClaimCode>Z7NV-LBBG39-75MU</gcClaimCode>
</CreateGiftCardResponse>

CancelGiftCard

Beispiel-HTTP POST-Anforderung für CancelGiftCard mit JSON-Nutzlast

PAYLOAD

 {"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "gcId": "A2GCN9BRX5QS76"}

HASHED PAYLOAD

 7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

CANONICAL REQUEST

POST
/CancelGiftCard

accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

HASHED CANONICAL REQUEST

0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222545Z
20130910/us-east-1/AGCODService/aws4_request
0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CancelGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949
{
  "creationRequestId": "AwssbTSpecTest001",
  "partnerId": "Awssb",
  "gcId": "A2GCN9BRX5QS76"
}

Beispiel-HTTP POST-Anforderung für CancelGiftCard mit XML-Nutzlast

PAYLOAD

<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

HASHED PAYLOAD

bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

CANONICAL REQUEST

POST
/CancelGiftCard

accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

HASHED CANONICAL REQUEST

8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222449Z
20130910/us-east-1/AGCODService/aws4_request
8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

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-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

Beispiel-Antwort für CancelGiftCard

JSON-Antworthauptteil

{"creationRequestId":"AwssbTSpecTest001","gcId":"A2GCN9BRX5QS76","status":"SUCCESS"}

XML-Antworthauptteil

<CancelGiftCardResponse>
<creationRequestId>AwssbTSpecTest001</creationRequestId>
<status>SUCCESS</status>
<gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardResponse>

Erforderliche Parameter

Hinweis: Der Währungswert (USD, GBP, EUR, JPY, AUD, TRY, AED) kann je nach Gebietsschema variieren.

• HTTP-Anforderungsmethode=POST
• Kanonischer URI=/CancelGiftCard
• Kanonische Abfragezeichenfolge=" (leere Zeichenfolge)

• Kanonische Kopfzeilen=

    accept:application/json
    content-type:application/json
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T222545Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
  

  oder

     accept:application/x-www-form-urlencoded; charset=UTF-8
     content-type:application/x-www-form-urlencoded; charset=UTF-8
     host:agcod-v2-gamma.amazon.com
     x-amz-date:20130910T222449Z
     x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
  

• SignedHeaders=content-type;host;x-amz-date;x-amz-target
• Algorithmus=AWS4-HMAC-SHA256
• Anforderungsdatum=20130910T222449Z
• CredentialScope=20130910/us-east-1/AGCODService/aws4_request
• Dienstname=AGCODService
• Erstellungsanforderungs-ID=AwssbTSpecTest001
• Host=agcod-v2-gamma.amazon.com (anwendbaren Endpunkt verwenden)
• Regionenname=us-east-1 (anwendbaren Endpunkt verwenden)
• Partner-ID=Awssb (eigene Partner-ID verwenden)

V4-Signatur-Beispiel mit bekannter Antwort

Um Sie bei der Entwicklung zu unterstützen, haben wir ein Testbeispiel mit fiktiven Zugriffsschlüsseln/geheimen Schlüsseln enthalten, um einen Test mit bekannter Antwort für verschiedene Phasen der unten stehenden Unterzeichnung zu generieren. Details zur Ausführung auf jeder Stufe der Unterzeichnung finden Sie hier. Siehe auch dieses Diagramm des Prozesses.

Verwendete Parameter

Partner ID: Test
creationRequestId: Test001
AGCODAccess Key: fake-access-key
AGCOD Secret Key: fake-secret-key
Timestamp: 20140205T171524Z

kSecret: ihr-Sicherheitsnachweis
kDate: 41b8dd5e0d1716ba90401d46b58b12d500accdd2ea9c2b22a2d275946c9d978e
kRegion: 7b47360ce7afbe1b839e0b0e55834df99979a5414bc7f846b17c9374d230d45d
kService: 68136b0a64b2d01c8934370288b46500243645e468f521503e0d1fa73526d409
kSigning: 27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>Test001</creationRequestId>
    <partnerId>Test</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

CANONICAL REQUEST

POST
/CreateGiftCard
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

HASHED CANONICAL REQUEST

7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

STRING TO SIGN

AWS4-HMAC-SHA256
20140205T171524Z
20140205/us-east-1/AGCODService/aws4_request
7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

DERIVED SIGNING KEY

27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

SIGNATURE

 e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=fake-aws-key/20140205/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1
<CreateGiftCardRequest>
    <creationRequestId>Test001</creationRequestId>
    <partnerId>Test</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</CreateGiftCardRequest>

Fehlerbehandlung

Jede von der Incentives-API gesendete Antwort verfügt über ein Statuselement, das den Ausführungsstatus für den jeweiligen Vorgang beschreibt. Es gibt drei statusCode-Werte: SUCCESS, FAILURE und RESEND. Weitere Informationen finden Sie unter Fehlerbehandlung.

Fehlercodes

Wir verwenden eine Konvention von F2XX-Codes, um Fehler zu bezeichnen, wenn die Anforderung ungültig ist. Wir verwenden eine Konvention von F1XX, wenn die Ursache bei Amazon liegt.

Wir haben Mock-Fehleranforderungs-IDs zur Verfügung gestellt, um bestimmte Fehlerantworten mit den Create/Cancel-Aufrufen zu simulieren. Wenn eine Fehlerantwort simuliert wird, muss die Mock-Fehleranforderungs-ID an das Feld creationRequestId übergeben werden, ähnlich wie eine normale Anforderungs-ID. Die Werte, die für den Rest der Felder übergeben werden, werden einfach in der Antwort wiederholt. Um eine erfolgreiche Antwort zu simulieren, kann der Wert von F1000 für die Mock-Fehleranforderungs-ID übergeben werden. Weitere Informationen finden Sie unter Mocking-Testbeispiele und Fehlerbehandlung.

Einlösungscodes für Geschenkgutscheine bearbeiten

Einlösungscodes für Geschenkgutscheine haben monetären Wert und müssen sehr sicher behandelt werden. Wir empfehlen, Kontrollmechanismen einzusetzen, um den sicheren Umgang mit sensiblen Daten (Einlösungscodes für Geschenkgutscheine, Anmeldedaten für Sicherheitszugriff usw.) zu gewährleisten. Dazu gehört die Definition angemessener Überwachungskontrollmechanismen für Dateisysteme/Datenbanken, in denen sensible Informationen gespeichert sind. Sie sollten das Kennwort Ihrer Incentives-API-Portalkonten, die Zugriff auf geheime Schlüssel-Anmeldeinformationen haben, regelmäßig ändern. Wir empfehlen Ihnen, Ihre Zugangsschlüssel mindestens einmal alle 180 Tage (6 Monate) durchzuwechseln. Mit dem Incentives-API-Portal können Sie jederzeit einen neuen Zugriffsschlüssel generieren. AGCOD unterstützt jedoch keine automatische Schlüsselrotation.

• Einlösungscodes sollten während der Übermittlung zwischen Amazon und Ihren Systemen vertraulich behandelt werden.
• Einlösungscodes sollten nicht gespeichert werden.
• Es sollten Datenverarbeitungspraktiken in Ihren Einrichtungen vorhanden sein, in denen Einlösungscodes zugänglich sind (entweder während der Übermittlung oder am Speicherort).

Weitere Informationen finden Sie unter Richtlinien für die Incentives-API-Datenspeicherung.

Hinweis: Sie haften für die Einlösungscodes, sobald die Incentives-API erfolgreich auf Ihre CreateGiftCard-Anforderung reagiert.

Limits für Transaktionsbeträge

Aufrufe für CreateGiftCard müssen einen von Ihrem Konto autorisierten Währungscode innerhalb des für das Ausstellungsland zulässigen Bereichs angeben.

Testskript für digitale Codes erstellen

Führen Sie die folgenden Tests durch, um Ihre Integration in die API zu überprüfen.