Première Requête¶
Introduction¶
Ce guide vous accompagne dans votre première demande de signature via l'API VoidSign : créer une demande, vérifier son état, puis télécharger le document signé. Tous les exemples utilisent curl. Pour la référence complète des endpoints, consultez la Référence API.
Tutoriel interactif en ligne de commande (expérimental)
Ce tutoriel existe aussi sous forme de script bash guidé pas à pas, pour ceux qui préfèrent exécuter que lire. Il effectue les mêmes requêtes que ce guide, avec le même document de test.
Le script bash est expérimental — il peut évoluer ou cesser de fonctionner sans préavis, et n'est pas couvert par les garanties de stabilité de l'API. Ce guide écrit reste la référence.
Prérequis supplémentaire : jq (en plus de curl et base64). Le script gère le français et l'anglais.
Pour inspecter le script avant de l'exécuter :
Prérequis¶
- Un compte VoidSign (la configuration de la facturation n'est nécessaire qu'après avoir dépassé les 3 signatures mensuelles gratuites)
- Liens rapides pour se connecter ou pour créer un compte
- Les commandes
curletbase64disponibles dans votre terminal
Configurer votre clé API¶
Rendez-vous sur https://app.voidsign.com/pro/api/keys pour créer une clé API. Chaque requête API doit inclure votre clé dans l'en-tête X-VoidSign-Key :
Gardez votre clé API secrète
Ne versionnez pas votre clé API et ne l'exposez pas dans du code côté client. Traitez-la comme un mot de passe.
Pour vérifier que votre clé est valide, essayez de récupérer une demande inexistante. Une réponse 404 signifie que la clé est valide ; une réponse 401 signifie qu'elle ne l'est pas :
curl -X GET \
"https://api.voidsign.com/api/v1/requests/wrong_id" \
-H "X-VoidSign-Key: vs_live_API_KEY"
Créer une demande de signature¶
Pour ce guide, nous utilisons un document de test prêt à l'emploi : un accord fictif en français contenant un champ caché intégré. Téléchargez-le ici : sample_agreement_fr.pdf.
VoidSign envoie au signataire un e-mail d'invitation contenant un lien pour signer le document. Consultez Créer une demande pour la spécification complète de l'endpoint.
Taille maximale du fichier
La taille maximale du PDF décodé est de 3 Mo via l'API. Consultez Limites pour l'ensemble des contraintes.
Remplacez vs_live_API_KEY par votre clé API réelle et <BASE64_CONTENT> par le contenu du fichier sample_agreement_fr.pdf encodé en base64.
curl -X POST \
"https://api.voidsign.com/api/v1/requests" \
-H "X-VoidSign-Key: vs_live_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"auth_method": "mail",
"invitation_mode": "voidsign_mail",
"locales": ["fr-FR"],
"description": "Test Getting Started Guide",
"documents": [
{
"base64": "<BASE64_CONTENT>",
"fields": [
{
"type": "signature",
"box_coordinate_system": "CS-ACP-GD",
"box_center_anchor_tag": "VS_ANCH_ABCD",
"box_width_ratio": 0.24477791116446576,
"box_height_ratio": 0.08387096774193559,
"signer_ref": 1
},
{
"type": "paraph",
"box_coordinate_system": "CS-CP-AD",
"box_center_x_ratio": 0.9600240096038415,
"box_center_y_ratio": 0.9788624787775893,
"page_number": "all",
"signer_ref": 1,
"font_size": 14
}
]
}
],
"signers": [
{
"ref": 1,
"email": "jean.dupont@example.com",
"first_name": "Jean",
"last_name": "Dupont",
"reminder_days": [3, 7]
}
]
}'
Le champ de signature utilise le système de coordonnées CS-ACP-GD (Anchor Center Point + Given Dimensions). Le document de test contient un champ caché intitulé VS_ANCH_ABCD intégrée au niveau de la zone de signature. VoidSign détecte automatiquement la position et la page du champ caché en l'associant avec le paramètre box_center_anchor_tag, puis il suffit de spécifier les dimensions de la zone de signature (box_width_ratio et box_height_ratio).
Le champ de paraphe utilise le système CS-CP-AD avec page_number: "all" pour apposer les initiales du signataire sur chaque page du document.
Réponse 201 attendue :
{
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "created",
"signers": [
{
"email": "jean.dupont@example.com",
"status": "pending"
}
]
}
Conservez le request_id
Vous aurez besoin du request_id pour vérifier le statut et télécharger le document signé.
Utiliser vos propres documents
Ce guide utilise un document avec un champ caché (VS_ANCH_ABCD) pour simplifier le positionnement. Pour utiliser vos propres PDF, consultez le guide Positionner les champs sur un PDF et la référence Systèmes de coordonnées pour le système CS-ULP-GD.
Vérifier l'état de la demande¶
Vérifiez le statut de votre demande en appelant l'endpoint de statut de la demande :
curl -X GET \
"https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "X-VoidSign-Key: vs_live_API_KEY"
Tant que le signataire n'a pas encore signé, la réponse ressemble à :
{
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "created",
"signed_at": null,
"signers": [...],
[...]
}
Une fois que tous les signataires ont signé, le status passe à "signed" et signed_at est renseigné :
{
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "signed",
"signed_at": "2026-03-16T17:42:28Z",
"signers": [...],
[...]
}
VoidSign en production
Le polling (ou l'interrogation répétitive du statut d'un objet, ici la demande de signature) n'est pas la méthode recommandée pour intégrer VoidSign en production. L'utilisation des webhooks est la méthode prévue. VoidSign en production est un guide dédié pour utiliser VoidSign correctement dans un environnement de production.
Télécharger le document signé¶
Une fois le statut de la demande à "signed", téléchargez le PDF final. Consultez Télécharger le PDF signé.
curl -X GET \
"https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads/signed" \
-H "X-VoidSign-Key: vs_live_API_KEY" \
--output signed.pdf
Télécharger le dossier de preuves¶
Le dossier de preuves est un enregistrement infalsifiable du processus de signature : qui a signé, quand et depuis où. Il est disponible aux formats JSON et PDF. Consultez Télécharger le dossier de preuves.
Format JSON :
curl -X GET \
"https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads/audit-trail/json" \
-H "X-VoidSign-Key: vs_live_API_KEY" \
--output audit-trail.json
Format PDF :