Modes d'intégration¶
VoidSign propose deux modes d'intégration. Le mode est choisi à la création de la demande via le champ invitation_mode du corps de la requête POST /api/v1/requests :
- Flux mail (
invitation_mode="voidsign_mail") : le signataire signe surapp.voidsign.com. - Flux embarqué (
invitation_mode="caller_embed") : le signataire signe dans votre application via une<iframe>.
Dans les deux flux, le signataire valide un code OTP avant de confirmer sa signature.
Comparaison rapide¶
| Axe | Flux mail (voidsign_mail) |
Flux embarqué (caller_embed) |
|---|---|---|
| Initiative | Asynchrone : le signataire arrive quand il le souhaite, depuis son e-mail. | Synchrone : votre application amène le signataire dans le flux, en temps réel. |
| Interface | Hébergée par VoidSign : le signataire ouvre app.voidsign.com. |
Dans votre application : l'interface VoidSign s'affiche dans une <iframe> au sein de votre propre page. |
| Déclenchement | Vous créez la demande, VoidSign délivre par e-mail. | Vous savez que le signataire est déjà dans votre application, vous lui présentez le document. |
| Réponse de l'API à la création | Un request_id. L'invitation part par e-mail. |
Un request_id et, par signataire, un bloc embed contenant iframe_url et expires_at. |
| Réception du résultat | Webhook request.completed lorsque tous les signataires ont signé. |
Webhook identique, plus un événement postMessage voidsign:signed émis dans la page parente dès la fin de la signature. |
| Cas d'usage typique | Contrats commerciaux, flux RH, demandes envoyées en différé à des signataires externes. | Onboarding SaaS, contrats signés en séance, parcours produit où la signature doit rester dans votre tunnel. |
Quand choisir le flux mail (voidsign_mail)¶
Choisissez ce flux quand :
- Le signataire n'est pas déjà dans votre application au moment où vous créez la demande.
- Vous souhaitez que VoidSign s'occupe entièrement de la délivrance (invitation, relances, lien personnel).
- L'expérience d'arrivée par e-mail est acceptable, voire souhaitée (sentiment d'officialité, traçabilité de l'envoi).
Démarrer : Première Requête (flux mail), puis Intégrer la signature par mail.
Quand choisir le flux embarqué (caller_embed)¶
Choisissez ce flux quand :
- Le signataire est déjà authentifié dans votre application et vous voulez lui présenter le document sans le faire sortir de votre interface.
- Vous voulez conserver la maîtrise du moment exact où la signature est proposée (parcours produit, étape d'onboarding, validation d'un devis).
- Votre intégration doit réagir au résultat immédiatement côté client (avancer dans un tunnel, mettre à jour une UI), pas seulement via webhook.
- Vous voulez contrôler vous-même la communication avec vos signataires (e-mails, relances, notifications), sans que VoidSign envoie ses propres messages.
Démarrer : Première Requête (flux embarqué), puis Intégrer la signature sur votre application.
Ce que les deux flux partagent¶
Les deux flux reposent sur la même API, le même cycle de vie, la même facturation et le même dossier de preuves :
- Création de demande identique (
POST /api/v1/requestsavec documents, signataires, champs). - Statuts de demande et de signataire identiques. Voir Cycle de vie d'une demande.
- Webhooks identiques. Voir Configurer les webhooks.
- Téléchargement du PDF signé et du dossier de preuves via les mêmes endpoints.
Seule la délivrance du lien de signature change entre les deux modes.