Sessions et liens de signature

Les destinataires signent sur la page de signature de Bona Fide : soit la page hébergée à l’adresse https://sign.bonafidesign.com/s/…, soit la même page intégrée à votre produit avec <bf-signing>. Les destinataires n’ont pas besoin de compte. Ce qui leur donne accès, c’est une session de signature.

Sessions de signature

La livraison par courriel crée les sessions pour vous (le lien dans le courriel). Pour une signature intégrée ou que vous livrez vous-même, créez-en une à partir de votre back-end :

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

Champ	Remarques
recipient	Un destinataire de l’enveloppe qui peut encore signer (pas en copie conforme, pas terminé)
mode	embedded (par défaut) ou hosted. Les url hébergées ont la forme …/s/<token>, vers laquelle rediriger ou à envoyer vous-même
allowedOrigins	Jusqu’à 10 origines autorisées à afficher la page intégrée dans un cadre
returnUrl	L’adresse vers laquelle la page hébergée renvoie le signataire une fois qu’il a terminé
ttlSeconds	De 60 à 3600, 600 par défaut

Les sessions sont à usage unique : dès que le destinataire soumet, la session est consommée, et une session utilisée ou expirée répond 410 Gone. Créez-en une nouvelle chaque fois que votre page s’affiche. Les sessions ne peuvent être créées que lorsque l’enveloppe est à l’état sent, et l’annulation de l’enveloppe y met fin.

Le parcours du signataire

La page de signature (et toute interface personnalisée que vous bâtissez sur la même API) suit ces étapes :

1. Échange : POST /v1/signing/exchange { "token": "bfs_…" } renvoie un jeton d’accès éphémère (bfa_…) conservé en mémoire. Aucun témoin n’est utilisé : le blocage des témoins tiers n’a donc aucune incidence dans un iframe.
2. Chargement : GET /v1/signing/session renvoie la vue du signataire (titre de l’enveloppe, expéditeur, rôle et champs du destinataire, valeurs préremplies, avis au consommateur) et enregistre recipient.viewed la première fois. GET /v1/signing/document est le PDF à afficher.
3. Vérification (seulement avec email_otp) : POST /v1/signing/otp envoie par courriel un code à six chiffres (valide 10 minutes) et POST /v1/signing/otp/verify le vérifie. Un code erroné renvoie verified: false avec le nombre de tentatives restantes. Le champ verification.verified de la vue vaut déjà true quand la méthode du destinataire n’exige aucun code.
4. Soumission : POST /v1/signing/submit avec les values des champs (signatures dessinées, tapées ou téléversées), le consentement à l’avis et viewedDocumentHash, le SHA-256 du PDF exact qui a été affiché. Si le document a changé depuis, la soumission est refusée (409).
5. Ou refus : POST /v1/signing/decline { "reason": "…" } met fin à l’enveloppe (envelope.declined).

C’est au tour du destinataire seulement quand tous les groupes d’acheminement précédents ont terminé; avant cela, la vue indique canSign: false, et une soumission répond 409 not-your-turn.

Vérification du signataire

Chaque destinataire a une méthode de verification : celle du rôle (définie dans le panneau des rôles de l’éditeur de modèles), sauf si l’enveloppe la remplace pour ce destinataire (dans l’écran d’envoi, ou avec recipients[].verification).

Méthode	Ce que fait le signataire	Quand l’utiliser
none (par défaut)	Ouvre le lien de signature unique et signe	Le lien lui est envoyé par courriel : seule une personne qui a accès à cette boîte de réception le détient
email_otp	Ouvre le lien, puis saisit un code à six chiffres envoyé par courriel à la même adresse	Vous voulez une deuxième preuve, récente, au moment de la signature (contrats à forte valeur, boîtes de réception partagées)
integrator_asserted	Signe dans votre produit, qui atteste de son identité (externalUserId)	Signature intégrée derrière votre propre système de connexion

none est la valeur par défaut parce que le lien que Bona Fide envoie par courriel est lui-même propre au destinataire et impossible à deviner : l’ouvrir démontre le contrôle de l’adresse courriel, et c’est sur cette attribution que reposent les lois sur la signature électronique (ESIGN / UETA aux États-Unis, signature électronique simple au sens d’eIDAS). Les produits comparables l’utilisent aussi par défaut. Les modèles publiés avec email_otp le conservent, et un email_otp explicite continue de fonctionner partout.

Deux parcours ne reposent jamais sur un lien seul :

• Les liens de signature permanents (/l/…) : le visiteur saisit lui-même son adresse; il confirme donc toujours un code envoyé par courriel avant la création d’une enveloppe, quelle que soit la configuration du modèle.
• Les sessions que vous créez (POST /v1/envelopes/{id}/sessions) n’apportent aucune preuve de l’adresse courriel : c’est le rôle de votre système de connexion; utilisez donc integrator_asserted (avec externalUserId) ou email_otp pour ces sessions.

Le certificat de finalisation consigne, pour chaque signataire, ce qui a réellement été utilisé :

Consigné comme	Quand
Lien par courriel (lien unique envoyé à adresse)	none, signé à partir du lien reçu par courriel
Lien par courriel + code à usage unique (envoyé à adresse)	email_otp, signé à partir du lien reçu par courriel
Lien de signature + code à usage unique (envoyé à adresse)	Un visiteur d’un lien permanent
Code à usage unique (envoyé à adresse)	email_otp dans une session que vous avez créée
Session de signature émise par l’expéditeur	none dans une session que vous avez créée
Attestation de l’intégrateur	integrator_asserted

Le résumé de vérification public affiche les mêmes libellés, sans l’adresse.

Langues

La page de signature, ses courriels (demande, rappels, codes, finalisation, annulation), la page des liens permanents et la page d’état des observateurs sont offertes en 50 langues. Le signataire les voit selon cet ordre de préférence :

1. la langue qu’il a choisie dans le menu des langues de la page (mémorisée sur cet appareil);
2. <bf-signing locale="…"> (signature intégrée) ou ?locale= sur un lien hébergé;
3. la locale du destinataire, définie à la création de l’enveloppe (recipients[].locale, ou locale sur l’enveloppe pour tous ceux qui n’ont pas la leur);
4. la langue de son navigateur.

Les courriels ont besoin d’une langue avant que quiconque ouvre une page : ils utilisent donc la locale du destinataire et sont en anglais sans elle. Les liens permanents envoient le courriel du code dans la langue affichée sur la page du visiteur.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

Les étiquettes proches sont acceptées et enregistrées sous la langue à laquelle elles correspondent (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); toute autre valeur provoque une erreur de validation. Les avis de consentement traduits précisent que le texte anglais prévaut, et le signataire peut l’afficher; la langue dans laquelle l’avis a été lu est enregistrée avec la signature (consentLocale dans l’événement d’audit recipient.signed).

Code	Langue	Nom natif
ar	Arabe	العربية	de droite à gauche
hy	Arménien	Հայերեն
bn	Bengali	বাংলা
bg	Bulgare	Български
zh-Hans	Chinois (simplifié)	简体中文
zh-Hant	Chinois (traditionnel)	繁體中文
hr	Croate	Hrvatski
cs	Tchèque	Čeština
da	Danois	Dansk
nl	Néerlandais	Nederlands
en-GB	Anglais (Royaume-Uni)	English (UK)
en-US	Anglais (États-Unis)	English (US)
et	Estonien	Eesti
fil	Filipino	Filipino
fi	Finnois	Suomi
fr	Français	Français
fr-CA	Français (Canada)	Français (Canada)
de	Allemand	Deutsch
el	Grec	Ελληνικά
he	Hébreu	עברית	de droite à gauche
hi	Hindi	हिन्दी
hu	Hongrois	Magyar
id	Indonésien	Bahasa Indonesia
it	Italien	Italiano
ja	Japonais	日本語
ko	Coréen	한국어
lv	Letton	Latviešu
lt	Lituanien	Lietuvių
ms	Malais	Bahasa Melayu
mr	Marathi	मराठी
nb	Norvégien	Norsk bokmål
fa	Persan (farsi)	فارسی	de droite à gauche
pl	Polonais	Polski
pt-BR	Portugais (Brésil)	Português (Brasil)
pt-PT	Portugais (Portugal)	Português (Portugal)
ro	Roumain	Română
ru	Russe	Русский
sr-Latn	Serbe (latin)	Srpski
sk	Slovaque	Slovenčina
sl	Slovène	Slovenščina
es-419	Espagnol (Amérique latine)	Español (Latinoamérica)
es-ES	Espagnol (Espagne)	Español (España)
sw	Swahili	Kiswahili
sv	Suédois	Svenska
te	Télougou	తెలుగు
th	Thaï	ไทย
tr	Turc	Türkçe
uk	Ukrainien	Українська
ur	Ourdou	اردو	de droite à gauche
vi	Vietnamien	Tiếng Việt

Liens de signature permanents

Un lien de signature est une URL permanente pour les contrats que de nombreuses personnes signent de la même façon : une renonciation, un contrat de travailleur autonome, les conditions d’un projet pilote. Chaque visiteur qui le remplit obtient sa propre enveloppe.

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

• visitorRole est le rôle de signataire que prend le visiteur. Les liens acceptent un visiteur et au plus un contresignataire : mode: "auto" contresigne automatiquement avec le sceau de la plateforme Bona Fide, mode: "person" achemine l’enveloppe à l’email indiqué. Tout autre rôle non CC n’aurait aucun destinataire : ces modèles sont donc refusés.
• Le visiteur saisit son nom, son adresse courriel et les variables du modèle, puis confirme un code envoyé par courriel avant que quoi que ce soit soit créé (POST /v1/links/{id}/start, puis POST /v1/links/{id}/verify).
• limits plafonne l’utilisation par adresse courriel par jour (3 par défaut), par IP par heure (20 par défaut), par jour au total et par domaine de courriel. Avec dedupe (activé par défaut), une adresse courriel qui a déjà signé reçoit 409 already-signed.
• PATCH /v1/signing-links/{id} suspend le lien (active: false), le réactive ou le fait passer à une version plus récente; la suppression d’un lien conserve les enveloppes qu’il a créées. Chaque utilisation émet signing_link.used.

Note

La page du visiteur se trouve à l’url du lien (https://sign.bonafidesign.com/l/lnk_…). GET /v1/links/{id} est la description publique qu’elle affiche : nom du modèle, champs du visiteur et variables qu’il remplit.