Intégrer une API de signature électronique consiste à connecter directement vos applications métier (CRM, ERP, plateforme RH, logiciel SaaS) aux fonctionnalités de signature, sans passer par une interface tierce. Pour une équipe produit ou technique, l'objectif est clair : automatiser l'envoi des documents à signer, suivre leur statut en temps réel et déclencher des actions métier dès qu'une signature est apposée.
Mal préparée, une intégration API génère pourtant des frictions classiques : authentification mal comprise, webhooks non sécurisés, tests insuffisants avant la mise en production. Dans cet article, vous trouverez les étapes d'intégration de bout en bout, des exemples de code en cURL, Node.js, Python et PHP, la gestion des webhooks, les erreurs fréquentes et une checklist de mise en production.
Résumé en bref :
- Compte sandbox : indispensable avant toute intégration, il permet de tester sans engager de documents réels.
- Authentification : une clé API statique transmise dans l'en-tête `Authorization` selon le schéma `Bearer`, sans flux OAuth.
- Signature request : objet central de l'API, il regroupe document, signataires et champs de signature.
- Webhooks : ils notifient votre application en temps réel des évènements, avec une signature HMAC à vérifier systématiquement.
- Mise en production : nécessite de basculer de la clé API sandbox vers la clé API live, après validation complète des tests.
Pourquoi intégrer une API de signature électronique à votre application
Passer par une API plutôt que par l'interface web classique permet d'insérer la signature électronique directement dans le parcours de vos utilisateurs : signature d'un devis depuis votre CRM, validation d'un contrat de travail depuis votre SIRH, approbation d'un bon de commande depuis votre ERP. Vous gardez la main sur l'expérience utilisateur tout en déléguant la valeur légale et la sécurité de la signature.
Avant de vous lancer, il peut être utile de regarder à quoi ressemblent des intégrations réussies, secteur par secteur, notamment si votre équipe découvre tout juste le sujet. Cette automatisation s'inscrit aussi dans une logique plus large : les avantages chiffrés d'une API de signature électronique vont de la réduction du temps de traitement au retour sur investissement documenté.
Avant de commencer : les prérequis techniques
Créer un compte sandbox
Avant d'écrire la moindre ligne de code en production, activez l'essai API et son environnement sandbox. Il reproduit le comportement de l'API de production, sans valeur juridique ni envoi réel aux signataires. C'est l'endroit pour itérer sur vos appels API, tester vos webhooks et valider votre workflow complet. La procédure de création de compte et de première requête se déroule en cinq étapes, depuis la section API > API keys de l'application.
L'essai API gratuit donne un accès de 40 jours à un environnement sandbox dédié ; l'environnement de production n'est débloqué qu'après souscription à un plan payant.
Passez à la vitesse supérieure
Tester gratuitement Youtrust pendant 14 jours
Récupérer vos clés API et choisir votre mode d'authentification
Chaque clé API est rattachée à un environnement, à un périmètre (`organization` ou `workspace`) et à un niveau de permission (`Read-Only` ou `Full-Access`). Pour créer des ressources — signature requests, documents, signataires — une clé `Full-Access` est obligatoire. Seuls les rôles Admin ou Owner peuvent générer une clé.
Conservez ces clés côté serveur uniquement : elles ne doivent jamais transiter côté client (navigateur, application mobile). Une clé n'expire pas automatiquement : prévoyez une rotation périodique et une révocation immédiate en cas d'exposition.
Bon à savoir
Avant de choisir votre architecture d'intégration, prenez le temps de passer en revue les 10 critères pour choisir une API de signature électronique : conformité, SLA, souveraineté des données, support. Cela évite des refontes coûteuses une fois le développement avancé.
Les 7 étapes pour intégrer une API de signature électronique
Étape 1 — S'authentifier avec un jeton Bearer
L'API ne repose pas sur un flux OAuth : votre clé API est transmise telle quelle dans l'en-tête `Authorization`, selon le schéma `Bearer`. Le choix de l'environnement cible se fait par la base URL — `https://api-sandbox.yousign.app/v3` en test, `https://api.yousign.app/v3` en production. Une clé créée dans un environnement ne peut pas accéder à l'autre.
curl --location --request GET 'https://api-sandbox.yousign.app/v3/signature_requests' \ --header 'Authorization: Bearer {apiKey}'
Si cette requête renvoie la liste de vos signature requests, votre authentification est opérationnelle.
Étape 2 — Créer une demande de signature (signature request)
La « signature request » est l'objet pivot de l'API : elle regroupe le document, les signataires, les champs de signature et le niveau de signature choisi. Exemple en Node.js :
const response = await fetch("https://api-sandbox.yousign.app/v3/signature_requests", { method: "POST", headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" }, body: JSON.stringify({ name: "Contrat de prestation", delivery_mode: "email", timezone: "Europe/Paris" }) }); const signatureRequest = await response.json(); // status: "draft"
La ressource est créée au statut `draft` : aucun signataire n'est encore sollicité à ce stade.
Le règlement (UE) n° 910/2014 dit eIDAS encadre la reconnaissance juridique de la signature électronique dans l'Union européenne. Il a été révisé par le règlement (UE) 2024/1183, dit « eIDAS 2 », entré en application le 18 octobre 2024. Le niveau retenu détermine la force probante du document signé.
« Il existe quatre niveaux de signature et cachet électroniques : simple ; avancé ; avancé reposant sur un certificat qualifié ; qualifié. »
Étape 3 — Uploader le document à signer
Une fois la signature request créée, vous y associez le ou les documents PDF. Le champ `nature` est requis et vaut `signable_document` pour un document destiné à être signé. Exemple en Python :
import requests
url = f"https://api-sandbox.yousign.app/v3/signature_requests/{signature_request_id}/documents" files = {"file": open("contrat.pdf", "rb")} data = {"nature": "signable_document"} headers = {"Authorization": f"Bearer {api_key}"}
response = requests.post(url, files=files, data=data, headers=headers) document = response.json()
Étape 4 — Ajouter les signataires et positionner les champs
Chaque signataire est défini par son identité, son email et son mode de délivrance. Les champs de signature sont positionnés sur le document via des coordonnées (page, x, y) ou des ancres textuelles automatiques.
Attention
Une erreur fréquente consiste à positionner les champs par coordonnées fixes sans tenir compte des documents à mise en page variable. Préférez le positionnement par ancre textuelle pour fiabiliser l'intégration sur des documents générés dynamiquement. Notez aussi que les limites de ressources par signature request encadrent le nombre de documents, de signataires et de champs.
Étape 5 — Activer la demande de signature
Tant que la signature request reste au statut `draft`, aucun email n'est envoyé. L'activation la fait passer en `ongoing` et déclenche les notifications aux signataires. Exemple en PHP :
php $ch = curl_init("https://api-sandbox.yousign.app/v3/signature_requests/{$signatureRequestId}/activate"); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $apiKey"]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch);Étape 6 — Recevoir et traiter les webhooks
Les webhooks notifient votre application en temps réel de chaque évènement, sans que vous ayez à interroger l'API en continu. Il faut d'abord créer un abonnement webhook en déclarant votre endpoint HTTPS, votre `secret_key`, l'environnement visé via l'attribut `sandbox` et la liste des évènements souscrits — ou le joker `` pour tous les capter.
Important
Si votre compte API est en période d'essai, les abonnements webhook ne peuvent être créés que depuis l'application, et uniquement en sandbox. C'est le point de blocage le plus fréquent à cette étape.
Consultez la liste complète des évènements disponibles pour ne souscrire qu'à ce dont vous avez besoin. Exemple de payload reçu :
{ "event_id": "f1c0b2a4-9e3d-4f58-b7a1-2c6d8e0f3a91", "event_name": "signature_request.done", "event_time": 1760000000, "subscription_id": "3b7e1d92-5a84-4c13-9f60-ad2e7c514b08", "sandbox": true, "data": { "signature_request": { "id": "2a6f9f6a-18a4-4e14-8bee-b734369f3cf6", "status": "done" } } }
Côté réception, la validation du payload repose sur l'en-tête `X-Yousign-Signature-256` : calculez un HMAC SHA-256 du corps brut de la requête avec votre clé secrète, préfixez le résultat de `sha256=` et comparez les deux valeurs à temps constant. Hashez toujours le corps brut, jamais une version déjà parsée.
Attention
Votre endpoint doit répondre un code 2xx en moins d'une seconde sur la première tentative, sinon la livraison est considérée comme échouée. Traitez la logique lourde en asynchrone. En cas d'échec, la politique de relance rejoue jusqu'à 8 fois avec un backoff exponentiel étalé sur 2 jours : dédupliquez impérativement sur `event_id` et suivez l'en-tête `X-Yousign-Retry`.
Étape 7 — Basculer en production
Une fois les tests validés, générez une clé API de production, remplacez la base URL par `https://api.yousign.app/v3` et créez un nouvel abonnement webhook avec `sandbox: false`. Les abonnements ne sont pas dupliqués automatiquement d'un environnement à l'autre.
Tester son intégration avant la mise en production
La collection Postman officielle permet de rejouer l'ensemble des endpoints sans écrire une ligne de code, avec des variables dynamiques (`signatureRequestId`, `documentId`) qui s'enchaînent automatiquement. Avant la mise en production, testez systématiquement :
- La création et l'activation d'une demande de signature avec plusieurs signataires.
- La réception des webhooks pour chaque statut (activé, signé, refusé, expiré).
- Le comportement de votre application en cas de timeout ou de relance d'un même évènement.
- La gestion des erreurs 4xx avec des messages explicites côté utilisateur.
Gardez en tête que la sandbox applique des limites fonctionnelles : documents filigranés, nombre de signataires restreint pendant l'essai et destinataires limités aux membres de votre organisation.
Erreurs API fréquentes et comment les résoudre
Code erreur | Cause probable | Solution |
|---|---|---|
401 Unauthorized | Clé API absente, révoquée ou mal formatée | Vérifier l'en-tête `Authorization: Bearer {apiKey}` |
403 Forbidden | Clé `Read-Only` utilisée pour une écriture, ou mauvais environnement | Générer une clé `Full-Access` sur le bon environnement |
404 Not Found | ID de signature request ou de document invalide | Contrôler l'identifiant et la présence de `/v3` dans l'URL |
422 Unprocessable Entity | Champ obligatoire manquant (`nature`, signataire, document) | Valider le payload avant envoi |
429 Too Many Requests | Quota dépassé : 30 requêtes/minute et 200 requêtes/heure en sandbox | Mettre en place un retry avec backoff exponentiel |
500 Internal Server Error | Incident côté fournisseur | Rejouer la requête puis contacter le support |
Combien de temps prend l'intégration d'une API de signature électronique ?
La majorité des clients Youtrust intègrent l'API en moins d'une semaine, soit environ 7 jours en moyenne, documentation et environnement de test compris. Ce délai dépend surtout de la complexité de vos workflows : nombre de signataires, règles d'ordonnancement, niveau de signature requis, intégration à votre archivage existant. Un premier appel API fonctionnel, lui, se fait en quelques minutes via Postman.
Les équipes techniques en ISV ont des enjeux spécifiques, détaillés dans notre article sur les raisons de choisir la signature électronique en tant qu'ISV.
Avec Youtrust, votre équipe dispose d'une API REST v3 documentée, d'un environnement sandbox isolé de la production et d'un support technique dédié aux intégrations. Vous gardez le contrôle total sur l'expérience de signature intégrée à votre application, tout en vous appuyant sur une infrastructure conforme eIDAS.
Checklist avant la mise en production
- Une clé API de production `Full-Access` a été générée et stockée dans un gestionnaire de secrets.
- La base URL pointe bien vers `https://api.yousign.app/v3`.
- Un abonnement webhook `sandbox: false` est créé et son endpoint est publiquement accessible en HTTPS.
- La signature `X-Yousign-Signature-256` est vérifiée côté serveur sur le corps brut.
- Le traitement des webhooks est asynchrone et idempotent via `event_id`.
- Les erreurs 401, 422 et 429 sont gérées avec des messages clairs et un backoff.
- Un test de bout en bout a été réalisé avec un document réel et un vrai signataire.
Conclusion
Intégrer une API de signature électronique suit un chemin balisé : authentification par clé API, création de la signature request, upload du document, ajout des signataires, activation, puis gestion sécurisée des webhooks avant la bascule en production. La clé du succès réside dans une phase de test rigoureuse en sandbox, qui évite la majorité des erreurs rencontrées en production. Pour aller plus loin sur les critères de choix de votre fournisseur, consultez notre article parole d'expert sur les éléments essentiels pour lancer un projet d'API, et explorez le Developer Center pour la référence complète des endpoints.
Testez une API de signature électronique conforme eIDAS
Envie de tester une API de signature électronique conforme eIDAS ?
FAQ
Comment intégrer une API de signature électronique dans mon application ?
En suivant ces étapes : créer un compte sandbox, s'authentifier avec une clé API en Bearer, créer une signature request, uploader le document, ajouter les signataires, activer la demande puis traiter les webhooks avant de passer en production.
Quelles sont les étapes d'intégration d'une API de signature électronique ?
Authentification, création de la signature request au statut `draft`, upload du document, ajout des signataires et des champs, activation (passage en `ongoing`), réception des webhooks, puis bascule sur la base URL de production.
Comment tester une API de signature électronique avant la mise en production ?
Utilisez l'environnement sandbox, accessible gratuitement pendant 40 jours : il reproduit le comportement de l'API de production sans valeur juridique ni envoi réel. La collection Postman officielle permet de rejouer tous les endpoints sans écrire de code.
Comment gérer les webhooks d'une API de signature électronique ?
Créez un abonnement en déclarant un endpoint HTTPS et une clé secrète, vérifiez le HMAC SHA-256 de l'en-tête `X-Yousign-Signature-256`, répondez un 2xx en moins d'une seconde et dédupliquez les évènements sur `event_id`.
Combien de temps prend l'intégration d'une API de signature électronique ?
La majorité des clients Youtrust intègrent l'API en moins d'une semaine, soit environ 7 jours en moyenne. Le délai varie selon la complexité des workflows à couvrir.
Existe-t-il des exemples de code pour envoyer un document à signer via API ?
Oui : la documentation fournit des exemples en cURL ainsi que dans les langages serveur courants (Node.js, Python, PHP), couvrant la création de la demande, l'upload du document et son activation.
