API Incentives

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

L’API Incentives fournit des points de terminaison de programmation qui vous permettent d’effectuer ces tâches en temps réel :

• Créez des codes de demande qui peuvent être utilisés sur le site Web Amazon comme devise pour acheter des produits.
• Activez des chèques-cadeaux physiques.
• Créditez le solde de chèque-cadeau d’un compte client via votre application ou votre site Web.
• Créditez le solde de chèque-cadeau d’un compte client sur un site de briques et mortier.

Votre logiciel peut effectuer des demandes synchrones aux points de terminaison de l’API Incentives. Si votre demande génère un code de demande, vous pourrez le fournir à un client selon une méthode approuvée par Amazon.

• Points de terminaison
  • Points de terminaison d’environnement sandbox
  • Points de terminaison d’environnement de production
• Créer des demandes dans l’API Incentives
  • Bloc-notes de l’API Incentives
  • Exemple de code AWS Signature Version 4
  • Exemples de l’API Incentives
  • En-têtes de demandes communs
  • Implémentation de Signature Version 4
    • Tâche 1 : créer une demande canonique
    • Tâche 2 : créer une chaîne à signer
    • Tâche 3 : créer une signature
• Exemple de demande signée
• Traitement des erreurs
• Dépannage de votre code de signature
• Transmission sécurisée des données
• Modifications de la réponse de l’API
• Portail API Incentives
• Traitement des clés
  • Sécurité des informations d’identification
  • Rotation des clés
• Instructions sur le stockage des données
• Taux limites
• Traitement des erreurs
  • Codes d’erreur
• Contacter le support technique d’Amazon (nécessite un contrat actif)
• Informations légales

Points de terminaison

Les demandes de votre code vers une API Incentives incluent une URL de base qui fait partie d’une adresse de point de terminaison complète. Votre code enverra les demandes à une seule URL de base déterminée par votre pays d’exploitation. Nous fournissons également un environnement sandbox dans lequel vous pouvez appeler n’importe quel point de terminaison de l’API Incentives sans conséquences. Les tableaux suivants présentent les valeurs des URL de base des environnements sandbox et de production pour les pays où l’API Incentives est disponible.

Remarque : les adresses IP sous-jacentes de ces points de terminaison changent fréquemment en fonction de la géographie et de la charge. Ne codez pas en dur les adresses IP dans votre code ou dans votre liste blanche de pare-feu. Utilisez uniquement les adresses DNS complètes indiquées ici pour atteindre nos points de terminaison.

Points de terminaison d’environnement sandbox

Points de terminaison d’environnement de production

Créer des demandes dans l’API Incentives

Chaque demande sur un point de terminaison 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. Lors de l’appel des points de terminaison de l’API Incentives, il peut être difficile de fournir des signatures correctes à l’aide de Signature Version 4. Cette section décrit les ressources disponibles pour créer votre code de signature.

Bloc-notes de l’API Incentives

Vous pouvez appeler certaines opérations de l’API Incentives dans un environnement sandbox à l’aide du bloc-notes de l’API Incentives. En affichant les détails de la demande et de la réponse, cet outil montre à quoi devrait ressembler un appel à une opération de l’API Incentives.

Remarque : Lors du passage d’une requête avec un corps JSON, le scratchpad n’affiche pas l’en-tête content_type , qui est défini sur application/json.

Exemple de code AWS Signature Version 4

Signature Version 4 est une norme AWS. La documentation AWS inclut des extraits de code pouvant appeler une opération à l’aide de cette signature. Le tableau suivant présente les paramètres que vous pouvez modifier dans l’exemple POST (Python) décrit sur cette page : Exemples du processus de signature complet Signature Version 4. Avec ces modifications, le code Python appelle l’opération CreateGiftCard dans l’environnement sandbox d’Amérique du Nord à l’aide d’un corps JSON :

Vous trouverez également des extraits supplémentaires en langages Java, C#, Python, Ruby et JavaScript sur cette page : Exemples de dérivation d’une clé de signature pour Signature Version 4

Exemples de l’API Incentives

Nous fournissons également un exemple de code Java, C#, Python, Ruby, PHP et HTML (JavaScript). Ces exemples sont personnalisés pour appeler la plupart des opérations de l’API Incentives.

• Exemple Java
  • Vous pouvez sélectionner le format du corps de la demande en commentant la ligne du format non préféré.

  • 

• Exemple C #
  • Dans le constructeur AWSAuthenticator, définissez le paramètre namespace sur com.amazonaws.agcod
• Exemple Python
• Exemple Ruby
• Exemple PHP
• Exemple HTML

Remarques :

• cet exemple de code ne permet pas de traiter correctement les erreurs et n’est donc pas « prêt pour la production ». Il doit être utilisé uniquement comme référence.
• La clé secrète, la clé d’accès et l’ID de partenaire apparaissent en texte clair dans ce code source.
• Ce code source et les données secrètes peuvent parfois être affichés, y compris dans des scénarios où une erreur non traitée conduit à un comportement non déterministe dans le programme.

Fournissez les paramètres suivants en utilisant vos propres valeurs spécifiques avant de commencer le test :

• partnerId - Acme1
• currencyCode – USD pour É-U, EUR pour UE, JPY pour JP, CAD pour CA, AUD pour AU, TRY pour TR, AED pour ÉAU
• agcodAccessKey - votre-identifiant-de-sécurité
• agcodSecretKey - votre-identifiant-de-sécurité
• region – us-east-1 (varie en fonction de la localisation et de l’environnement (voir Régions et points de terminaison)
• endpoint (varie en fonction de la localisation et de l’environnement (voir Régions et points de terminaison)

En-têtes de demandes communs

L’API Incentives requiert les en-têtes suivants dans chaque demande HTTP.

Pour x-amz-date/date, l’heure de date suivante est une valeur x-amz-date valide : 20120325T120000Z. L’en-tête x-amz-date est facultatif pour toutes les demandes. Si l’en-tête date est spécifié dans le format de base ISO 8601, x-amz-date n’est pas nécessaire. Pour plus d’informations, consultez la page Gestion des dates dans Signature Version 4 dans les références générales d’Amazon Web Services. L’horodatage doit être inclus dans les 15 minutes suivant l’heure du système Amazon lors de la réception de la demande. Si ce n’est pas le cas, la requête échoue avec le code d’erreur RequestExpired pour empêcher un autre utilisateur de répéter vos demandes.

Implémentation de Signature Version 4

Les exemples ci-dessus peuvent ne pas s’appliquer à votre scénario. Pour une implémentation complète de Signature Version 4, passez en revue les points suivants :

• Signature des demandes AWS avec Signature Version 4
• Exemple - une requête GET simple avec les paramètres
• Dépannage des erreurs d’AWS Signature Version 4

Chaque demande d’opération REST envoyée par votre code doit inclure une signature. Pour signer une demande, créez une chaîne qui inclut le texte de votre demande ainsi que votre clé d’accès secrète. Transmettez cette chaîne à une fonction de hachage cryptographique, qui renvoie une valeur de hachage. Incluez cette valeur de hachage dans le champ Signature de l’en-tête Authorization de votre demande d’opération REST. Avant de traiter votre demande, nos services recalculent la signature en utilisant les mêmes entrées, puis confirment que votre valeur de hachage Authorization correspond à notre calcul.

La passerelle de l’API prend en charge l’authentification à l’aide d’AWS Signature Version 4. Le processus de calcul d’une signature peut être divisé en trois tâches :

Tâche 1 : créer une demande canonique

Créez votre demande HTTP au format canonique décrit dans la section Tâche 1 : créer une demande canonique pour Signature Version 4 dans les références générales d’Amazon Web Services.

Tâche 2 : créer une chaîne à signer

Créez une chaîne que vous utiliserez comme l’une des valeurs d’entrée de votre fonction de hachage cryptographique. La chaîne, appelée chaîne à signer, est une concaténation du nom de l’algorithme de hachage, de la date de la demande, d’une chaîne de portée des informations d’identification et de la demande canonique de la tâche précédente. La chaîne de portée des informations d’identification elle-même est une concaténation des informations de date, de région et de service.

Pour le paramètre x-amz-credential , spécifiez le code du point de terminaison où vous allez envoyer la requête, par exemple, us-east-1. Recherchez votre région dans les tableaux Points de terminaison. Exemple :

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

Important : vous devez utiliser des minuscules pour la région, le nom du service et la chaîne de fin spéciale. L’en-tête x-amz-credential est utilisé lorsque des paramètres d’authentification sont ajoutés à la chaîne de requête. Ils sont aussi facilement ajoutés à l’en-tête d’autorisation unique, et dans ce cas, x-amz-credential n’apparaît pas. Donc, c’est un peu déroutant de mentionner x-amz-credential, un mot-clé qui n’est utilisé que dans une instance particulière et qui n’est pas requis. Sa valeur est requise, mais la valeur x-amz-credential n’est requis que lorsque les paramètres de chaîne de requête sont utilisés pour effectuer l’authentification.

Tâche 3 : créer une signature

Créez une signature pour votre demande en utilisant une fonction de hachage cryptographique qui accepte deux chaînes d’entrée : votre chaîne à signer et une clé dérivée. La clé dérivée est calculée à partir de votre clé d’accès secrète et de la chaîne de portée des informations d’identification pour créer plusieurs codes d’authentification de messages basés sur le hachage. Le diagramme suivant illustre le processus général de calcul d’une signature :

Exemple de demande signée

Charge utile à signer

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

Charge utile hachée

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1 

Demande canonique (avec lignes vides)

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

Demande canonique hachée

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14 

Chaîne à signer

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

Clé de signature dérivée

780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453 

Signature

Votre signature sera différente, car vos informations d’identification de clé d’accès de sécurité ne sont pas les mêmes, mais son format sera comme suit :

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a

Charge utile signée

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

Traitement des erreurs

Chaque réponse envoyée à partir de la passerelle de service Web contient un élément Status associé qui décrit le statut d’exécution de l’opération concernée. Il y a trois valeurs d’état SUCCESS, FAILURE et RESEND. Reportez-vous à la section Traitement des erreurs pour obtenir des conseils, en particulier pour le traitement des RESEND avec la logique de nouvelle tentative.

Dépannage de votre code de signature

Vérifiez les erreurs de codage courantes suivantes à la section Exemples de dérivation d’une clé de signature pour Signature Version 4.

Les erreurs de codage courantes sont les suivantes :

• Échanger par inadvertance la clé et les données lors du calcul des clés intermédiaires. Le résultat du calcul de l’étape précédente est la clé, et non les données. Lisez attentivement la documentation de vos primitives cryptographiques pour vous assurer que vous placez les paramètres dans l’ordre approprié.
• Oublier d’ajouter la chaîne AWS comme préfixe devant la clé lors de la première étape. Il est possible d’implémenter la dérivation de clé en utilisant une boucle For ou un itérateur. N’oubliez pas alors d’inclure la chaîne AWS lors de la première itération.
• Oublier d’utiliser l’option asBytes pour la fonction JavaScript HMAC.Crypto. Si vous n’utilisez pas l’option asBytes, l’implémentation HMAC effectuera un encodage hexadécimal supplémentaire par défaut.
• Assurez-vous que la chaîne de requête de votre demande est correctement triée et codée, que les noms d’en-tête ont été convertis en minuscules et que les en-têtes ont été triés par code de caractère. Consultez la section Créer une demande canonique pour Signature Version 4.
• Pour les requêtes de corps JSON, uniquement content_type défini sur application/json réussira.

Transmission sécurisée des données

Les points de terminaison de l’API Incentives sont ouverts UNIQUEMENT via un port sécurisé (HTTPS) et tout le trafic sur ce canal est sécurisé à l’aide du protocole SSL/TLS 1.2. Ce protocole standard chiffre les données des chèques-cadeaux pendant le transfert. Vous devez fournir vos propres mécanismes sécurisés au sein de vos systèmes pour empêcher l’accès non autorisé aux clés de chiffrement utilisées par le protocole SSL/TLS 1.2.

Important : les demandes API doivent utiliser TLS 1.2 (ou version ultérieure).

Modifications de la réponse de l’API

Les réponses des points de terminaison de l’API Incentives incluent souvent des informations au format d’échange de données XML ou JSON. De nouveaux attributs pourront prochainement être ajoutés à ces réponses et certains éléments peuvent apparaître dans un ordre différent. Votre code doit gérer normalement les prochaines modifications des corps de réponse au format XML ou JSON à l’aide d’un analyseur XML ou JSON. Par exemple, XPath analyse les valeurs du contenu XML à l’aide d’une syntaxe d’expression. Une bibliothèque d’analyseurs est plus fiable lorsque le schéma d’un corps de réponse XML ou JSON change ou évolue.

Portail API Incentives

Dans le portail de API Incentives, vous pouvez :

• Afficher le solde du compte, les dépenses quotidiennes moyennes (au cours des 14 derniers jours), les jours restants (en fonction des dépenses moyennes) et les alertes
• Afficher l’activité détaillée des transactions, dans le navigateur ou sous forme de téléchargement
• Définir des alertes de montant de solde faible
• Informer Amazon que vous avez effectué un paiement
• (Administrateurs uniquement) Créer des clés d’accès et contrôler les clés existantes

Traitement des clés

Les clés d’accès sont des informations d’identification que vous utilisez pour signer vos demandes de programmation sur n’importe quel point de terminaison de l’API Incentives. Comme un nom d’utilisateur et un mot de passe, vous devez utiliser l’ID de clé d’accès et la clé d’accès secrète ensemble pour authentifier toutes vos demandes.

Un compte partenaire disposant de droits d’administrateur peut accéder à de nouvelles clés d’accès et contrôler les clés existantes à partir du portail API Incentives, sur la page API security credentials . (Un compte partenaire qui ne dispose pas de droits d’administrateur ne peut pas voir cette page. Vous pouvez solliciter un accès d’administrateur de compte en nous envoyant un e-mail à incentives-api@amazon.com.)

Sécurité des informations d’identification

Les clés d’accès et les clés secrètes fournies sur la page API security credentials doit être protégée contre tout accès non autorisé et toute libération accidentelle. Cela s’applique aux informations d’identification des environnements de production et sandbox. La sécurité de votre système et de vos fonds repose sur la gestion sécurisée de ces données secrètes. Ne partagez pas vos clés.

Rotation des clés

La modification régulière des clés d’accès est une bonne pratique de sécurité bien connue qui réduit l’impact commercial de toute clé compromise. Par souci de sécurité, nous vous recommandons d’effectuer régulièrement une rotation (modification) de vos clés d’accès. La mise en place d’un processus permet également de vérifier les étapes opérationnelles de rotation des clés, de sorte que ces modifications s’effectuent de manière fluide pour votre organisation.

Vous devez changer vos clés d’accès au moins une fois tous les 180 jours (6 mois). Vous recevrez un e-mail de rappel 30 jours avant la date prévue de rotation des clés. Si vous avez des questions, veuillez contacter votre responsable de compte ou incentives-api@amazon.com.

Pour effectuer la rotation des clés d’accès, procédez comme suit :

1. Dans le portail API Incentives, cliquez sur API security credentials.
2. Cliquez sur Create new access key.
3. Mettez à jour toutes vos applications pour utiliser la nouvelle clé d’accès.
4. Vérifiez que toutes les demandes d’opérations de l’API Incentives fonctionnent à l’aide des valeurs de la nouvelle clé.
5. Pour la clé d’origine, cliquez sur Deactive.
6. Vérifiez de nouveau que toutes les demandes d’opérations de l’API Incentives fonctionnent à l’aide des valeurs de la nouvelle clé. Attention ! Une fois qu’une clé d’accès est supprimée, elle ne peut pas être récupérée.
7. Pour la clé d’origine, cliquez sur Delete.

La nouvelle clé est maintenant en cours d’utilisation, et la clé d’origine est inactive et ne peut pas être réutilisée.

Instructions sur le stockage des données

Cette section décrit certaines pratiques exemplaires pour le traitement CreateGiftCard des résultats, en particulier gcClaimCode .

Consultez également les exigences en matière de sécurité des informations contenues dans les conditions d’achat et de distribution des cartes-cadeaux d’entreprise Amazon, y compris les meilleures pratiques de sécurité énoncées dans les politiques relatives aux cartes-cadeaux d’entreprise dans les conditions d’utilisation de l’API Amazon Incentives disponibles à l’ adresse https://www.amazon.com/gp/help/customer/display.html?nodeId=202120960.

Instructions relatives à la demande et au stockage des codes chèques-cadeaux renvoyés à la suite d’un appel réussi à CreateGiftCard :

• Votre code client génère une valeur unique creationRequestId pour chaque nouvel appel vers l’opération CreateGiftCard .
• Votre code client doit stocker les valeurs creationRequestId, amount, et currencyCode utilisées dans chaque requête.
• Amazon stocke tous les gcClaimCode. Une fois que vous avez généré un code chèque-cadeau, votre code peut récupérer le même code de demande de chèque-cadeau en envoyant une nouvelle demande à CreateGiftCard en utilisant les mêmes valeurs de code creationRequestId, amount, et currency valeurs de code. Cela peut être une alternative plus sûre au stockage des codes de demande de chèques-cadeaux dans votre base de données.
• Vous ne devriez pas stocker ces codes. Si votre code conserve temporairement les codes de demande de chèques-cadeaux, ces valeurs doivent être détruites après avoir fourni le code au client. (Consultez la section Sécurité.)
• Si vous devez annuler un code de demande de chèque-cadeau, votre code doit appeler CancelGiftCard dans les 15 minutes suivant la création du code.

Taux limites

L’API Incentives limitera ou refusera les demandes entrantes afin d’éviter toute utilisation abusive du système. Le taux de demande ne peut pas dépasser 10 demandes par seconde, tous types de transactions inclus.

Lorsque les demandes de votre code dépassent un taux limite, votre demande échoue et une exception ThrottlingException est renvoyée :

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

Traitement des erreurs

Chaque réponse envoyée à partir de la passerelle AGCOD contient un élément Status associé qui décrit le statut d’exécution de l’opération concernée. Il existe trois valeurs statusCode  : SUCCESS, FAILURE, et RESEND.

SUCCESS

Une réponse d’opération comprend une valeur statusCode de SUCCESS lorsque l’opération est réussie.

FAILURE

Une réponse d’opération comprend une valeur statusCode de FAILURE lorsque la demande ne peut pas être honorée par l’API Incentives. Cette réponse de statut peut inclure des données de demande non valides ou une erreur de logique métier qui doit être examinée par le partenaire. L’en-tête errorCode sera renseigné dans de tels cas pour fournir des détails supplémentaires sur l’erreur.

RESEND

Une réponse d’opération comprend une valeur statusCode de RESEND et une erreur F400 lorsqu’il y a une défaillance système temporaire qui peut probablement être résolue en essayant à nouveau la demande. Il est important que votre code fournisse une logique de nouvelle tentative, car une erreur F400 correspond à un « état inconnu » qui peut entraîner des frais sur votre compte. L’erreur RESEND ne doit pas être interprétée comme un échec.

Remarque : les étapes suivantes illustrent une stratégie d’interruption pour un appel à ActivateGiftCard/DeactivateGiftCard. Votre code doit également utiliser cette stratégie d’interruption pour les appels à CreateGiftCard/CancelGiftCard et à LoadAmazonBalance/VoidAmazonBalanceLoad.

1. Lorsque votre demande renvoie un message d’erreur F400, si vous pouvez simplement relancer la même opération ActivateGiftCard, réessayez simplement cette opération. Si vous ne pouvez pas effectuer de nouvelle tentative, passez à l’étape 2.
2. Envoyez une opération DeactivateGiftCard en utilisant la même valeur *requestId.
3. Si l’appel à DeactivateGiftCard renvoie SUCCESS, appelez de nouveau ActivateGiftCard en utilisant une nouvelle valeur *requestId.
4. Si l’appel à DeactivateGiftCard échoue, attentez une seconde avant d’envoyer de nouveau la même demande DeactivateGiftCard.
5. Si aucune demande DeactivateGiftCard ne réussit au bout de 10 secondes, augmentez le délai en utilisant un schéma d’interruption exponentielle.
6. Après 24 heures, stoppez toute nouvelle tentative et envoyez un e-mail à Amazon contenant les détails des opérations ayant échoué.

Codes d’erreur

Recherchez une liste des codes d’erreur de production et de simulation dans Erreurs et erreurs simulées.

Contacter le support technique d’Amazon (nécessite un contrat actif)

Tout au long du processus de développement et d’intégration, vous pouvez adresser vos questions techniques à Amazon.

Veuillez noter que si vous ne disposez pas d’un contrat actif et d’un accès à l’environnement sandbox, les développeurs qui surveillent cet alias ne pourront probablement pas vous identifier. Contactez votre responsable de compte pour qu’il vous indique la procédure à suivre pour obtenir un accès à l’environnement sandbox.

N’oubliez pas d’inclure votre ID de partenaire dans toute communication avec nos développeurs afin qu’ils puissent facilement identifier votre compte. Dans chaque communication, veuillez fournir autant d’informations que possible :

• Demande et réponse complètes de votre appel à l’API Incentives
• URL du point de terminaison utilisée (y compris l’URL du serveur) pour effectuer la demande
• Valeur StringToSign utilisée dans la demande, si elle n’est pas déjà incluse dans les informations ci-dessus sur la demande et la réponse
• Signature correspondant à la valeur StringToSign utilisée, si elle n’est pas déjà incluse dans les informations ci-dessus sur la demande et la réponse
• Heure approximative de votre demande (avec fuseau horaire configuré sur la machine émettant la demande ci-dessus)
• Langage de programmation utilisé
• Tout changement récent (à la fois de programmation et/ou d’infrastructure) de votre côté
• Capture d’écran de l’erreur

Informations légales

En intégrant et en utilisant l’API Incentives, vous (en votre nom ou au nom de l’entreprise que vous représentez) acceptez d’être lié par les Conditions d’achat et de distribution de cartes-cadeaux d’entreprise Amazon.