Idempotence des appels API de signature
Idempotence des appels API de signature : clé d'idempotence, retries, doublons d'envois et bonnes pratiques d'intégration.
- L'idempotence garantit qu'un même appel API n'est appliqué qu'une seule fois.
- Elle protège contre les doublons d'envois et de signatures en cas de retry.
- Elle repose sur un identifiant unique fourni par le client.
- Elle est indispensable dans les intégrations critiques et les workflows automatisés.
Lorsqu'une intégration appelle une API de signature, un réseau instable peut dupliquer la demande. L'idempotence empêche ce scénario. Cet article explique pourquoi elle est critique.
Le problème des requêtes dupliquées
Une API reçoit parfois la même requête plusieurs fois :
- timeout et nouvelle tentative automatique ;
- double-clic dans l'interface ;
- retry d'un job de traitement ;
- rappel d'un webhook.
Sans protection, un envoi de signature peut être créé deux fois, provoquant des doublons et des confusions.
Ce qu'est l'idempotence
Une opération est idempotente si la répéter produit le même résultat que la première exécution.
- deux appels identiques → une seule ressource créée ;
- les appels suivants renvoient la ressource existante ;
- aucun effet de bord dupliqué.
L'idempotence transforme une erreur réseau en événement sans conséquence.
La clé d'idempotence
| Élément | Rôle |
|---|---|
| Clé (Idempotency-Key) | Identifiant unique de l'opération |
| Corps de requête | Doit correspondre à la clé |
| Durée de conservation | Période pendant laquelle la clé est reconnue |
| Réponse | Renvoyée telle quelle pour une clé connue |
Le client génère la clé ; l'API l'associe à la ressource créée.
Les risques sans idempotence
- Envois dupliqués : le signataire reçoit deux e-mails.
- Doublons de contrats : deux versions coexistent.
- Demandes de signature multiples : confusion et refus.
- Facturation en double dans les offres à l'usage.
- Workflows désynchronisés : les étapes se dérèglent.
Dans un volume élevé, ces risques se multiplient et deviennent des incidents clients.
Bonnes pratiques côté client
- Générer une clé unique par opération (UUID).
- Réutiliser la même clé lors des retries.
- Ne pas changer le corps avec la même clé.
- Logger les clés et les réponses.
- Tester les scénarios de retry.
Bonnes pratiques côté fournisseur
- Accepter un en-tête de clé d'idempotence.
- Conserver la clé avec la ressource.
- Renvoyer la même réponse pour une clé connue.
- Documenter la durée de conservation.
- Détecter les collisions (même clé, corps différent).
Erreurs fréquentes à éviter
- Générer une nouvelle clé à chaque retry : l'idempotence devient inutile.
- Ne pas conserver la clé côté serveur.
- Changer le corps avec la même clé.
- Confondre idempotence et webhook.
- Ignorer les timeouts dans la gestion des appels.
Checklist d'intégration
- Générer une clé unique par opération.
- Réutiliser la clé sur les retries.
- Vérifier la réponse retournée.
- Tester les doublons simulés.
- Surveiller les erreurs d'idempotence.
Pour aller plus loin
- API de signature — l'intégration aux outils.
- Webhooks — la notification après signature.
- Sécurité des API — protéger les appels (programmé).
Questions fréquentes
L'idempotence est-elle obligatoire ?
Elle est une bonne pratique standard des API fiables, et essentielle dans les workflows critiques.
Quand la clé expire-t-elle ?
Selon le fournisseur. Pour une opération de signature, elle doit couvrir toute la durée de l'envoi.
Que faire si la clé est réutilisée avec un autre corps ?
L'API doit refuser ou signaler la collision pour éviter une corruption.
Sources officielles
- RFC 7231 — méthodes HTTP et idempotence
- API de signature électronique — guide d'intégration
L'idempotence s'accompagne des webhooks pour un flux fiable. Voir l'article sur les webhooks post-signature.
Ce contenu est une information technique générale et ne remplace pas la documentation de votre fournisseur.
Important
Ce contenu fournit une information générale et ne remplace pas un avis juridique ou un audit de conformité. Le niveau de signature adapté dépend du contexte, de l’identification, de l’authentification et des preuves effectivement produites.