Concepts

Enregistrer des activités

Vue d'ensemble

L'endpoint POST /api/v1/partner/activities enregistre une activité membre et déclenche le pipeline de traitement des récompenses. Chaque fois qu'un membre complète une transaction dans votre système, soumettez-la à Otonum pour que la plateforme évalue les campagnes actives, calcule les récompenses et mette à jour le solde du membre.

Les activités sont de quatre types — Purchase, Transfer, Visit et Review — chacun supportant un objet detail optionnel qui fournit un contexte enrichi et spécifique au type.

Pour le contrat complet de requête et réponse, référez-vous à la Référence API.

Champs principaux

Champ	Requis	Description
personalCode	Oui	Identifie le membre réalisant l'activité
type	Oui	Type d'activité : Purchase, Transfer, Visit ou Review
amount	Oui	Montant monétaire associé à l'activité (ex. : total de la transaction, montant du transfert)
reference	Oui	Votre identifiant interne unique — utilisé pour la déduplication. La même référence n'est jamais traitée deux fois
occurredAt	Non	Horodatage UTC de l'activité (ISO 8601). Par défaut, l'heure de soumission si omis
redemptionCode	Non	Code de bon à échanger dans le cadre de cette activité
redemptionAmount	Non	Montant de la remise appliquée via le bon
description	Non	Contexte libre sur l'activité
detail	Non	Objet structuré spécifique au type d'activité — voir ci-dessous

Le champ detail

La propriété detail accepte un objet structuré dont la forme dépend du champ type. Elle est optionnelle dans tous les cas mais fortement recommandée — les données de detail alimentent les analyses produit, la segmentation et les règles de campagne avancées dans Otonum.

---

Purchase

Utilisez PurchaseDetails quand type est Purchase.

Propriété	Type	Requis	Contraintes	Description
channel	PurchaseChannel	Oui	—	Canal de vente : Instore, Online, USSD ou Whatsapp
items	PurchaseItem[]	Non	Max 500 articles	Liste des articles achetés pour les analyses produit
terminalId	string	Non	Max 50 caractères	Identifiant de la caisse ou du terminal de paiement

Champs de PurchaseItem :

Propriété	Type	Requis	Contraintes	Description
key	string	Non	—	Clé unique / SKU de l'article
name	string	Oui	1–200 cars	Nom ou description de l'article
quantity	integer	Oui	Min 1	Quantité commandée
unitPrice	number	Oui	Min 0	Prix unitaire

Erreurs de validation

Champ	Règle	Code d'erreur
channel	Requis, valeur d'énum valide	PURCHASE_CHANNEL_INVALID
terminalId	Max 50 caractères	PURCHASE_TERMINAL_ID_TOO_LONG
items	Max 500 entrées	PURCHASE_ITEMS_TOO_MANY
name	Non vide	PURCHASE_ITEM_NAME_REQUIRED
quantity	Minimum 1	PURCHASE_ITEM_QUANTITY_INVALID
unitPrice	Minimum 0	PURCHASE_ITEM_PRICE_NEGATIVE

Code
{
  "personalCode": "ABC123",
  "type": "Purchase",
  "amount": 45.0,
  "reference": "COMMANDE-9981",
  "detail": {
    "channel": "Instore",
    "terminalId": "POS-04",
    "items": [
      {
        "key": "REF-001",
        "name": "Café Mélange 250g",
        "quantity": 2,
        "unitPrice": 12.5
      },
      {
        "key": "REF-042",
        "name": "Tasse réutilisable",
        "quantity": 1,
        "unitPrice": 20.0
      }
    ]
  }
}

---

Transfer

Utilisez TransferDetails quand type est Transfer.

Propriété	Type	Requis	Contraintes	Description
originCountry	string	Oui	Exactement 2 cars, ISO 3166-1	Code pays ISO 3166-1 alpha-2 d'origine (ex. : CI, SN, ML)
destinationCountry	string	Oui	Exactement 2 cars, ISO 3166-1	Code pays ISO 3166-1 alpha-2 de destination
operator	string	Non	—	Opérateur banque ou Mobile Money (ex. : Orange Money, Wave, MTN MoMo)
recipientPhone	string	Non	Format tél. international	Numéro du destinataire — anonymisé dans les analyses publiques
fees	number	Non	Min 0	Frais de transfert facturés au membre
feesCurrency	string	Non	3 lettres majuscules ISO 4217	Code devise ISO 4217 pour les frais (ex. : XOF, GHS)

Erreurs de validation

Champ	Règle	Code d'erreur
originCountry	Requis	TRANSFER_ORIGIN_COUNTRY_REQUIRED
originCountry	Code ISO 3166-1 à 2 lettres	TRANSFER_ORIGIN_COUNTRY_INVALID
destinationCountry	Requis	TRANSFER_DESTINATION_COUNTRY_REQUIRED
destinationCountry	Code ISO 3166-1 à 2 lettres	TRANSFER_DESTINATION_COUNTRY_INVALID
recipientPhone	Format international (+?[1-9]\d{6,14})	TRANSFER_RECIPIENT_PHONE_INVALID
fees	Minimum 0	TRANSFER_FEES_NEGATIVE
feesCurrency	Exactement 3 lettres majuscules (ISO 4217)	TRANSFER_FEES_CURRENCY_INVALID

Code
{
  "personalCode": "ABC123",
  "type": "Transfer",
  "amount": 50000.0,
  "reference": "TXN-77214",
  "detail": {
    "originCountry": "CI",
    "destinationCountry": "SN",
    "operator": "Wave",
    "fees": 500.0,
    "feesCurrency": "XOF"
  }
}

---

Visit

Utilisez VisitDetails quand type est Visit.

Propriété	Type	Requis	Contraintes	Description
source	VisitSource	Oui	—	Source du check-in : QrCode, Nfc, Manual ou App
locationId	string	Non	—	Identifiant du site — utile pour les programmes de fidélité multi-sites
locationName	string	Non	Max 200 caractères	Nom d'affichage du site visité

Erreurs de validation

Champ	Règle	Code d'erreur
source	Requis	VISIT_SOURCE_REQUIRED
source	Doit être QrCode, Nfc, Manual ou App	VISIT_SOURCE_INVALID
locationName	Max 200 caractères	VISIT_LOCATION_NAME_TOO_LONG

Code
{
  "personalCode": "ABC123",
  "type": "Visit",
  "amount": 0,
  "reference": "VISITE-20260602-0041",
  "detail": {
    "source": "QrCode",
    "locationId": "STORE-12",
    "locationName": "Abidjan - Plateau"
  }
}

---

Review

Utilisez ReviewDetails quand type est Review.

Propriété	Type	Requis	Contraintes	Description
rating	integer	Oui	1–5	Note sur une échelle de 1 à 5
platform	string	Non	Max 50 caractères	Plateforme de soumission de l'avis (ex. : Google, inapp, WhatsApp)
hasComment	boolean	Non	—	true si l'avis contient un commentaire écrit. Le texte n'est pas conservé (RGPD)

Erreurs de validation

Champ	Règle	Code d'erreur
platform	Max 50 caractères	REVIEW_PLATFORM_TOO_LONG

Code
{
  "personalCode": "ABC123",
  "type": "Review",
  "amount": 0,
  "reference": "AVIS-88102",
  "detail": {
    "rating": 5,
    "platform": "Google",
    "hasComment": true
  }
}

Traitement asynchrone

L'endpoint d'activité retourne immédiatement un taskId. Otonum traite les récompenses de façon asynchrone :

1. Otonum évalue l'activité par rapport à toutes les campagnes actives pour l'application
2. Les règles sont évaluées pour chaque campagne éligible
3. Toutes les campagnes correspondantes accordent leurs récompenses (elles s'accumulent)
4. Tout bon échangé est marqué comme consommé
5. Le solde du membre est mis à jour
6. Le membre est notifié selon vos paramètres de notification

Votre flux de traitement n'est jamais bloqué en attendant qu'Otonum termine. Pour la plupart des intégrations, suivre l'achèvement n'est pas nécessaire. Consultez Statut des tâches pour les cas où l'interrogation est pertinente.

Points importants

• reference est votre clé de déduplication — utilisez toujours votre identifiant interne de transaction ou de commande
• amount est requis et doit être > 0 pour Purchase et Transfer ; il doit être 0 pour Visit et Review
• detail est optionnel mais recommandé pour tous les types ; il permet un ciblage de campagne plus précis
• Une visite ou un avis sans campagne correspondante réussit quand même — aucune erreur n'est générée

Référence des codes d'erreur de validation

Code d'erreur	Message
PERSONAL_CODE_REQUIRED	Le code personnel est requis.
REFERENCE_REQUIRED	La référence est requise.
ACTIVITY_TYPE_INVALID	Type d'activité non reconnu. Valeurs acceptées : purchase, transfer, visit, review.
OCCURRED_AT_IN_FUTURE	La date de l'activité ne peut pas être dans le futur.
AMOUNT_REQUIRED	Le montant est requis pour ce type d'activité.
AMOUNT_MUST_BE_POSITIVE	Le montant doit être supérieur à zéro.
AMOUNT_NOT_APPLICABLE	Le montant n'est pas applicable pour ce type d'activité.
DETAILS_INVALID_FORMAT	Le format JSON des détails est invalide.
DETAILS_NULL	Les détails ne peuvent pas être null.
PURCHASE_CHANNEL_INVALID	Canal de vente invalide. Valeurs acceptées : InStore, Online, Ussd, WhatsApp.
PURCHASE_TERMINAL_ID_TOO_LONG	L'identifiant terminal ne peut pas dépasser 50 caractères.
PURCHASE_ITEMS_TOO_MANY	Le nombre d'articles ne peut pas dépasser 500.
PURCHASE_ITEM_NAME_REQUIRED	Le nom de l'article est requis.
PURCHASE_ITEM_QUANTITY_INVALID	La quantité doit être supérieure à zéro.
PURCHASE_ITEM_PRICE_NEGATIVE	Le prix unitaire ne peut pas être négatif.
TRANSFER_ORIGIN_COUNTRY_REQUIRED	Le pays d'origine est requis.
TRANSFER_ORIGIN_COUNTRY_INVALID	Pays d'origine invalide. Code ISO 3166-1 à 2 lettres requis (ex. : CI).
TRANSFER_DESTINATION_COUNTRY_REQUIRED	Le pays de destination est requis.
TRANSFER_DESTINATION_COUNTRY_INVALID	Pays de destination invalide. Code ISO 3166-1 à 2 lettres requis (ex. : SN).
TRANSFER_CORRIDOR_MISMATCH	Le corridor ne correspond pas aux pays d'origine et de destination.
TRANSFER_RECIPIENT_PHONE_INVALID	Format de numéro de téléphone invalide.
TRANSFER_FEES_NEGATIVE	Les frais de transfert ne peuvent pas être négatifs.
TRANSFER_FEES_CURRENCY_INVALID	Code devise des frais invalide. Format ISO 4217 à 3 lettres requis.
VISIT_SOURCE_REQUIRED	La source de visite est requise.
VISIT_SOURCE_INVALID	Source de visite invalide. Valeurs acceptées : QrCode, Nfc, Manual, App.
VISIT_LOCATION_NAME_TOO_LONG	Le nom du lieu ne peut pas dépasser 200 caractères.
REVIEW_PLATFORM_TOO_LONG	Le nom de la plateforme ne peut pas dépasser 50 caractères.

Voir aussi

• Campagnes : comment les activités déclenchent l'évaluation des campagnes
• Bon d'achat : flux d'échange
• Statut des tâches : suivi asynchrone
• Guide d'intégration : flux d'intégration de bout en bout