> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pulse-sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bonnes pratiques

> Sécurité, résilience, performance et tests : la liste de contrôle avant de passer en production.

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

## Sécurité

> [!TIP]
>
> 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.

> [!TIP]
>
> Chaque intégration a sa **propre clé**, avec le strict nécessaire de permissions.

> [!TIP]
>
> Les clés sensibles sont restreintes à vos **adresses IP** et ont une **date d'expiration**.

> [!TIP]
>
> Chaque envoi de Pulse est **vérifié** (signature + horodatage + corps brut + comparaison en temps constant).

> [!TIP]
>
> Vos journaux ne contiennent ni clé, ni secret, ni e-mails de clients en clair.

> [!TIP]
>
> Tout passe en **HTTPS**.

## Résilience

> [!TIP]
>
> Chaque `POST` porte une `Idempotency-Key` stable pour une même action métier.

> [!TIP]
>
> Vos appels ont un **délai maximal** (8 à 10 secondes) : un appel sans limite finit par bloquer votre serveur.

> [!TIP]
>
> 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.

> [!TIP]
>
> Votre récepteur de Pulses répond **200 tout de suite** et traite ensuite, en dédoublonnant sur `event.id`.

> [!TIP]
>
> Vous avez un plan de **rattrapage** : lister les ventes d'une période avec l'API après une panne.

## Performance

> [!TIP]
>
> `per_page=100` pour les synchronisations.

> [!TIP]
>
> Les **Pulses** remplacent les interrogations répétées : n'appelez pas `GET /sales` chaque minute pour détecter une vente.

> [!TIP]
>
> Les données stables (produits, boutique) sont mises en cache quelques minutes.

> [!TIP]
>
> Vous surveillez `X-RateLimit-Remaining` et ralentissez avant la limite plutôt qu'après.

## Paiements

> [!TIP]
>
> 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.

> [!TIP]
>
> Vous traitez tous les états d'une commande : payée, en attente, échouée, abandonnée, remboursée.

> [!TIP]
>
> Vous stockez l'identifiant de la vente dès sa création pour la rapprocher de vos commandes.

## Tests

> [!TIP]
>
> Vous envoyez un **événement de test** (`POST /pulses/{id}/test`) avant d'activer le scénario réel.

> [!TIP]
>
> Vous testez les cas d'erreur : clé invalide, permission manquante, limite atteinte, validation refusée, serveur indisponible.

> [!TIP]
>
> 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](https://docs.pulse-sell.com/concepts/errors.md).
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.