Spécification de l'API Coupon

Vue d'ensemble

L'API Coupon de Rokt permet aux clients des publicités Rokt d'accéder et de récupérer de manière transparente des codes de coupon promotionnels pour les utiliser dans leurs campagnes. Les coupons sont gérés dans le système Rokt et peuvent être administrés lors de la conversion d'une publicité Rokt par un client.

Authentification

Contactez votre gestionnaire de compte Rokt pour créer une clé API afin d'accéder à l'API Coupon de Rokt. L'API utilise l'authentification bearer encodée en base64. Vos clés API confèrent de nombreux privilèges, veillez donc à les garder en sécurité ! Ne partagez pas vos clés API secrètes dans des zones accessibles au public telles que GitHub, le code côté client, etc.

Référence de l'API

L'API Coupon nécessite des coupons liés à un Rokt Creative ainsi qu'un ID de session Rokt pour l'administration des coupons. Les IDs de session sont requis pour garantir la distribution d'un code de coupon donné au plus une fois. Si vous n'êtes pas sûr de votre ID de compte, contactez votre gestionnaire de compte. Plus de détails peuvent être trouvés dans la section Exigences Clés.

URL de l'endpoint	http://coupon-api.rokt.com/api/v1

Requête

POST /accounts/{account_id}/creative/{creative_id}/session/{session_id}/allocate-coupon

En-têtes

Nom	Valeur	Requis	Description
Content-Type	application/json	Oui	N/A
Charset	utf-8	Oui	N/A
Authorization	Bearer base64(rokt-coupon-key:{secretValue})	Oui	En-tête d'authentification Bearer, avec la valeur d'identification étant un encodage base64 de la chaîne "rokt-coupon-key" et la valeur secrète, séparés par un deux-points

Paramètres

Nom	Requis	Type	Dans	Description
accountId	Oui	Chaîne, jusqu'à 64 caractères	Chemin	Rokt Account ID
creativeId	Oui	Long	Chemin	Identifiant interne Rokt pour la création à laquelle le client a adhéré
sessionID	Oui	Chaîne, jusqu'à 64 caractères	Chemin	ID de session Rokt, transmis dans l'URL de trafic par le partenaire

Exemple de Requête

curl -X POST http://coupon-api.rokt.com/api/v1/accounts/3284705019915440561/creative/1/session/1/allocate-coupon \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR_ENCODED_TOKEN}" \
-d '{}'

Exemple de Réponse

{
  "couponId": "67c41952-55b5-4fca-8fe8-8da4116ded3e",
  "couponCode": "COUPON-CODE-475558",
  "accountId": "3284705019915440561",
}

Gestion des Erreurs

Exception	Code HTTP	Cause	Résolution
AuthorizationHeaderMissing	401 Unauthorized	L'en-tête Authorization est manquant dans la requête.	Assurez-vous que la requête inclut un en-tête Authorization valide.
AuthenticationFailure	401 Unauthorized	Clé API invalide, jeton expiré ou identifiants incorrects.	Assurez-vous que des identifiants d'authentification valides sont fournis.
InvalidAuthorizationHeaderFormat	401 Unauthorized	Le format de l'en-tête Authorization est incorrect (par exemple, Bearer manquant ou jeton mal formé).	Assurez-vous que l'en-tête suit le format correct, par exemple Authorization:Bearer base64(rokt-coupon-key:{secretValue})
FailedToRetrieveSecrets	401 Unauthorized	Le format de l'en-tête Authorization est invalide (le jeton est incorrect ou manquant dans les secrets).	Vérifiez le format de l'en-tête Authorization.
InvalidToken	401 Unauthorized	Le jeton fourni est invalide, expiré ou révoqué.	Demandez un nouveau jeton et assurez-vous qu'il est valide avant utilisation.
FailedToValidateCouponPayload	400 Bad Request	La charge utile de la requête de coupon contient des champs invalides ou manquants.	Assurez-vous que tous les champs requis sont inclus et correctement formatés avant d'envoyer la requête.
FailedToAllocateCoupon	500 Internal Server Error	Le serveur a rencontré un problème lors de la tentative d'allocation d'un coupon.	Cette erreur est survenue en raison de problèmes avec l'API Coupon ou ses services sous-jacents. Contactez le canal de support Rokt.
NoCouponsRemaining	404 Not Found	Il n'y a plus de coupons disponibles pour cette offre.	Contactez votre gestionnaire de compte Rokt pour reconstituer la liste des coupons.

Exigences Clés

Pour récupérer des codes de coupon à partir de l'API Rokt Coupon, les paramètres suivants sont essentiels :

• ID de compte
• ID créatif
• ID de session

Alors que votre ID de compte est une valeur constante, Rokt vous fournira l'ID de session et l'ID créatif via l'URL de destination créative. Les détails sur la façon de procéder sont listés ci-dessous.

Flux de données pour l'intégration des annonceurs

1. Extraire les paramètres de l'URL de trafic : Lorsqu'un utilisateur est redirigé vers la page de l'annonceur, l'URL de trafic inclura les paramètres requis. Par exemple, le créatif peut avoir l'URL de trafic suivante : https://samplewebsite.com/download?sessionid=abcdef123456&creativeid=67890. L'ID de session est un UUID, tandis que l'ID créatif est un bigint.

2. Stocker les paramètres dans le stockage local : Les annonceurs doivent analyser l'URL et stocker l'ID de session et l'ID créatif de manière sécurisée dans le stockage local du navigateur, ou par une méthode alternative de votre choix. Voir l'exemple de code suivant pour l'extraction et le stockage :

const urlParams = new URLSearchParams(window.location.search);
const sessionid = urlParams.get('sessionid');
const creativeid = urlParams.get('creativeid');

if (sessionid && creativeid) {
    localStorage.setItem('sessionid', sessionid);
    localStorage.setItem('creativeid', creativeid);
}

3. Passer les paramètres stockés à l'API Rokt Coupon : Lors de l'appel à l'API Rokt Coupon, récupérez les paramètres stockés à partir du stockage local et incluez-les dans le corps de la requête API. Voir l'exemple de code suivant pour appeler l'API :

remarque

L'ID de compte, le jeton d'authentification et d'autres informations sensibles ne doivent pas être stockés directement dans le code. Cet exemple est uniquement à des fins de démonstration.

// Extraire les paramètres de l'URL de trafic
const urlParams = new URLSearchParams(window.location.search);
const sessionid = urlParams.get('sessionid');
const creativeid = urlParams.get('creativeid');
const accountid = 'YOUR_ACCOUNT_ID'; // Remplacez par votre ID de compte Rokt

// Stocker les paramètres dans le stockage local
if (sessionid && creativeid) {
    localStorage.setItem('sessionid', sessionid);
    localStorage.setItem('creativeid', creativeid);
}

// Récupérer et passer les paramètres stockés dans l'appel API
const storedSessionId = localStorage.getItem('sessionid');
const storedCreativeId = localStorage.getItem('creativeid');

if (storedSessionId && storedCreativeId && accountid) {
```javascript
// Construire dynamiquement l'URL de l'API avec des paramètres dans le chemin
const apiUrl = `http://coupon-api.stage.rokt.com/api/v1/accounts/${accountid}/creative/${storedCreativeId}/session/${storedSessionId}/allocate-coupon`;

fetch(apiUrl, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${authToken}` // Remplacez authToken par votre clé API
    },
    body: JSON.stringify({}) // Corps JSON vide comme requis
})
.then(response => {
    if (!response.ok) {
        throw new Error(`Erreur HTTP ! statut : ${response.status}`);
    }
    return response.json();
})
.then(data => {
    console.log('Code du coupon :', data.code);
})
.catch(error => console.error('Erreur :', error));
} else {
    console.error('Les paramètres requis sont manquants.');
}