Intégration

Statut des tâches

Lorsque vous soumettez un achat, Otonum retourne un taskId immédiatement et traite la récompense de façon asynchrone en arrière-plan. Cette page explique pourquoi cette conception existe et comment la gérer correctement dans votre intégration.

Pour les détails du point de terminaison, consultez la Référence API.

Pourquoi un traitement asynchrone ?

Le calcul des récompenses implique l'évaluation de plusieurs campagnes actives, l'application de règles métier étagées, la mise à jour des soldes et le déclenchement de notifications, le tout indépendamment de votre flux de caisse. Rendre cela asynchrone signifie :

• Votre caisse n'est jamais bloquée en attente du calcul des récompenses
• Otonum peut gérer des volumes élevés aux heures de pointe sans affecter vos temps de réponse
• Une défaillance du traitement ne fait pas échouer l'achat. La transaction est toujours enregistrée.

Le pattern standard : ne pas interroger

Pour la grande majorité des intégrations, vous n'avez pas besoin d'interroger la complétion de la tâche. Le flux recommandé est :

1. Soumettre l'achat → recevoir le taskId
2. Confirmer la commande au membre dans votre système
3. Laisser Otonum traiter la récompense en arrière-plan
4. Otonum notifie le membre de sa récompense automatiquement

L'interrogation ajoute de la latence et de la complexité à votre flux de caisse. Ne le faites que lorsque c'est vraiment nécessaire pour votre cas d'usage.

Quand l'interrogation a du sens

Scénario	Pourquoi interroger
Affichage in-app de la récompense	Vous souhaitez afficher « Vous avez gagné 120 points ! » dans votre propre interface immédiatement après la caisse, avant que le membre ne parte
Audit de rapprochement	Votre backend audite les récompenses complétées par rapport à vos propres enregistrements de commandes selon un calendrier
Débogage	Une récompense était attendue mais n'est pas apparue sur le solde du membre

Statuts des tâches

Statut	Ce que cela signifie	Que faire
processing	En attente ou en cours d'évaluation	Attendez et réinterrogez
completed	Récompenses calculées et appliquées au solde	Affichez la confirmation si nécessaire
failed	Une erreur s'est produite	Voir ci-dessous

Gestion d'une tâche échouée

Un statut failed signifie qu'Otonum n'a pas pu traiter la récompense pour cet achat. L'achat lui-même a été enregistré, mais aucune récompense n'a été appliquée. Causes courantes :

• Une règle de campagne mal configurée
• Un redemptionCode invalide (bon déjà utilisé ou expiré)
• Un délai d'expiration de traitement interne

Ne resoumettez pas l'activité. La même reference serait de toute façon rejeté comme doublon. Contactez plutôt le support Otonum avec le taskId pour investigation et correction manuelle si nécessaire.

Paramètre de chemin :

Paramètre	Type	Requis	Description
taskId	string	Oui	L'identifiant de tâche retourné par le point de terminaison d'achat

Réponse :

Code
{
  "taskId": "987",
  "status": "completed"
}

Champ	Type	Description
taskId	string	L'identifiant unique de la tâche
status	string	Statut actuel de la tâche (voir ci-dessous)

Statuts des tâches

Statut	Description
processing	La tâche est en file d'attente ou en cours de traitement
completed	Les récompenses ont été calculées et appliquées avec succès
failed	Le traitement a échoué. Contactez le support avec l'identifiant de tâche.

Réponses d'erreur :

Statut	Signification
401	Clé API invalide
404	Aucune tâche trouvée avec l'identifiant fourni
429	Limite de débit dépassée

---

Quand consulter le statut d'une tâche

Pour la plupart des intégrations, vous n'avez pas besoin de surveiller le statut de la tâche. La soumission de l'achat confirme que le processus de récompense a démarré, et Otonum notifie directement le membre.

Consultez le statut de la tâche uniquement si votre intégration a besoin de :

• Confirmer le traitement des récompenses avant d'afficher un message « Vous avez gagné X points ! » dans votre application
• Auditer les tâches terminées à des fins de réconciliation
• Diagnostiquer un événement de traitement de récompense échoué

Exemple de surveillance

Pour un exemple de polling et le format exact de la route de statut, référez-vous à la Référence API.

Conseil : Évitez de consulter le statut plus d'une fois par seconde pour rester dans la limite de 10 requêtes/seconde.