Sessions et liens de signature

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

Sessions de signature

La remise par e-mail crée les sessions pour vous (le lien figurant dans l’e-mail). Pour une signature intégrée ou remise par vos soins, créez-en une depuis votre backend :

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, pas terminé)
mode	embedded (par défaut) ou hosted. Les url hébergées sont de la forme …/s/<token>, vers lesquelles 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 valide, la session est consommée, et une session utilisée ou expirée répond 410 Gone. Créez-en une nouvelle à chaque affichage de votre page. Les sessions ne peuvent être créées que tant que l’enveloppe est sent, et l’annulation de l’enveloppe les clôt toutes.

Le parcours du signataire

La page de signature (et toute interface personnalisée construite 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 cookie n’intervient : le blocage des cookies tiers dans une iframe n’a donc aucune incidence.
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, information préalable du consommateur) et enregistre recipient.viewed la première fois. GET /v1/signing/document est le PDF à afficher.
3. Vérification (uniquement avec email_otp) : POST /v1/signing/otp envoie par e-mail un code à six chiffres (valable 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 lorsque la méthode du destinataire ne requiert pas de code.
4. Validation : POST /v1/signing/submit avec les values des champs (signatures dessinées, saisies ou importées), le consentement à l’information préalable et viewedDocumentHash : le SHA-256 du PDF exact qui a été affiché. Si le document a changé entre-temps, la validation est refusée (409).
5. Ou refus : POST /v1/signing/decline { "reason": "…" } met fin à l’enveloppe (envelope.declined).

Le destinataire n’a la main que lorsque tous les groupes d’acheminement précédents ont terminé ; auparavant, la vue contient canSign: false, et une validation reçoit la réponse 409 not-your-turn.

Vérification du signataire

Chaque destinataire possède 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	À utiliser quand
none (par défaut)	Ouvre le lien de signature unique et signe	Le lien lui est envoyé par e-mail : seule une personne ayant accès à cette boîte de réception le possède
email_otp	Ouvre le lien, puis saisit un code à six chiffres envoyé à la même adresse	Vous voulez une seconde preuve, récente, au moment de la signature (contrats à fort enjeu, boîtes partagées)
integrator_asserted	Signe dans votre produit, qui se porte garant de son identité (externalUserId)	Signature intégrée derrière votre propre système de connexion

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

Deux parcours ne reposent jamais sur un simple lien :

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

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

Consigné comme	Quand
Lien par e-mail (lien unique envoyé à adresse)	none, signé depuis le lien reçu par e-mail
Lien par e-mail + code à usage unique (envoyé à adresse)	email_otp, signé depuis le lien reçu par e-mail
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écapitulatif public de vérification affiche les mêmes libellés, sans l’adresse.

Langues

La page de signature, ses e-mails (demande, relances, codes, finalisation, annulation), la page des liens permanents et la page de suivi des observateurs sont disponibles en 50 langues. Un signataire les voit selon cet ordre de priorité :

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’en ont pas) ;
4. la langue de son navigateur.

Les e-mails ont besoin d’une langue avant que quiconque n’ouvre une page : ils utilisent donc la locale du destinataire et sont en anglais à défaut. Les liens permanents envoient l’e-mail contenant le 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 balises 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 est une erreur de validation. Les informations de consentement traduites précisent que le texte anglais fait foi, et le signataire peut basculer vers celui-ci ; la langue dans laquelle l’information a été lue 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 manière : une décharge, un contrat de prestataire, les conditions d’un projet pilote. Chaque visiteur qui va au bout du parcours 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 endossé par le visiteur. Les liens prennent en charge un visiteur et au plus un contresignataire : mode: "auto" contresigne automatiquement avec le cachet de la plateforme Bona Fide, mode: "person" achemine l’enveloppe vers l’email indiqué. Tout autre rôle hors copie n’aurait pas de destinataire : de tels modèles sont donc refusés.
• Le visiteur saisit son nom, son adresse e-mail et les variables du modèle, puis confirme un code reçu par e-mail avant que quoi que ce soit ne soit créé (POST /v1/links/{id}/start, puis POST /v1/links/{id}/verify).
• limits plafonne l’utilisation par adresse e-mail et par jour (3 par défaut), par IP et par heure (20 par défaut), par jour au total, et par domaine de messagerie. Avec dedupe (activé par défaut), une adresse e-mail qui a déjà signé reçoit 409 already-signed.
• PATCH /v1/signing-links/{id} met le lien en pause (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 renseigne.