Intégrer une API de signature électronique dans un CRM

Ce qu'il faut retenir

Intégrer une API de signature dans un CRM consiste à déclencher un envoi depuis un objet métier (devis, contrat, bon de commande) et à rapatrier l'état de la procédure vers cet objet.
Le schéma d'intégration le plus simple comporte deux appels : créer une demande de signature, puis recevoir un événement de fin via webhook — pas de polling.
Les échecs les plus fréquents sont le non-respect de l'idempotence (doublons), les webhooks non sécurisés et la perte du lien entre la procédure de signature et l'enregistrement CRM.
Un environnement de test (sandbox) permet de valider le parcours complet avant de toucher les données de production.

Un CRM contient déjà l'essentiel : le contact, le devis, l'historique. Ajouter la signature consiste à relier ces données à un service de signature, sans recréer un silo. Cet article décrit l'architecture minimale, les pièges d'intégration et la structure des événements qui font tourner le circuit.

Le cas d'usage : quand brancher la signature au CRM

Les parcours typiques concernent les équipes qui clôturent des contrats dans le CRM :

Devis signé : à la validation commerciale, un bouton « envoyer pour signature » crée la procédure et joint le PDF du devis.
Contrat ou bon de commande : le document généré depuis le CRM part en signature, et son état revient dans le champ « statut contrat ».
Mandat ou lettre de mission : la pièce signée est rattachée à la fiche contact, avec la date de signature.

Le gain est double : l'équipe ne quitte plus son outil de travail, et le CRM devient la source de vérité des documents signés. L'erreur serait d'envisager la signature comme une application séparée que l'on consulte à part.

Architecture minimale : deux appels et un webhook

Le schéma le plus robuste tient en deux points d'intégration :

Étape	Appel	Ce qui se passe
1. Création	POST création de demande de signature	Le CRM envoie le document, les signataires et le contexte ; reçoit un identifiant de procédure
2. Suivi	Webhook de fin de procédure	Le service de signature notifie le CRM quand la procédure est terminée (ou refusée)
3. Récupération	GET du dossier de preuve	Le CRM rapatrie le PDF signé et le journal, et les rattache à l'objet

Le polling (« demander toutes les 30 secondes si c'est signé ») fonctionne mais gaspille des appels et retarde la mise à jour. Le webhook est le mécanisme adapté : il pousse l'événement dès qu'il se produit.

Les champs à persister dans le CRM

Pour que le CRM reste exploitable, persistez au minimum :

l'identifiant de la procédure de signature (pour retrouver le dossier et auditer) ;
le statut de la procédure (en attente, signée, refusée, expirée) ;
la date de création et de signature ;
le lien vers le document signé et le dossier de preuve ;
la référence métier (numéro de devis, de contrat) transmise dès la création.

La référence métier est essentielle : elle permet de rattacher l'événement reçu au bon enregistrement CRM, même si l'identifiant interne du CRM change.

Le webhook : sauvegarde et vérification

Quand le service de signature notifie la fin d'une procédure, votre intégration doit :

Vérifier la signature du webhook (signature HMAC sur le corps de la requête) avant de traiter l'événement ;
Être idempotente : traiter deux fois le même événement ne doit pas créer deux PDF ni deux mises à jour ;
Retenter en cas d'échec : si la mise à jour CRM échoue, le webhook doit pouvoir être rejoué ;
Logger la réception et le traitement pour l'audit.

Un point souvent négligé : le webhook doit fonctionner même si la session utilisateur est fermée. C'est un traitement serveur, pas un rafraîchissement de page.

Éviter les doublons par l'idempotence

Le scénario classique : l'utilisateur clique deux fois sur « envoyer pour signature », ou la connexion coupe et la requête est renvoyée. Sans protection, deux procédures sont créées et le client reçoit deux e-mails.

La solution est une clé d'idempotence : un identifiant unique, stable par demande (souvent la référence du devis concaténée avec une version). Le service de signature ignore toute création portant une clé déjà connue. Côté CRM, la mise à jour de l'objet doit aussi être idempotente : ne pas écraser un statut plus avancé.

Salesforce, HubSpot ou CRM maison : mêmes règles

Les principes sont identiques quel que soit le CRM :

Salesforce : le déclencheur peut être un bouton custom sur l'objet (devis, opportunité) ; l'état revient via un Apex ou un callout ; le document signé est stocké comme ContentDocument rattaché à l'enregistrement.
HubSpot : une workflow personnalisée ou un bouton sur l'enregistrement ; le webhook alimente une propriété de statut et le PDF est ajouté en pièce jointe.
CRM maison : vous contrôlez l'ensemble ; l'architecture présentée ici se transpose directement, avec la base de données comme source de vérité.

Le point commun : la logique d'intégration doit vivre dans un composant serveur, pas dans le navigateur, pour garantir la fiabilité des webhooks et la sécurité des clés API.

Les erreurs fréquentes à éviter

Polling au lieu de webhooks : inutile, coûteux et moins réactif.
Webhook non vérifié : accepter un événement sans contrôle d'authenticité expose à la falsification des statuts.
Non-idempotence : doublons de procédures et d'e-mails.
Perte du lien métier : sans référence de devis transmise, impossible de retrouver l'objet CRM.
Document signé non récupéré : le CRM affiche « signé » mais la pièce reste dans le service de signature.
Clés API exposées dans le front : les identifiants d'accès doivent rester côté serveur.

Checklist d'intégration

Préparer un environnement sandbox et des documents de test.
Créer une procédure depuis le CRM et vérifier la référence métier transmise.
Recevoir le webhook de fin et vérifier son authenticité.
Tester la relecture d'un événement (idempotence).
Rapatrier le PDF signé et le dossier de preuve dans le CRM.
Tester le parcours complet : envoi, signature réelle, mise à jour du statut.
Vérifier l'absence de doublons en cas de double clic ou de coupure réseau.

Pour aller plus loin

Intégrer une API de signature : architecture de référence — la vue d'ensemble des composants.
Idempotence d'une API de signature — éviter les doubles procédures.
Webhooks de signature : HMAC, rejeu, ordre et SSRF — sécuriser le canal de notification.

Sources officielles

Pour aller plus loin

Un webhook mal sécurisé peut compromettre l'ensemble du circuit de signature. La méthode de protection est détaillée dans l'article sur la sécurisation des webhooks.

Ce contenu fournit une information générale et des bonnes pratiques d'intégration. Les spécificités de chaque CRM et de chaque service de signature doivent être validées dans leur documentation respective.