Aller au contenu

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.

VoidSign en production

Le polling 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.

Prérequis

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 :

X-VoidSign-Key: vs_live_...

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

Téléversez un PDF, positionnez un champ de signature et spécifiez un signataire. 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 encodé en base64 de votre fichier PDF.

Cela créera une demande de signature sur le document fourni avec un seul signataire et un champ de signature. Des champs supplémentaires peuvent être ajoutés.

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-ULP-GD",
            "box_x_ratio": 0.15,
            "box_y_ratio": 0.7,
            "box_width_ratio": 0.3,
            "box_height_ratio": 0.1,
            "page_number": 0,
            "signer_ref": 1
          }
        ]
      }
    ],
    "signers": [
      {
        "ref": 1,
        "email": "jean.dupont@example.com",
        "first_name": "Jean",
        "last_name": "Dupont",
        "reminder_days": [3, 7]
      }
    ]
  }'

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é.

Positionner les champs sur votre PDF

Pour déterminer les coordonnées des champs, consultez le guide Positionner les champs sur un PDF. Il couvre l'outil visuel Fields Helper, les stratégies pour les documents dynamiques et le calcul programmatique des coordonnées.

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": [...],
  [...]
}

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 :

curl -X GET \
  "https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads/audit-trail/pdf" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  --output audit-trail.pdf