Intégration

Paramètres de l'application

Les paramètres de votre application définissent les règles régissant la façon dont les récompenses sont gagnées et échangées, notamment les pourcentages de cashback, les taux de conversion des points, les seuils de remboursement et les politiques d'expiration. Ces paramètres sont configurés dans l'application Otonum Récompenses et peuvent être lus par programme via l'API.

Pour les détails des points de terminaison, consultez la Référence API.

Pourquoi lire les paramètres via l'API ?

Votre intégration doit connaître les règles du programme afin de pouvoir :

• Communiquer avec précision avec les clients, par exemple : « Vous gagnerez 5 % de cashback sur cet achat »
• Conditionner l'option d'échange correctement. Proposez l'échange uniquement quand le client est vraiment éligible ; l'offrir sous le seuil crée de la friction et des échecs.
• Afficher des avertissements d'expiration si les récompenses expirent, afin d'informer les clients avant qu'ils perdent de la valeur.

Paramètres du cashback

La configuration du cashback expose trois leviers qui affectent votre UX client :

Paramètre	Comment l'utiliser dans votre intégration
minimumRedemptionAmount	N'affichez l'option « Échanger le cashback » que lorsque le solde cashback du client atteint ou dépasse ce seuil. Tenter de créer un bon en dessous échouera.
earningCaps	Utilisez-le pour calculer et afficher l'aperçu exact de la récompense pour une transaction donnée (ex. « Gagnez jusqu'à X $ de cashback »).
expiration	Si défini affiche un avertissement d'expiration dans votre portail client, par exemple : « Votre cashback expire en fin de mois. » Si None, aucun message d'urgence n'est nécessaire.

Paramètres des points

La configuration des points pilote les calculs de conversion dans toute votre intégration :

Paramètre	Comment l'utiliser dans votre intégration
minimumPointRequiredForRedemption	Conditionez l'option « Échanger des points » derrière ce seuil. Affichez l'écart aux clients : « Il vous manque encore 80 points pour échanger. »
minimumPointRequiredCashValue	Utilisez-le comme taux de conversion pour afficher les valeurs de récompense estimées. Exemple : si minimumPointRequiredCashValue est 1,00 et minimumPointRequiredForRedemption est 100, alors 1 point = 0,01 $. Affichez les gains de points sur chaque reçu en conséquence.
expiration	Identique au cashback. Affichez des avertissements d'expiration si défini.

Quand récupérer les paramètres

Les paramètres sont stables et changent rarement. Il n'est pas nécessaire de les récupérer à chaque transaction. Un bon pattern :

1. Récupérez-les une fois au démarrage (ou quotidiennement via un job planifié)
2. Mettez en cache le résultat dans votre couche de service
3. Rafraîchissez en cas d'erreur. Si vous recevez un échec inattendu lié aux seuils, rafraîchissez le cache et réessayez une fois.

Cela garde votre intégration réactive sans appels API inutiles.

Réponse :

Code
{
  "expiration": "None",
  "minimumRedemptionAmount": 5.0,
  "earningCaps": 100.0
}

Champ	Type	Description
expiration	string	Politique d'expiration : "None", "Month1", "Month3"
minimumRedemptionAmount	number	Solde de cashback minimum requis avant un échange
earningCaps	number	Cashback maximum pouvant être gagné par transaction

Réponses d'erreur :

Statut	Signification
400	Paramètres de cashback non configurés pour cette application
401	Clé API invalide
409	Conflit. Paramètres dans un état incohérent
429	Limite de débit dépassée

---

Paramètres des points

Récupérez la configuration des points pour votre application via la route dédiée décrite dans la Référence API.

Réponse :

Code
{
  "expiration": "None",
  "minimumPointRequiredForRedemption": 100,
  "minimumPointRequiredCashValue": 1.0
}

Champ	Type	Description
expiration	string	Politique d'expiration : "None", "Month1", "Month3"
minimumPointRequiredForRedemption	integer	Solde minimum de points avant qu'un bon d'échange puisse être créé
minimumPointRequiredCashValue	number	Valeur en argent des points minimum échangeables (ex. : 100 points = 1,00 $)

Réponses d'erreur :

Statut	Signification
400	Paramètres de points non configurés pour cette application
401	Clé API invalide
409	Conflit. Paramètres dans un état incohérent
429	Limite de débit dépassée

---

Cas d'utilisation courants

Afficher les règles du programme aux clients

Utilisez les points de terminaison de paramètres au démarrage de l'application pour afficher les conditions exactes du programme. Référez-vous à la Référence API pour les routes et exemples de payload.

Mettre en cache les paramètres côté serveur

Les paramètres du programme changent rarement. Mettez-les en cache côté serveur (ex. : pendant 1 heure) pour éviter d'atteindre la limite de débit :

Code
let cacheParametres = null;
let expiration = 0;

async function getParametres() {
  if (Date.now() < expiration) return cacheParametres;
  cacheParametres = await recupererParametres();
  expiration = Date.now() + 60 * 60 * 1000; // 1 heure
  return cacheParametres;
}