Guide d'intégration
Ce guide explique comment connecter vos systèmes existants (POS, e-commerce ou application mobile) à la plateforme de fidélité Otonum. Il couvre le cycle de caisse complet, de l'identification du membre à la confirmation de la récompense.
Pour le format exact des requêtes et réponses de chaque appel, consultez la Référence API.
Aperçu de l'architecture
Votre système communique avec l'API Otonum au nom de vos membres. Otonum gère toute la logique de récompense côté serveur. Votre système fournit l'identité du membre et les données de transaction, puis Otonum détermine et applique les récompenses.
Flux étape par étape
Étape 1 : Identifier le membre
À la caisse, collectez le code personnel du membre (via carte de fidélité, scan de l'application ou saisie manuelle). Si vous n'avez que son courriel, vous pouvez rechercher son code via la route dédiée.
Une fois que vous avez le code, récupérez le solde du membre et affichez les récompenses disponibles en amont. Cette approche augmente les taux d'échange et offre une meilleure expérience que d'annoncer les options après la caisse.
Étape 2 : Échange (optionnel)
Si le membre souhaite utiliser ses récompenses, le flux est identique, qu'il échange des points ou du cashback :
- Créer un bon à partir du solde du membre, en spécifiant le type de programme de fidélité (
PointsouCashback) et le montant à échanger. - Valider le bon à la caisse pour confirmer qu'il est toujours actif et obtenir la valeur définitive en espèces
cashValueà appliquer.
L'étape de validation est importante car le bon pourrait avoir été créé sur un autre canal. Validez toujours avant d'appliquer la remise.
Conservez la reference du bon. Vous en aurez besoin lors de la soumission de l'achat pour le marquer comme utilisé.
Étape 3 : Appliquer la remise dans votre système
Otonum vous indique combien réduire. C'est votre système qui applique la remise. Otonum ne modifie jamais les prix et n'interagit pas avec votre processeur de paiement.
Calculez les deux montants que vous soumettrez :
| Champ | Formule |
|---|---|
amount | Montant net de la transaction — prix original moins toute remise appliquée |
redemptionAmount | La cashValue du bon |
amount est la valeur utilisée pour le calcul des récompenses.
Étape 4 : Soumettre l'activité
Après finalisation de la transaction dans votre système, envoyez-la à Otonum. Deux champs sont critiques :
reference: Utilisez votre identifiant de commande interne. C'est la clé de déduplication d'Otonum. La même référence ne sera jamais traitée deux fois. Cela protège vos membres contre les doubles récompenses lors de nouvelles tentatives réseau.redemptionCode: Incluez le code du bon si un échange a eu lieu. Cela marque le bon comme utilisé.
Le point de terminaison d'activité retourne un taskId immédiatement. Le traitement des récompenses démarre en arrière-plan.
Étape 5 : Traitement des récompenses
Après réception de votre soumission, Otonum :
- Évalue l'activité par rapport à toutes vos campagnes actives
- Calcule les points ou le cashback gagnés selon les règles de campagne
- Marque le bon échangé comme utilisé (le cas échéant)
- Met à jour le solde du membre
- Notifie le membre (courriel ou push, selon vos paramètres)
Cela est asynchrone. Votre caisse retourne avant que le traitement soit terminé. Consultez Statut des tâches pour savoir quand il est nécessaire de suivre l'achèvement.
Pour éviter tout décalage avec les routes effectives, cette page ne duplique pas d'exemples d'URL API. Référez-vous à la Référence API pour les endpoints, paramètres et exemples de payload à jour.
Patterns d'intégration
POS (en magasin)
- Ajoutez une étape fidélité avant le paiement : demandez le code personnel, affichez le solde, proposez l'échange
- Après le paiement, soumettez l'achat à Otonum en arrière-plan. Ne bloquez pas le POS sur l'appel API.
- Affichez le code personnel sous forme de QR code ou code-barres dans votre application de carte de fidélité pour un scan rapide
E-commerce
- Ajoutez un champ de code de fidélité à la caisse (aux côtés des codes promo)
- Quand le code est saisi, récupérez le solde et affichez les récompenses disponibles en temps réel
- Après confirmation de la commande, déclenchez la soumission d'achat Otonum depuis votre webhook de commande ou événement post-paiement
Application mobile
- Affichez le code personnel sous forme de QR/code-barres sur l'écran d'accueil de l'app pour un scan facile en magasin
- Montrez un aperçu du solde et l'historique récent des récompenses sur l'écran de profil
- Soumettez toujours les achats depuis votre serveur backend, jamais directement depuis l'application mobile (la clé API doit rester côté serveur)
Décisions clés pour votre intégration
| Décision | Recommandation |
|---|---|
| Quand afficher le solde | Avant la caisse, pas après. Cette approche stimule l'échange. |
| Quand interroger le statut de tâche | Seulement si votre interface a besoin d'afficher immédiatement les récompenses gagnées |
| Annulation de bon | Annulez si le client change d'avis avant la soumission de l'achat |
| Prévention des doublons | Utilisez toujours l'ID de commande comme reference |
| Gestion des notifications | Otonum envoie des notifications par défaut. Décidez si votre système doit aussi en envoyer et désactivez l'un des deux canaux pour éviter les doublons. |
Idempotence
Pour éviter le traitement en double des récompenses lors de nouvelles tentatives réseau, fournissez toujours un reference unique par activité.
Webhooks (prochainement)
Otonum prévoit des webhooks pour envoyer des notifications en temps réel à votre système (récompense gagnée, émission de bon, évolution de statut). En attendant, suivez le Journal des modifications pour les annonces de disponibilité.