Skip to main content
Une intégration qui fonctionne en test peut échouer en production. Cette liste couvre ce qui cause réellement les incidents.

​
Sécurité

La clé d’API n’existe que côté serveur, dans une variable d’environnement. Jamais dans une application mobile, une page web, un dépôt Git.
Chaque intégration a sa propre clé, avec le strict nécessaire de permissions.
Les clés sensibles sont restreintes à vos adresses IP et ont une date d’expiration.
Chaque envoi de Pulse est vérifié (signature + horodatage + corps brut + comparaison en temps constant).
Vos journaux ne contiennent ni clé, ni secret, ni e-mails de clients en clair.
Tout passe en HTTPS.

​
Résilience

Chaque POST porte une Idempotency-Key stable pour une même action métier.
Vos appels ont un délai maximal (8 à 10 secondes) : un appel sans limite finit par bloquer votre serveur.
Une 429 est réessayée après Retry-After ; une 5xx avec attente croissante et aléatoire ; une 4xx (sauf 429) n’est jamais réessayée à l’identique.
Votre récepteur de Pulses répond 200 tout de suite et traite ensuite, en dédoublonnant sur event.id.
Vous avez un plan de rattrapage : lister les ventes d’une période avec l’API après une panne.

​
Performance

per_page=100 pour les synchronisations.
Les Pulses remplacent les interrogations répétées : n’appelez pas GET /sales chaque minute pour détecter une vente.
Les données stables (produits, boutique) sont mises en cache quelques minutes.
Vous surveillez X-RateLimit-Remaining et ralentissez avant la limite plutôt qu’après.

​
Paiements

Vous ne vous fiez jamais à la page de retour du client pour confirmer un paiement : seul sale.completed (ou payment_status lu par l’API) fait foi.
Vous traitez tous les états d’une commande : payée, en attente, échouée, abandonnée, remboursée.
Vous stockez l’identifiant de la vente dès sa création pour la rapprocher de vos commandes.

​
Tests

Vous envoyez un événement de test (POST /pulses/{id}/test) avant d’activer le scénario réel.
Vous testez les cas d’erreur : clé invalide, permission manquante, limite atteinte, validation refusée, serveur indisponible.
Vous testez la rotation d’une clé et d’un secret : une rotation ne doit jamais être un incident.

​
Quand quelque chose ne va pas

  1. Notez l’en-tête X-Request-Id de la réponse en cause.
  2. Lisez code et errors dans le corps : ils disent presque toujours exactement quoi corriger. Voir Erreurs.
  3. Pour un Pulse, ouvrez l’historique des envois (GET /pulses/{id}/deliveries) : vous y voyez le code HTTP reçu par votre serveur.
  4. Si vous contactez le support, fournissez le X-Request-Id.