Intégrer la signature par mail¶

Ce guide décrit l'intégration du flux mail (invitation_mode="voidsign_mail") : la création de la demande, les relances et le suivi de l'avancement côté serveur.

Si vous découvrez VoidSign ou ce mode, commencez plutôt par Première Requête (flux mail) puis revenez ici.

Ce que vous allez construire¶

VoidSign envoie un e-mail d'invitation au signataire, qui clique sur le lien pour signer sur app.voidsign.com. Vous n'avez pas à embarquer d'interface ; votre application observe la fin de signature via webhook et récupère le PDF signé et le dossier de preuves.

sequenceDiagram
    participant B as Votre serveur
    participant V@{ "type": "entity" } as VoidSign API
    participant S as Signataire(s)

    B->>V: POST /api/v1/requests (voidsign_mail)
    V-->>B: 201 { request_id }
    V->>S: E-mail d'invitation

    Note over B: Pas d'interrogation nécessaire.<br/>Attente du webhook

    S->>V: Ouvre le lien, signe le document
    V->>B: POST webhook: request.completed
    B-->>V: 200 OK

    B->>V: GET /downloads/signed
    V-->>B: 200 signed.pdf
    B->>V: GET /downloads/audit-trail/pdf
    V-->>B: 200 audit-trail.pdf

Créer une demande pour le flux mail¶

Le corps de la requête se distingue par invitation_mode="voidsign_mail". VoidSign envoie automatiquement un e-mail d'invitation à chaque signataire après la création de la demande. Le lien d'invitation est valable 30 jours ; au-delà, le signataire ne peut plus signer et il faut annuler la demande puis en créer une nouvelle. Consultez Créer une demande pour la spécification complète de l'endpoint.

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": "Contrat de prestation",
    "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]
      }
    ]
  }'

Côté backend, seul request_id est strictement nécessaire pour la suite : il identifie la demande pour le suivi du statut et le téléchargement des documents.

Relances¶

Vous pouvez programmer des relances automatiques à la création via le champ reminder_days de chaque signataire. La valeur est une liste d'entiers indiquant, à partir du jour de création de la demande, à quels jours envoyer un rappel par e-mail au signataire tant qu'il n'a pas signé. Par exemple [3, 7] envoie une relance 3 jours puis 7 jours après création.

Un membre de l'entreprise peut également déclencher une relance manuelle à tout moment depuis le tableau de bord, tant que le signataire est au statut pending.

Suivre l'avancement¶

Pour observer la fin de signature en production, utilisez les webhooks : VoidSign appelle votre endpoint dès que tous les signataires ont signé. Configurez votre webhook depuis https://app.voidsign.com/pro/api/webhooks et abonnez-vous à l'événement request.completed. Voir Configurer les webhooks pour la vérification de signature et les bonnes pratiques.

Le polling (interrogation répétée de GET /api/v1/requests/{request_id}) est acceptable pour découvrir l'API depuis votre poste de développement, mais il n'est pas recommandé en production : il consomme votre quota de débit et ajoute de la latence par rapport à la livraison par webhook.