# Bonnes pratiques d’intégration

> Les habitudes qui rendent une intégration sûre, économe et robuste face aux erreurs.

## Sécurité

- Rangez les jetons et les secrets de webhook dans un gestionnaire de secrets, jamais dans le code. Un jeton commité se reconnaît à son préfixe `nf_` : révoquez-le aussitôt.
- Un jeton par intégration, avec les seuls scopes dont elle a besoin. Révoquer l’un ne coupe pas les autres.
- Vérifiez la signature de chaque webhook, sur le corps brut, en temps constant.

## Écritures sûres

- Envoyez une `Idempotency-Key` sur chaque création, et la même clé quand vous réessayez.
- Réessayez les `5xx` et les `429` avec un délai croissant ; ne réessayez jamais un `401`, un `403` ou un `422` sans rien changer.

## Économie de débit

- Abonnez un webhook plutôt que de sonder ; si vous sondez, espacez les appels et respectez `Retry-After`.
- Renvoyez l’`ETag` reçu dans `If-None-Match` : une réponse `304` ne coûte rien.
- Lisez le résumé des anomalies avant de paginer leurs occurrences.

## Lire les chiffres honnêtement

- `null` veut dire « non mesuré », jamais zéro. Une moyenne voyage avec son dénominateur : lisez-le.
- Un crawl tronqué ou bloqué (`comparable: false`) ne se compare pas.
- Appuyez-vous sur les `code`, jamais sur les `title`, qui se traduisent.