Première Requête (flux embarqué)¶

Introduction¶

Ce tutoriel vous accompagne dans votre première demande de signature en flux embarqué (invitation_mode="caller_embed") : l'interface de signature s'affiche dans une <iframe> au sein de votre application. C'est le mode adapté à un signataire déjà présent dans votre application (onboarding SaaS, parcours produit en séance).

• Pour le flux mail (envoi d'un e-mail d'invitation au signataire), voir Première Requête (flux mail).
• Pour la comparaison des deux modes et le choix de l'un par rapport à l'autre, voir Modes d'intégration.

Tous les exemples utilisent curl. Pour la référence complète des endpoints, consultez la Référence API.

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 curl et base64 disponibles dans votre terminal
• Une page HTML que vous pouvez modifier facilement pour héberger l'iframe

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

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.

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. Le champ déterminant est invitation_mode="caller_embed" : aucun e-mail d'invitation n'est envoyé, la réponse contient pour chaque signataire un bloc embed avec l'URL à intégrer.

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": "caller_embed",
    "locales": ["fr-FR"],
    "description": "Test Getting Started Guide (embed)",
    "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
          }
        ]
      }
    ],
    "signers": [
      {
        "ref": 1,
        "email": "jean.dupont@example.com",
        "first_name": "Jean",
        "last_name": "Dupont"
      }
    ]
  }'

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é au niveau de la zone de signature : VoidSign détecte automatiquement sa position et sa page en l'associant au paramètre box_center_anchor_tag, et il suffit alors de préciser les dimensions de la zone (box_width_ratio et box_height_ratio).

Réponse 201 attendue :

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "signers": [
    {
      "signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "email": "jean.dupont@example.com",
      "status": "pending",
      "embed": {
        "iframe_url": "https://app.voidsign.com/sign/embed/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expires_at": "2026-05-26T16:00:00+00:00"
      }
    }
  ]
}

Les champs spécifiques au flux embarqué sont :

• signers[i].signer_id : identifiant canonique du signataire, à utiliser pour les endpoints par signataire (notamment le rafraîchissement de jeton).
• signers[i].embed.iframe_url : URL prête à intégrer dans <iframe src="…">. Elle contient un jeton sign_api à courte durée de vie.
• signers[i].embed.expires_at : date d'expiration du jeton sous-jacent (environ 2 heures après la création).

Faire signer le document¶

Copiez la valeur de embed.iframe_url et collez-la dans la propriété src d'une balise <iframe> au sein d'une page HTML :

<!doctype html>
<html>
  <body>
    <h1>Signez votre contrat</h1>
    <iframe
      src="https://app.voidsign.com/sign/embed/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
      width="900"
      height="700"
      style="border: 1px solid #ddd;"
    ></iframe>

    <script>
      window.addEventListener("message", (event) => {
        if (event.origin !== "https://app.voidsign.com") return;
        if (event.data?.type === "voidsign:signed") {
          alert("Document signé ! request_id = " + event.data.request_id);
        }
      });
    </script>
  </body>
</html>

Ouvrez la page dans votre navigateur, signez le document à l'intérieur de l'iframe, et vous devriez voir s'afficher la confirmation déclenchée par l'événement postMessage.

Télécharger le document signé¶

Une fois la signature effectuée, 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

Et après ?¶

Vous venez de boucler le parcours minimal d'une demande de signature en flux embarqué. Pour une intégration de qualité production, il reste à traiter :

• L'intégration complète côté front : rafraîchissement de jeton (l'iframe_url expire en ~2 h), gestion des événements voidsign:error, vérification d'origine dans votre écouteur message. Tout cela est documenté dans Intégrer la signature sur votre application.
• Les webhooks pour récupérer le PDF signé et le dossier de preuves côté serveur (le postMessage voidsign:signed est un signal navigateur par signataire, pas une source de vérité serveur). Voir Configurer les webhooks.
• La mise en production : sécurité de la clé API, gestion des environnements, idempotence. Voir Passer en production.