Concepts fondamentaux
Comprendre ces concepts vous aidera à concevoir une intégration Otonum fiable et à prendre de meilleures décisions sur la manière de présenter l'expérience de fidélisation à vos clients.
Pour les détails techniques de chaque point de terminaison, consultez la Référence API.
Identité client
Dans Otonum, chaque personne qui participe à votre programme de fidélité est représentée par un enregistrement membre lié à son adresse courriel et auquel est attribué un code personnel.
Le code personnel
Un code personnel est un identifiant court et lisible (ex. JEAN2026) que le membre présente à la caisse, sur une carte de fidélité, dans une application, ou saisi manuellement. C'est la clé primaire pour toutes les opérations de récompense. La soumission d'achats, la récupération de soldes et la création de bons référencent toutes ce code.
Les codes personnels sont générés par Otonum lors de l'inscription et peuvent être récupérés par courriel à tout moment.
Modes d'inscription
| Mode | Quand l'utiliser |
|---|---|
| Individuel | Inscription en temps réel, quand un membre s'inscrit, opte au comptoir, ou crée un compte dans votre application |
| En lot | Migration groupée, pour importer une base de membres existante dans Otonum |
Les champs requis incluent le courriel, le prénom, le nom et la langue (utilisée pour envoyer les notifications dans la langue du membre). Les champs optionnels comme la date d'anniversaire peuvent déclencher des campagnes de jalons.
Solde client
Le solde d'un membre représente les récompenses disponibles à l'échange. Otonum le détaille en quatre champs pour vous donner une visibilité complète :
| Champ | Description |
|---|---|
balance | Actuellement disponible pour l'échange |
totalEarned | Montant cumulé gagné depuis l'inscription |
totalRedeemed | Montant cumulé appliqué aux achats |
totalReserved | Montant bloqué dans un bon actif, en attente d'utilisation |
Le montant totalReserved est temporairement indisponible. Il est engagé dans un bon qui sera soit utilisé lors de l'échange, soit automatiquement retourné au balance si le bon expire sans être utilisé après 30 jours.
Programmes de fidélité
Otonum supporte deux mécanismes de récompense fondamentaux. Votre programme est configuré pour en utiliser un ou les deux selon les paramètres de votre compte.
Points
Les membres gagnent des points sur les achats admissibles selon les règles de vos campagnes. Les points s'accumulent dans leur compte et peuvent ensuite être échangés contre un bon de remboursement.
Les points sont appropriés lorsque vous voulez que vos membres :
- Construisent une valeur perçue dans le temps, car l'accumulation crée de l'engagement et une raison de revenir
- Ressentent la satisfaction d'un objectif, par exemple : « encore X points avant ma récompense »
- Participent à des campagnes de jalons, comme les bonus d'anniversaire, les week-ends à points doubles et les niveaux VIP
Le taux de conversion (points → valeur monétaire) est défini dans vos paramètres du programme.
Cashback
Les membres reçoivent un crédit cashback, c'est-à-dire un pourcentage direct de la transaction retourné à leur solde après chaque achat admissible.
Le cashback fonctionne bien lorsque :
- Vous souhaitez offrir une valeur immédiate et tangible, car les membres voient un équivalent en argent réel et non des points abstraits
- Votre marché répond bien aux économies directes, ce qui est courant dans les épiceries, les stations-service et les achats quotidiens
- Vous êtes dans un environnement concurrentiel où les récompenses instantanées différencient votre offre
Le cashback s'accumule dans le solde du membre jusqu'à ce qu'il atteigne le seuil de remboursement minimum, à partir duquel un bon peut être créé.
Bons d'achat
Un bon d'achat est un instrument de remise à usage unique généré à partir du solde accumulé d'un membre. Les bons sont le mécanisme d'échange dans Otonum. Ils convertissent la valeur de récompense stockée en une remise appliquée à la caisse.
Cycle de vie d'un bon
-
Solde accumulé : le membre gagne des points ou du cashback sur plusieurs achats.
-
Bon créé : le membre demande un échange. Otonum crée un bon et déplace le montant correspondant du
balancevers letotalReserved. -
Bon validé à la caisse : votre système appelle l'API de validation pour confirmer que le bon est toujours actif et obtenir la remise définitive en espèces.
-
Achat soumis avec l'échange : votre système soumet l'achat en incluant la référence du bon. Otonum marque le bon comme utilisé et met à jour le solde.
-
Expiration (si non utilisé) : si le bon n'est pas utilisé dans les 30 jours, il expire automatiquement et le montant réservé est retourné au
balance.
Quand créer un bon
Créez les bons à la demande à la caisse, quand le membre choisit activement d'échanger. Évitez de créer des bons à l'avance (ex. lors de l'inscription ou selon un calendrier), car cela bloque inutilement le solde du membre pendant 30 jours et peut empêcher d'autres échanges.
Note : 🧪 Sandbox La création et la validation de bons retournent
403 Forbiddendans l'environnement sandbox. Prévoyez de simuler ces réponses dans votre suite de tests.
L'événement achat
Un achat est l'événement central dans toute intégration Otonum. Chaque fois qu'un membre complète une transaction, vous la soumettez à Otonum pour que la plateforme puisse :
- Évaluer l'achat par rapport à toutes vos campagnes actives
- Calculer la récompense applicable (points, cashback, ou bon déclenché par une campagne)
- Marquer tout bon échangé comme utilisé
- Mettre à jour le solde du membre
- Notifier le membre selon vos paramètres de notification
Champs importants
| Champ | Utilité |
|---|---|
personalCode | Identifie le client |
personalCode | Identifie le membre |
amount | Montant réellement payé par le membre après application de la remise |
reference | Identifiant interne de la commande, utilisé pour la déduplication. La même référence ne sera jamais traitée deux fois. |
redemptionAmount | La remise du bon appliquée (le cas échéant) |
redemptionCode | Le code du bon (le cas échéant), qui le marque comme utilisé |
Le calcul des récompenses est basé sur amount (ce que le membre a réellement payé).
Traitement asynchrone
Le calcul des récompenses se produit après votre réception de la réponse API. Le point de terminaison d'achat retourne immédiatement un taskId. Votre caisse n'est jamais bloquée en attendant qu'Otonum termine. Consultez Statut des tâches pour savoir quand suivre l'achèvement.
Transactions
Otonum conserve un historique complet et paginé de tous les événements de fidélité pour chaque membre : achats, gains de récompenses, échanges et ajustements de solde. Cet historique est utile pour :
- Portails membres : afficher une chronologie de l'historique points/cashback
- Rapprochement : auditer l'émission de récompenses par rapport à vos propres enregistrements de commandes
- Support : diagnostiquer des récompenses manquantes ou des soldes contestés
Tous les enregistrements de transactions sont générés automatiquement par Otonum au fil des événements. L'historique est en lecture seule depuis l'API.
Pour éviter les incohérences entre la documentation conceptuelle et les routes réelles, cette page ne duplique pas les URLs d'API. Référez-vous à la Référence API pour les endpoints, les paramètres et les exemples à jour.
Campagnes
Une campagne définit les règles régissant le calcul des récompenses pour une période spécifique, un segment client ou une catégorie de produits. Les campagnes sont configurées dans l'application Otonum Business et ne nécessitent pas d'appels API pour leur gestion.
Paramètres clés d'une campagne :
| Paramètre | Description |
|---|---|
| Type de récompense | Points, remise en argent ou bon d'achat |
| Taux de gain | Montant de récompense par dollar dépensé |
| Éligibilité | Quels clients ou catégories de produits sont admissibles |
| Plage de dates | Date de début et de fin de la campagne |
| Règles d'empilement | Si plusieurs campagnes peuvent s'appliquer simultanément |
Format des requêtes et réponses
Toutes les requêtes et réponses API utilisent le format JSON. Définissez toujours l'en-tête Content-Type sur les requêtes POST et PUT :
Code
Les dates sont retournées au format ISO 8601 (UTC) :
Code
Les montants monétaires sont représentés sous forme de nombres décimaux avec jusqu'à 2 décimales, dans la devise configurée pour votre compte.