Guthaben auf Kundenkonten gutschreiben

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

Der Webservice "Anmelden und Empfangen" bietet eine API für die Auszahlung von Guthaben an einen neuen oder bestehenden Amazon-Kunden. Bei einer Auszahlung wird zum Geschenkgutschein-Guthaben auf dem Konto eines Amazon-Kunden in Echtzeit ein Geldwert hinzugebucht. Dieser REST-basierte Webservice ist Teil der Incentives-API, einer Reihe von Diensten, die Vorgänge für Amazon-Geschenkgutscheine unterstützen.

Rufen Sie "Anmelden und Empfangen" in den folgenden Anwendungsfällen auf:

• Sie benötigen sofortige und garantierte Auszahlungen in einer Währung an Ihre Kunden über eine bestehende Webanwendung.
• Sie müssen sicherstellen, dass der Geldwert nicht übertragbar ist, um rechtliche oder geschäftliche Verpflichtungen zu erfüllen.
• Sie möchten eine E-Mail-Benachrichtigung über ein Auszahlungsereignis an Kunden senden.

Auf dieser Seite wird beschrieben, wie Sie die API "Anmelden und Empfangen" aus Ihrer Anwendung aufrufen und welche Aufgaben Sie mit dieser API ausführen können.

• Schlüsselkonzepte und allgemeiner Ablauf
• Voraussetzungen
• API "Anmelden und Empfangen"
  • Vorgänge
    • LoadAmazonBalance
    • VoidAmazonBalanceLoad
    • GetAvailableFunds
• Anforderungen testen
• Testskript für "Anmelden und Empfangen"
• Leistung
• Fehlercodes

Schlüsselkonzepte und allgemeiner Ablauf

Die API "Anmelden und Empfangen" nutzt den Webservice Anmeldung mit Amazon, über den sich Benutzer innerhalb Ihrer browserbasierten oder mobilen Anwendung bei ihrem Amazon-Konto mit den Zugangsdaten für ihr Amazon-Konto authentifizieren können. Im Anschluss an die Authentifizierung stellt der Dienst "Anmeldung mit Amazon" Ihrer Anwendung eine Benutzer-ID zur Verfügung, die Sie als Eingabeparameter für die API "Anmelden und Empfangen" verwenden können. Zusammen ermöglichen diese Dienste eine reibungslose Erfahrung für Endbenutzer.

Sie können "Anmeldung mit Amazon" anpassen, um den Dienst auf die gewünschte Benutzererfahrung abzustimmen. Auch ein SDK ist verfügbar. Weitere Informationen finden Sie unter "Anmeldung mit Amazon" im Entwicklerportal.

Nachfolgend finden Sie eine Beschreibung des Anwendungs-Workflows für "Anmelden und Empfangen":

1. Ein Benutzer einer Anwendung fordert eine Gutschrift von Geschenkgutschein-Guthaben auf seinem Amazon-Konto an.
2. Ihre Anwendung zeigt eine Seite im Modul "Anmeldung mit Amazon" an, auf der der Benutzer aufgefordert wird, seine Amazon-Anmeldedaten einzugeben.
3. Neue Amazon-Kunden können sich im Workflow "Anmeldung mit Amazon" für ein neues Konto registrieren.
4. Wenn Ihr Code den Namen, die E-Mail-Adresse oder die Postleitzahl des Amazon-Kunden anfordert, holt der Workflow "Anmeldung mit Amazon" die Einwilligung des Kunden für die Weitergabe dieser Daten an Ihren Service ein.
5. Das Modul initiiert eine Autorisierungsanforderung mit der API "Anmeldung mit Amazon".
6. Ein ID-Wert, der das Benutzerkonto eindeutig identifiziert, wird in der Antwort als JSON-Objekt zurückgegeben.
7. Ihre Anwendung ruft die Methode LoadAmazonBalance mit dem Wert id in Ihrem Anforderungstext auf.
8. Der Vorgang LoadAmazonBalance aktualisiert das Geschenkgutschein-Guthaben auf dem Konto.
9. Amazon sendet eine E-Mail-Bestätigung an die für das Amazon-Kundenkonto hinterlegte E-Mail-Adresse, wenn die Beträge erfolgreich zum Guthaben auf dem Geschenkgutschein-Konto des Kunden hinzugebucht oder storniert wurden. Diese E-Mail enthält Text, der im Parameter notificationMessage der LoadAmazonBalance-Anforderung angegeben ist.

Hinweise:

• Der Benutzer kann den Workflow "Anmeldung mit Amazon" jederzeit abbrechen, indem er Abbrechen wählt oder das Popup-Fenster schließt (wenn diese UX-Methode verwendet wird).
• Die Speicherung personenbezogener Daten, die Rückschluss auf die Person zulassen, einschließlich Name, E-Mail-Adresse und Postleitzahl, erfordert zusätzliche Sicherheitsvorkehrungen, damit die DSGVO, der California Consumer Privacy Act (CCPA) und andere Datenschutzgesetze eingehalten werden.

Voraussetzungen

Führen Sie die folgenden Einrichtungsschritte aus, um "Anmelden und Empfangen" zu verwenden:

• Folgen Sie den Anweisungen im Leitfaden für die Einrichtung der Incentives-API-Integration, um ein Konto zu erstellen und einem Vertrag mit Amazon Incentives zuzustimmen.
• Integrieren Sie Ihre Web- oder mobile Anwendung mit dem Webservice "Anmeldung mit Amazon", um die Authentifizierung und (optional) den Zugriff auf Benutzerprofildaten zu ermöglichen. Für weitere Informationen dazu, wie Sie Ihre Anwendung mit "Anmeldung mit Amazon" integrieren können, führen Sie die Schritte im Developer Center für "Anmeldung mit Amazon"aus. Hinweis: Um „Anmeldung mit Amazon“ in Ihrer mobilen App verwenden zu können, müssen Sie das Mobil-SDK "Anmeldung mit Amazon" verwenden. Eine browserbasierte Interaktion von einer mobilen App aus ist technisch zwar möglich, doch wir verbieten dies aus Sicherheitsgründen.
• Die Sandbox ist eine Testumgebung, die Sie beim Entwickeln und Testen Ihrer Anwendung verwenden. Wenden Sie sich an Ihren Amazon-Kundenbetreuer, um Zugangsdaten für eine Sandbox zu erhalten. Sobald der Zugriff auf die Sandbox gewährt wurde, können Sie mit der Entwicklung und dem Testen beginnen und dabei den von Ihrem Amazon-Kundenbetreuer erhaltenen Partner-ID-Wert verwenden. Endpunkt-Basis-URLs für den Zugriff auf die Sandbox finden Sie im Abschnitt Regionen und Endpunkte. Mit dem Zugriff auf die Sandbox können Sie Ihren Code entwickeln und testen. Eine Anleitung hierzu finden Sie im Leitfaden für die Einrichtung der Incentives-API-Integration.

API "Anmelden und Empfangen"

Ihre Anwendung interagiert mit "Anmelden und Empfangen", indem sie synchrone Anforderungen an den Webdienst stellt. In diesem Abschnitt werden der Aufbau einer Anforderung und die verfügbaren Vorgänge beschrieben. Das Aufrufen eines Vorgangs besteht darin, eine HTTP-Anforderung an einen Incentives-API-Endpunkt zu senden und auf die Antwort zu warten. Eine REST-HTTP-Anforderung an das Gateway enthält eine Anforderungsmethode, einen URI, Header und einen Text, der entweder in XML oder JSON dargestellt wird. Die Antwort enthält einen HTTP-Statuscode, Antwort-Header und einen Antworttext. Jeder API-Aufruf muss mit Ihren Sicherheitsanmeldedaten und dem AWS Signature Version 4 Signing Process signiert werden.

Im Folgenden finden Sie eine Beschreibung der einzelnen API-Vorgänge, Anforderungs-Header und zugehörigen Parameter.

Vorgänge

Folgende Vorgänge werden unterstützt:

• LoadAmazonBalance
• VoidAmazonBalanceLoad
• GetAvailableFunds

LoadAmazonBalance

Der Vorgang LoadAmazonBalance wendet Beträge auf das Geschenkgutschein-Guthaben eines Amazon-Kunden an. Im Folgenden finden Sie eine Beschreibung der Parameter des Anforderungstextes.

Anforderungsbeispiel

POST 
/LoadAmazonBalance HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{   "loadBalanceRequestId":"Amazon123456",
    "partnerId":"Amazon",
    "amount":{
        "currencyCode":"USD",
        "value": 1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "transactionSource":{
        "sourceId":"Customer Service"
    },
    "externalReference":"serviceId:123",
    "notificationDetails":{
        "notificationMessage":"Thank you for your purchase!"
    }
}

Antwortbeispiel

{
    "status": "Success",
    "amount": {
        "currencyCode": "USD",
        "value": 9000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    },
    "loadBalanceRequestId": "Amazon123456"
}

VoidAmazonBalanceLoad

Dieser Vorgang storniert eine vorher ausgeführte LoadAmazonBalance-Anforderung, wenn der Betrag für den ausgegebenen Einlösungscode nicht bereits vom empfangenden Amazon-Kunden ausgegeben wurde. Dieser Vorgang kann bis spätestens 15 Minuten nach dem ursprünglichen Aufruf von LoadAmazonBalance ausgeführt werden. Danach bleibt ein Aufruf von VoidAmazonBalanceLoad wirkungslos.

Ihre Anwendung muss diesen Vorgang aufrufen, wenn Sie nicht bestätigen können, dass eine vorherige AmazonBalanceLoad-Anforderung erfolgreich war. Wenn Ihr Aufruf von LoadAmazonBalance beispielsweise kein Ergebnis zurückgibt, rufen Sie VoidAmazonBalanceLoad auf, um sicherzustellen, dass keine Beträge zum Geschenkgutschein-Guthaben des Amazon-Kunden hinzugebucht werden.

Im Folgenden finden Sie eine Beschreibung der Parameter des Anforderungstextes.

Hinweis: Alle unten aufgeführten Parameter müssen mit den in einer vorherigen LoadAmazonBalance-Anforderung verwendeten übereinstimmen.

Anforderungsbeispiel

POST 
/VoidAmazonBalanceLoad HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{
    "loadBalanceRequestId": "Amazon123456",
    "partnerId": "Amazon",
    "amount": {
        "currencyCode": "USD",
        "value": 1000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    }
}

Antwortbeispiel

{
    "status":"Success",
    "amount":{
        "currencyCode":"USD",
        "value":1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "loadBalanceRequestId":"Amazon123456"
}

GetAvailableFunds

Siehe GetAvailableFunds.

Anforderungen testen

Um Ihre Integration zu testen, können Sie eine Antwort aus der API simulieren, indem Sie eine Anforderungssimulation erstellen. Die Antwort auf die Anforderungssimulation wird durch den id-Parameter gesteuert. Zum Beispiel simuliert die Übergabe in id F0000 eine Erfolg-Antwort, während die Übergabe in id F1000 einen allgemeinen Fehler simuliert. Eine vollständige Liste der verfügbaren Antworten finden Sie in den Fehlercodes . Die folgenden Parameter sind (mindestens) erforderlich, um eine Anforderungssimulation aufzurufen:

{
  "loadBalanceRequestId": "Amazon123456",
  "account": {
    "id": "F2044",
    "type": "0"
  }
}

Hinweis: Alle Werte, die in anderen Feldern übergeben werden, werden einfach in der Antwort wiederholt und sind nicht erforderlich.

Simulationsanforderungsbeispiel

POST /LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{   "loadBalanceRequestId":"Amazon123456",
    "partnerId":"",
    "amount":{
        "currencyCode":"",
        "value":""
    },
    "account":{
        "id":"F2044",
        "type":"0"
    },
    "transactionSource":{
        "sourceId":""
    },
    "externalReference":"",
    "notificationDetails":{
        "notificationMessage":""
    }
}

Beispiel für eine Antwortsimulation

{
    "errorCode": "F2044",
    "errorMessage": "Source Id is too long. Received 41 characters. Maximum   
number of characters is 40",
    "errorType": "SourceIdTooLong",
    "status": "FAILURE"
}

Testskript für "Anmelden und Empfangen"

Sie können einige Komponenten Ihrer Integration mithilfe der Sandbox-Umgebung überprüfen. Vollständige End-to-End-Tests der Benutzererfahrung bei Ihren Anwendungen können jedoch nur über das Produktions-API-Konto abgeschlossen werden.

Sandbox: Simulieren Sie eine Antwort aus der LoadAmazonBalance-API, indem Sie eine "Anforderungssimulation" erstellen.

Produktion:

• Verwenden Sie die Komponente "Anmeldung mit Amazon", um einen gültigen customer.id-Wert für ein Amazon-Kundenkonto zu erhalten.
• Rufen Sie die Endpunkte LoadAmazonBalance und VoidAmazonBalanceLoad auf.
• Führen Sie End-to-End-Tests Ihrer Anwendung und der Benutzererfahrung durch.

Leistung

Die API ist so ausgelegt, dass Transaktionen mit einer maximalen Rate von 10 Transaktionen pro Sekunde (TPS) verarbeitet werden.

Hinweis: Die Sandbox-Umgebung wird nicht durch eine Dienstgütevereinbarung (SLA) geregelt, und es kann den Anschein haben, dass die Transaktionsraten nicht zuverlässig sind.

Fehlercodes

Zur Bezeichnung von Fehlercodes wenden wir eine bestimmte Nomenklatur an. Wenn die Ursache beispielsweise auf der Client-Seite liegt, antwortet die API mit einem F2xx-Fehler; ist das Problem hingegen auf ein Systemproblem bei Amazon zurückzuführen, antwortet die API mit F1XX. Im Allgemeinen haben Fehlercodes die in der folgenden Tabelle dargestellte Bedeutung.