Ressources

Bonnes pratiques

Suivez ces directives pour construire une intégration Otonum sécurisée, résiliente et maintenable.

Sécurité

Protégez votre clé API

Votre clé API donne accès complet aux données de votre programme de fidélité. Traitez-la comme un mot de passe :

• Ne jamais l'inclure dans du JavaScript côté client ou dans le code d'une application mobile
• Ne jamais la valider dans un système de contrôle de version (utilisez .gitignore pour les fichiers .env)
• Stockez-la dans des variables d'environnement ou un gestionnaire de secrets (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
• Faites une rotation des clés régulièrement et immédiatement en cas de fuite suspectée

Code
# Bien. clé chargée depuis l'environnement
x-api-secret: $OTONUM_API_KEY

# Mal. clé codée en dur
x-api-secret: sk_live_abc123xyz

Toujours utiliser HTTPS

Tous les points de terminaison de l'API Otonum sont servis via HTTPS. N'appelez jamais l'API en HTTP. les requêtes seront rejetées.

Effectuez les appels API depuis votre backend

N'appelez jamais l'API Otonum directement depuis du JavaScript navigateur ou du code d'application mobile natif. Routez tous les appels via votre serveur pour garder votre clé API confidentielle.

---

Limitation de débit

Otonum applique une limite de 10 requêtes par seconde par clé API. Si cette limite est dépassée, l'API retourne une réponse 429 Too Many Requests :

La limite se réinitialise après 2 secondes. Implémentez un backoff exponentiel lors du traitement des réponses 429 :

Code
async function appelAvecReprise(fn, tentatives = 3) {
  for (let i = 0; i < tentatives; i++) {
    try {
      return await fn();
    } catch (erreur) {
      if (erreur.status === 429 && i < tentatives - 1) {
        const delai = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise((resolve) => setTimeout(resolve, delai));
      } else {
        throw erreur;
      }
    }
  }
}

---

Gestion des erreurs

Vérifiez toujours le code de statut HTTP et analysez le corps de la réponse d'erreur. Otonum utilise les codes de statut HTTP standard :

Statut	Signification	Action
200	Succès	Traiter la réponse
400	Mauvaise requête	Corriger le contenu de la requête
401	Non autorisé	Vérifier votre clé API
403	Interdit	Permissions insuffisantes
404	Non trouvé	Le client ou la ressource n'existe pas
409	Conflit	Identifiant de référence en double
422	Entité non traitable	Erreur de validation dans le corps de la requête
429	Trop de requêtes	Réessayer avec backoff
500	Erreur serveur	Réessayer une fois ; contacter le support si persistant

---

Versionnement de l'API

Spécifiez toujours la version de l'API dans vos requêtes. La version stable actuelle est v1 :

Pour les routes exactes et leur version courante, référez-vous systématiquement à la Référence API.

Lorsqu'une nouvelle version est publiée, la version précédente reste disponible pendant une période de dépréciation. Abonnez-vous au Journal des modifications pour rester informé des nouvelles versions et dépréciations.

---

Idempotence et déduplication

Fournissez toujours un reference unique lors de la soumission des activités. Cela évite le double traitement des récompenses lors de dépassements de délai réseau ou de nouvelles tentatives. Utilisez votre identifiant de commande interne comme référence :

Code
{
  "personalCode": "PC_JEAN2026",
  "type": "Purchase",
  "amount": 49.99,
  "reference": "commande_20260409_789"
}

---

Tests

• Utilisez l'environnement 🧪 Sandbox (https://api.sandbox.otonum.io) pendant le développement
• Générez une clé API de bac à sable dédiée dans l'application Business
• Les transactions en bac à sable n'affectent pas les vrais soldes clients et n'envoient pas de vraies notifications
• Testez tous les scénarios d'erreur (code invalide, bon expiré, limite de débit) avant la mise en production
• Passez à 🚀 Production (https://api.otonum.io) seulement lorsque votre intégration est complètement validée

---

Support

Si vous rencontrez des problèmes persistants ou avez des questions sur votre intégration :

• Courriel : support@otonum.com
• Application Business : Aide → Contacter le support

Veuillez inclure votre identifiant de compte, le referenceId ou taskId concerné et la réponse d'erreur complète lorsque vous contactez le support.