Intégrer une API de signature électronique : architecture de référence
Une intégration fiable sépare création, activation, suivi, preuve et reprise sur erreur. Voici le plan d’architecture et les contrats à tester.
Une démonstration d’API se résume souvent à un POST et à une URL de signature. En production, les difficultés apparaissent dans les doubles appels, les changements de signataire, les webhooks en retard, les documents trop volumineux, les expirations et les dossiers de preuve non rattachés.
L’architecture doit expliciter les responsabilités et les états. Elle doit pouvoir répondre à deux questions : que s’est-il passé après une panne ? et quelle version du document a réellement été acceptée ?
Définir les frontières et identifiants
Attribuez une référence métier stable et un identifiant technique à chaque tentative. Conservez l’identifiant du fournisseur, mais ne l’utilisez pas comme seule clé. La relation doit inclure la version documentaire et la politique de signature.
Le système métier décide qu’un acte doit être signé ; le service de signature orchestre invitation, authentification et preuve. Évitez que plusieurs applications puissent activer la même procédure sans coordination.
Orchestrer création, validation et activation
Créez d’abord un brouillon, téléversez les documents, ajoutez les signataires, puis contrôlez le résumé avant activation. Cette frontière permet de détecter une adresse erronée ou un mauvais PDF avant consommation de quota et envoi.
Utilisez une clé d’idempotence sur les commandes critiques. Le retour doit indiquer si la ressource a été créée ou rejouée. Les timeouts ne doivent jamais conduire automatiquement à un second envoi sans lecture de l’état.
Suivre et réconcilier
Les webhooks accélèrent la mise à jour, mais ils peuvent être dupliqués, retardés ou reçus dans le désordre. Stockez l’identifiant d’événement, vérifiez la signature et rendez le traitement idempotent. Interrogez périodiquement l’API pour réparer les écarts.
À la finalisation, récupérez document final, dossier de preuve et rapport de validation. Vérifiez l’empreinte et attachez les objets au dossier métier avec une politique de conservation commune.
Grille de décision
| Composant | Responsabilité | Échec à prévoir |
|---|---|---|
| Système métier | Intention et référence | Commande rejouée |
| Orchestrateur | État et politiques | Timeout fournisseur |
| Stockage | Versions documentaires | Téléversement incomplet |
| Webhook worker | Événements signés | Doublon ou désordre |
| Réconciliation | Réparer les écarts | API indisponible |
Plan d’action
- Définir une machine d’état
- Versionner documents et politiques
- Utiliser l’idempotence
- Vérifier les webhooks
- Réconcilier périodiquement
- Rapatrier et vérifier la preuve
Questions fréquentes
Faut-il stocker les PDF en base ?
Pas nécessairement. Un stockage objet avec références, empreintes, contrôle d’accès et politique de rétention est souvent plus adapté.
Peut-on faire confiance uniquement aux webhooks ?
Non. Une réconciliation permet de récupérer les événements manqués et de confirmer l’état final.
Quand consommer un quota ?
Définissez contractuellement l’unité. Une activation est généralement un meilleur point qu’un simple brouillon.
Sources officielles et techniques
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.