Créer des codes chèques-cadeaux

Assurez-vous de configurer votre compte API Amazon Incentives avant de commencer l’intégration. Créer un compte API Incentives.

L’API Incentives vous permet de créer et de distribuer rapidement des codes de demande de chèques-cadeaux Amazon via Internet.

Vous pouvez acheter ces codes via un service Web et les distribuer codes à vos clients. Ce document décrit comment les développeurs peuvent utiliser l’API AGCOD pour créer des codes de demande de chèques-cadeaux Amazon. Vous pouvez utiliser ces codes de plusieurs façons :

• Ajout de codes de demande de chèques-cadeaux à des chèques-cadeaux électroniques
• Cadeaux de groupe
• Échange en temps réel de codes de demande de chèques-cadeaux dans des programmes de fidélité (programmes par points)

• Opérations
  • CreateGiftCard
    • Requis pour les revendeurs : ProgramID
    • Requis pour les bons de produits : productType
    • Besoins supplémentaires aux points de vente
    • Facultatif : attribut de référence externe
    • Champs de réponse
  • CancelGiftCard
  • GetAvailableFunds
  • Exemple de demandes d’opération avec détails de signature
    • Paramètres requis
    • CreateGiftCard
      • Exemple de demande HTTP POST CreateGiftCard avec charge utile JSON
      • Exemple de demande HTTP POST CreateGiftCard avec charge utile XML
      • Exemple de réponse CreateGiftCard
    • CancelGiftCard
      • Exemple de demande HTTP POST CancelGiftCard avec charge utile JSON
      • Exemple de demande HTTP POST CancelGiftCard avec charge utile XML
      • Exemple de réponse CancelGiftCard
    • Exemple de signature V4 de réponse connue
• Traitement des erreurs
  • Codes d’erreur
• Traitement des codes de demande de chèques-cadeaux
• Limites des montants de transactions
• Script de test de création de codes numériques

Opérations

Votre code envoie des demandes HTTP POST signées à nos points de terminaison pour créer ou annuler des codes de demande. (Nous n’acceptons pas les demandes SOAP.) Le corps de vos demandes HTTP sera au format JSON ou XML.

Remarque : chaque demande sur un point de terminaison d’opérations de l’API Incentives doit être signée numériquement à l’aide de vos informations d’identification de sécurité de l’API Incentives et de l’algorithme de signature Signature Version 4.

Le tableau suivant décrit les concepts et les éléments que vous utiliserez lors d’appels vers ces points de terminaison :

Pour conserver le creationRequestId unique au niveau mondial, suivez les exigences suivantes :

• Générez une valeur alphanumérique unique au sein de votre système. Cet ID peut contenir jusqu’à 40 caractères alphanumériques.
• Commencez la creationRequestId valeur avec votre PartnerID.

Exemple : Si votre PartnerID est Amzn1, votre creationRequestId doit commencer par Amzn1 et tous les caractères supplémentaires que vous souhaitez dans votre ID (exemple : Amzn154321). Puisque l’API est idempotent, si une requête est envoyée avec un creationRequestId qui a été utilisé précédemment, l’API Incentives retournera le statut d'origine qui a été créé la première fois que le creationRequestId a été utilisé.

CreateGiftCard

Le CreateGiftCard opération crée un code chèque-cadeau en direct et déduit le montant du compte de prépaiement. La réponse contient les informations que vous devez stocker.

Le creationRequestId identifie de manière unique chaque demande de création, ainsi que d’autres informations comme le montant ou la devise (en plus des métadonnées concernant cette demande, les informations d’authentification, etc.).

Pour effectuer cette opération, plusieurs étapes sont nécessaires :

1. Le client envoie une demande CreateGiftCard à l’API Incentives.
2. Amazon confirme les fonds suffisants pour la demande en vérifiant le compte de prépaiement.
3. Amazon déduit le montant de la commande et répond avec un CreateGiftCard message de réponse synchrone qui contient gcClaimCode (le code chèque-cadeau en direct) et gcExpirationDate (la date d'expiration ne s'applique pas aux chèques-cadeaux créés aux États-Unis, au Canada et en Australie).
4. Votre code doit stocker le creationRequestId, amount, et les valeurs currencyCode et doit gérer les valeurs gcClaimCode en toute sécurité. Pour plus de détails, consultez Instructions sur le stockage des données.

Exemple de demande

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>

Exemple de réponse

<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>

Cette opération est idempotente, donc si l’API Incentives reçoit plus d’une requête avec la même creationRequestId, seule la première demande entraînera la création d'un nouveau chèque-cadeau, et toutes les réponses subséquentes retourneront le même chèque-cadeau original. Ils ne seront pas traités comme des transactions différentes.

Une invocation de l’appel CreateGiftCard entraîne la création d’un seul code de demande de chèque-cadeau. La création par lot n’est pas prise en charge pour le moment.

Requis pour les revendeurs : ProgramID

Vous pouvez utiliser le champ programID pour faciliter le suivi des transactions client et de cas d'utilisation. Le programID est un identifiant approuvé, fourni par Amazon via un processus de soumission. Vous devez d’abord soumettre les informations relatives au client et à l’utilisation par l’intermédiaire de votre gestionnaire de compte. Les soumissions approuvées reçoivent un numéro de référence appelé un programID que votre code inclura dans chaque appel de transaction à l'API. Le paramètre programID est alphanumérique et peut contenir jusqu’à 100 caractères.

L’exemple de message ci-dessous indique les modifications nécessaires pour prendre en compte le champ programID .

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

Requis pour les bons de produits : productType

Le productType est requis pour la création d’un code chèque-cadeau Pass Cadeaux Amazon. Vous devez recevoir l’autorisation d’utiliser ce champ. Ce champ sera différent et unique pour chaque type Pass Cadeaux. Si ce champ facultatif n’est pas transmis, le code de réclamation renvoyé correspond à un chèque-cadeau Amazon. Cet attribut est alphanumérique avec une longueur maximale de 50 caractères.

Remarque : Seuls les partenaires autorisés peuvent créer des bons de produits. Pour en savoir plus, contactez votre responsable de compte.

Les types de productType sont répertoriés dans cette feuille de calcul.

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

Besoins supplémentaires aux points de vente

Chaque appel à CreateGiftCard qui se produit à un point de vente doit inclure les détails de l’emplacement où la transaction a eu lieu. Les demandes adressées à ces points de terminaison peuvent inclure un transactionSource qui décrit l'emplacement physique de l'événement.

Il existe deux options pour envoyer les données d’emplacement du magasin à Amazon :

1. Forme longue : le partenaire fournit des données d'emplacement de magasin spécifiques pour chaque transaction (doit inclure sourceId, institutionId et sourceDetails)
2. Forme abrégée : le partenaire fournit uniquement le sourceId et institutionId dans la requête API. Un fichier de mappage d’emplacements distinct doit être envoyé pour mapper ces identifiants à des emplacements physiques. Reportez-vous aux instructions du fichier de mappage d’emplacements dans cette feuille de calcul.

Un exemple de charge utile de « forme longue » pour la source de transaction aux formats XML et JSON est illustré ci-dessous. Notez que sourceDetails doit être formaté en tant que blob JSON. Dans l’exemple JSON, l’objet blob JSON utilise la barre oblique inverse pour échapper les guillemets.

Exemple de forme longue de corps XML (notez que la valeur sourceDetails doit être formatée en tant que blob JSON) :

<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>

Exemple de forme courte du corps XML :

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

Exemple de forme courte du corps JSON :

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

Exemple de forme longue du corps JSON :

{
  "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\"}"
  }
}

Facultatif : attribut de référence externe

Vous pouvez utiliser le champ externalReference pour transmettre votre propre identifiant de référence sous forme de chaîne lorsque vous effectuez des demandes de codes chèques-cadeaux (jusqu’à 100 caractères Unicode). Le externalReference peut servir à stocker un mappage qui vous sera utile lors du suivi. Par exemple, vous pouvez spécifier des demandes de remboursement, des bornes, des dossiers clients, des numéros de commande, des comptes clients de revendeur, ou stocker des informations dans le champ externalReference .

Remarque : seules les références d’ordre opaques sans contenu en langage naturel sont autorisées dans ce champ.

L'identificateur transmis dans le champ externalReference apparaît avec la transaction dans le portail de l'API Incentives, dans le téléchargement de l’activité détaillée .

L'exemple suivant inclut un champ 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>

Champs de réponse

Ces éléments peuvent apparaître dans le corps de la réponse d’un appel réussi à l’opération CreateGiftCard.

Vous pouvez demander à nouveau un gcClaimCode ultérieurement en appelant CreateGiftCard à nouveau avec les mêmes valeurs creationRequestId, currencyCode, et les valeurs amount .

Le CreateGiftCard renvoie le statut de carte actuel d’un code chèque-cadeau.

Fulfilled - Le code chèque-cadeau a été créé avec succès.

<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>

RefundedToPurchaser –Le code chèque-cadeau a été annulé avec succès et remboursé lors d'un appel préalable à CancelGiftCard.

<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 – Le code chèque-cadeau n’a pas été utilisé avant la date d’expiration.

<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

Vous pouvez annuler un chèque-cadeau, tant qu’il n’est pas réclamé par un client Amazon. Le creationRequestId original utilisé pour créer le chèque-cadeau sera nécessaire pour annuler un chèque-cadeau.

Remarque : cette opération ne peut être exécutée que dans les 15 minutes suivant l’horodatage de la demande de création. Une fois la période écoulée, le code ne pourra pas être annulé et des frais seront déduits de votre solde prépayé.

Pour effectuer cette opération, envoyez une demande CancelGiftCard. L’API Incentives répondra avec un CancelGiftCardResponse synchrone.

Les deux opérations CreateGiftCard et CancelGiftCard sont idempotentes, Par conséquent, si l'API Incentives reçoit plus d'une telle requête avec le même creationRequestId, alors la première demande entraînera la création/l’annulation de la demande de chèque-cadeau, tandis que toutes les réponses ultérieures ne feront rien et ne seront pas traitées comme une transaction unique.

Exemple de demande

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>

Exemple de réponse

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

GetAvailableFunds

Cette opération renvoie le montant des fonds actuellement disponibles sur votre compte Amazon Incentives. Il offre une alternative à la connexion au portail de l’API Incentives pour afficher les fonds disponibles. Vous pouvez utiliser cette opération pour surveiller votre solde et déclencher des alertes.

Remarques :

• Cette opération est limitée à une transaction par seconde. Les tentatives d’envoi de demandes à un taux plus élevé seront ignorées.
• Étant donné qu’il n’y a pas de solde de compte réel dans un environnement sandbox, l’opération GetAvailableFunds renverra toujours un solde nul.

Exemple de demande

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"}

  Exemple de réponse

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

Exemple de demandes d’opération avec détails de signature

Cette section présente des exemples d’appels à CreateGiftCard et CancelGiftCard, y compris des exemples de valeurs de signature.

Paramètres requis

Remarque : la valeur de la devise (USD, GBP, EUR, JPY, AUD, TRY, AED) peut varier en fonction de vos paramètres régionaux.

Les en-têtes canoniques peuvent ressembler à ceci :

    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

ou ceci :

    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

Remarque : les exemples ci-dessous ont été créés à l’aide d’un compte de test Amazon. Vous devez utiliser vos propres identifiants d’accès (accessKeyID, partnerID, requestID).

Exemple de demande HTTP POST CreateGiftCard avec charge utile JSON

CHARGE UTILE

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

CHARGE UTILE HACHÉE

6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

DEMANDE CANONIQUE

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

DEMANDE CANONIQUE HACHÉE

447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

CHAÎNE À SIGNER

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

CLÉ DE SIGNATURE DÉRIVÉE

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71

POINT DE TERMINAISON

agcod-v2-gamma.amazon.com

DEMANDE SIGNÉE

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}}

Exemple de demande HTTP POST CreateGiftCard avec charge utile XML

CHARGE UTILE

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

CHARGE UTILE HACHÉE

e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

DEMANDE CANONIQUE

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

DEMANDE CANONIQUE HACHÉE

4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

CHAÎNE À SIGNER

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

CLÉ DE SIGNATURE DÉRIVÉE

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790

POINT DE TERMINAISON

agcod-v2-gamma.amazon.com

DEMANDE SIGNÉE

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>

Exemple de réponse CreateGiftCard

Corps de réponse JSON

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

Corps de réponse XML

<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

Exemple de demande HTTP POST CancelGiftCard avec charge utile JSON

CHARGE UTILE

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

CHARGE UTILE HACHÉE

 7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

DEMANDE CANONIQUE

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

DEMANDE CANONIQUE HACHÉE

0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

CHAÎNE À SIGNER

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

CLÉ DE SIGNATURE DÉRIVÉE

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949

POINT DE TERMINAISON

agcod-v2-gamma.amazon.com

DEMANDE SIGNÉE

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"
}

Exemple de demande HTTP POST CancelGiftCard avec charge utile XML

CHARGE UTILE

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

CHARGE UTILE HACHÉE

bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

DEMANDE CANONIQUE

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

DEMANDE CANONIQUE HACHÉE

8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

CHAÎNE À SIGNER

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

CLÉ DE SIGNATURE DÉRIVÉE

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87

POINT DE TERMINAISON

agcod-v2-gamma.amazon.com

DEMANDE SIGNÉE

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>

Exemple de réponse CancelGiftCard

Corps de réponse JSON

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

Corps de réponse XML

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

Paramètres requis

Remarque : la valeur de la devise (USD, GBP, EUR, JPY, AUD, TRY, AED) peut varier en fonction de vos paramètres régionaux.

• Méthode de demande HTTP=POST
• URI canonique=/CancelGiftCard
• Chaîne de requête canonique='' (chaîne vide)

• En-têtes canoniques=

    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
  

  ou

     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
  

• En-têtes signés=content-type;host;x-amz-date;x-amz-target
• Algorithme=AWS4-HMAC-SHA256
• Date de demande=20130910T222449Z
• Portée de l’identification=20130910/us-east-1/AGCODService/aws4_request
• Nom du service=AGCODService
• ID de la demande de création=AwssbTSpecTest001
• Hôte=agcod-v2-gamma.amazon.com (use applicable endpoint)
• Nom de la région=us-east-1 (utiliser le point de terminaison applicable)
• ID de partenaire=Awssb (utilisez votre propre ID de partenaire)

Exemple de signature V4 de réponse connue

Pour vous aider dans vos activités de développement, nous avons inclus un exemple de test avec une clé d’accès et des clés secrètes fictives pour générer un test de réponse connue à différentes étapes de la signature ci-dessous. Vous trouverez ici des instructions sur l’exécution de chaque étape de la signature. Reportez-vous également à ce diagramme du processus.

Paramètres utilisés

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

kSecret: votre-identifiant-de-sécurité
kDate: 41b8dd5e0d1716ba90401d46b58b12d500accdd2ea9c2b22a2d275946c9d978e
kRegion: 7b47360ce7afbe1b839e0b0e55834df99979a5414bc7f846b17c9374d230d45d
kService: 68136b0a64b2d01c8934370288b46500243645e468f521503e0d1fa73526d409
kSigning: 27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

CHARGE UTILE

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

CHARGE UTILE HACHÉE

50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

DEMANDE CANONIQUE

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

DEMANDE CANONIQUE HACHÉE

7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

CHAÎNE À SIGNER

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

CLÉ DE SIGNATURE DÉRIVÉE

27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

SIGNATURE

 e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1

POINT DE TERMINAISON

agcod-v2-gamma.amazon.com

DEMANDE SIGNÉE

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>

Traitement des erreurs

Chaque réponse envoyée à partir de l’API Incentives possède un élément status qui décrit l'état d'exécution de l'opération particulière ; il y a trois valeurs statusCode  : SUCCESS, FAILURE, et les valeurs RESEND. Reportez-vous à la section Traitement des erreurs pour plus de détails.

Codes d’erreur

Nous fournissons des ID de demande d’erreur simulée pour simuler certaines réponses d’erreur concernant les appels de création ou d’annulation. Lors de la simulation d’une réponse d’erreur, l’ID de demande d’erreur simulée doit être transmis en tant que le champ creationRequestId , semblable à un ID de requête normal. Les valeurs transmises pour les autres champs seront simplement répercutées dans la réponse. Pour simuler une réponse de réussite, la valeur de F1000 peut être transmise pour l’ID de demande d’erreur simulée. Reportez-vous aux sections Exemples de tests de simulation et Traitement des erreurs pour plus de détails.

Traitement des codes de demande de chèques-cadeaux

Les codes de demande de chèques-cadeaux ont une valeur monétaire et leur traitement doit être sécurisé. Nous recommandons de mettre en place des contrôles pour assurer la protection des données sensibles traitées (codes de demande de chèques-cadeaux, informations d’identification d’accès, etc.), notamment en définissant des audits appropriés sur les systèmes de fichiers et les bases de données servant au stockage des informations sensibles. Vous devez modifier périodiquement les mots de passe de vos comptes du portail de l’API Incentives ayant accès aux informations d’identification des clés secrètes. Nous vous recommandons d’effectuer une rotation de vos mots de passe au moins une fois tous les 180 jours (6 mois). Vous pouvez générer de nouvelles clés d’accès sur le portail de l’API Incentives à tout moment. Cependant, AGCOD ne prend pas en charge la rotation automatique des clés.

• Les codes doivent rester confidentiels pendant le transfert entre Amazon et vos systèmes.
• Les codes de demande ne doivent pas être stockés.
• Des pratiques sécuritaires de traitement des données devraient être mises en place dans vos locaux où les codes sont accessibles (en transfert ou au repos).

Pour plus de détails, consultez la section Instructions sur le stockage des données dans l’API Incentives.

Remarque : vous êtes responsable des codes de demande dès que l’API Incentives répond avec succès à votre demande CreateGiftCard.

Limites des montants de transactions

Les appels à CreateGiftCard doivent spécifier un code de devise autorisé par votre compte, dans la plage autorisée pour le pays d’émission.

Script de test de création de codes numériques

Pour vérifier votre intégration avec l’API, exécutez les tests suivants.