Ga naar inhoud
bona fidedocs

Ondertekeningssessies & -links

Ontvangers ondertekenen op de ondertekeningspagina van Bona Fide: de gehoste pagina op https://sign.bonafidesign.com/s/…, of dezelfde pagina ingesloten in uw product met <bf-signing>. Ontvangers hebben geen account nodig. Wat hen toegang geeft, is een ondertekeningssessie.

Ondertekeningssessies

Section titled “Ondertekeningssessies”

Bij bezorging per e-mail worden sessies voor u aangemaakt (de link in de e-mail). Voor ingesloten ondertekening of ondertekening waarbij u zelf de link bezorgt, maakt u er een aan vanuit uw backend:

Terminal window
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"
}
Veld Opmerkingen
recipient Een ontvanger van de envelop die nog kan ondertekenen (geen CC, nog niet klaar)
mode embedded (standaard) of hosted. Gehoste url’s hebben de vorm …/s/<token>, om naar door te sturen of zelf te versturen
allowedOrigins Maximaal 10 origins die de ingesloten pagina in een frame mogen tonen
returnUrl Waar de gehoste pagina de ondertekenaar heen stuurt als die klaar is
ttlSeconds 60 tot 3600, standaard 600

Sessies zijn voor eenmalig gebruik: zodra de ontvanger heeft ingediend, is de sessie verbruikt, en een gebruikte of verlopen sessie antwoordt 410 Gone. Maak elke keer dat uw pagina rendert een nieuwe aan. Sessies kunnen alleen worden aangemaakt zolang de envelop de status sent heeft, en het intrekken van de envelop beëindigt ze allemaal.

Wat de ondertekenaar doorloopt

Section titled “Wat de ondertekenaar doorloopt”

De ondertekeningspagina (en elke eigen UI die u op dezelfde API bouwt) volgt deze stappen:

  1. Inwisselen: POST /v1/signing/exchange { "token": "bfs_…" } geeft een kortlevend toegangstoken (bfa_…) terug dat in het geheugen wordt bewaard. Er komen geen cookies aan te pas, dus het blokkeren van cookies van derden maakt in een iframe niet uit.
  2. Laden: GET /v1/signing/session geeft de weergave voor de ondertekenaar terug (titel van de envelop, afzender, rol en velden van de ontvanger, vooraf ingevulde waarden, de consumentenverklaring) en legt de eerste keer recipient.viewed vast. GET /v1/signing/document is de pdf die wordt getoond.
  3. Verifiëren (alleen met email_otp): POST /v1/signing/otp mailt een zescijferige code (10 minuten geldig) en POST /v1/signing/otp/verify controleert die. Een verkeerde code geeft verified: false terug met het aantal resterende pogingen. verification.verified in de weergave is al true als de methode van de ontvanger geen code vereist.
  4. Indienen: POST /v1/signing/submit met de values van de velden (handtekeningen getekend, getypt of geüpload), de toestemming voor de verklaring en viewedDocumentHash: de SHA-256 van precies de pdf die werd getoond. Als het document sindsdien is gewijzigd, wordt het indienen geweigerd (409).
  5. Of weigeren: POST /v1/signing/decline { "reason": "…" } beëindigt de envelop (envelope.declined).

De ontvanger is pas aan de beurt wanneer elke eerdere routeringsgroep klaar is; daarvoor bevat de weergave canSign: false en antwoordt indienen met 409 not-your-turn.

Verificatie van de ondertekenaar

Section titled “Verificatie van de ondertekenaar”

Elke ontvanger heeft een verification-methode: die van de rol (ingesteld in het rollenpaneel van de sjabloondesigner), tenzij de envelop die per ontvanger overschrijft (in het verzendscherm of met recipients[].verification).

Methode Wat de ondertekenaar doet Gebruik dit als
none (standaard) Opent de unieke ondertekeningslink en ondertekent De link naar hen wordt gemaild: alleen iemand met toegang tot die inbox heeft hem
email_otp Opent de link en voert daarna een zescijferige code in die naar hetzelfde adres is gemaild U een tweede, vers bewijs wilt op het moment van ondertekenen (contracten met een hoge waarde, gedeelde inboxen)
integrator_asserted Ondertekent in uw product, dat instaat voor wie de persoon is (externalUserId) Ingesloten ondertekening achter uw eigen login

none is de standaard omdat de link die Bona Fide mailt zelf uniek is voor de ontvanger en niet te raden valt: wie hem opent, toont aan dat die het e-mailadres beheert, en dat is de toerekening waarop wetten voor elektronische handtekeningen steunen (ESIGN / UETA in de VS, gewone elektronische handtekeningen onder eIDAS). Vergelijkbare producten gebruiken dit ook als standaard. Sjablonen die met email_otp zijn gepubliceerd, behouden dat, en een expliciete email_otp blijft overal werken.

Twee flows vertrouwen nooit alleen op een link:

  • Permanente ondertekeningslinks (/l/…): de bezoeker typt zelf een adres, dus bevestigt altijd een gemailde code voordat er een envelop wordt aangemaakt, wat het sjabloon ook zegt.
  • Sessies die u zelf aanmaakt (POST /v1/envelopes/{id}/sessions) bevatten helemaal geen bewijs van het e-mailadres: dat is de taak van uw login, dus gebruik daarvoor integrator_asserted (met externalUserId) of email_otp.

Het voltooiingscertificaat legt per ondertekenaar vast wat er daadwerkelijk is gebruikt:

Vastgelegd als Wanneer
E-maillink (unieke link verstuurd naar adres) none, ondertekend via de gemailde link
E-maillink + eenmalige code (verstuurd naar adres) email_otp, ondertekend via de gemailde link
Ondertekeningslink + eenmalige code (verstuurd naar adres) Een bezoeker van een permanente link
Eenmalige code (verstuurd naar adres) email_otp in een sessie die u hebt aangemaakt
Ondertekeningssessie uitgegeven door de afzender none in een sessie die u hebt aangemaakt
Verklaring van de integrator integrator_asserted

De openbare verificatiesamenvatting toont dezelfde labels zonder het adres.

Talen

Section titled “Talen”

De ondertekeningspagina, de bijbehorende e-mails (verzoek, herinneringen, codes, voltooid, ingetrokken), de pagina van de permanente link en de statuspagina voor meekijkers zijn beschikbaar in 50 talen. Een ondertekenaar ziet ze in deze volgorde van voorkeur:

  1. de taal die de persoon heeft gekozen in het taalmenu van de pagina (onthouden op dat apparaat);
  2. <bf-signing locale="…"> (ingesloten ondertekening) of ?locale= bij een gehoste link;
  3. de locale van de ontvanger, ingesteld bij het aanmaken van de envelop (recipients[].locale, of locale bij de envelop voor iedereen zonder eigen taal);
  4. de taal van de browser.

E-mails hebben een taal nodig voordat iemand een pagina opent, dus ze gebruiken de locale van de ontvanger en zijn zonder die instelling in het Engels. Permanente links versturen de e-mail met de code in de taal die de pagina van de bezoeker toont.

{
  "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" }
  ]
}

Verwante tags worden geaccepteerd en opgeslagen als de taal waar ze bij horen (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); al het andere is een validatiefout. Vertaalde toestemmingsverklaringen vermelden dat de Engelse tekst geldt, en de ondertekenaar kan naar die tekst overschakelen; de taal waarin de verklaring is gelezen, wordt met de handtekening vastgelegd (consentLocale in het auditevent recipient.signed).

Code Taal Eigen naam
ar Arabisch العربية van rechts naar links
hy Armeens Հայերեն
bn Bengaals বাংলা
bg Bulgaars Български
zh-Hans Chinees (vereenvoudigd) 简体中文
zh-Hant Chinees (traditioneel) 繁體中文
hr Kroatisch Hrvatski
cs Tsjechisch Čeština
da Deens Dansk
nl Nederlands Nederlands
en-GB Engels (VK) English (UK)
en-US Engels (VS) English (US)
et Estisch Eesti
fil Filipijns Filipino
fi Fins Suomi
fr Frans Français
fr-CA Frans (Canada) Français (Canada)
de Duits Deutsch
el Grieks Ελληνικά
he Hebreeuws עברית van rechts naar links
hi Hindi हिन्दी
hu Hongaars Magyar
id Indonesisch Bahasa Indonesia
it Italiaans Italiano
ja Japans 日本語
ko Koreaans 한국어
lv Lets Latviešu
lt Litouws Lietuvių
ms Maleis Bahasa Melayu
mr Marathi मराठी
nb Noors Norsk bokmål
fa Perzisch (Farsi) فارسی van rechts naar links
pl Pools Polski
pt-BR Portugees (Brazilië) Português (Brasil)
pt-PT Portugees (Portugal) Português (Portugal)
ro Roemeens Română
ru Russisch Русский
sr-Latn Servisch (Latijns schrift) Srpski
sk Slowaaks Slovenčina
sl Sloveens Slovenščina
es-419 Spaans (Latijns-Amerika) Español (Latinoamérica)
es-ES Spaans (Spanje) Español (España)
sw Swahili Kiswahili
sv Zweeds Svenska
te Telugu తెలుగు
th Thai ไทย
tr Turks Türkçe
uk Oekraïens Українська
ur Urdu اردو van rechts naar links
vi Vietnamees Tiếng Việt
Section titled “Permanente ondertekeningslinks”

Een ondertekeningslink is een permanente URL voor contracten die veel mensen op dezelfde manier ondertekenen: een vrijwaringsverklaring, een overeenkomst met een opdrachtnemer, voorwaarden voor een pilot. Elke bezoeker die de link doorloopt, krijgt een eigen envelop.

Terminal window
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 is de ondertekenaarsrol die de bezoeker aanneemt. Links ondersteunen één bezoeker en maximaal één medeondertekenaar: mode: "auto" ondertekent automatisch mee met het platformzegel van Bona Fide, mode: "person" routeert de envelop naar het opgegeven email. Elke andere niet-CC-rol zou geen ontvanger hebben, dus zulke sjablonen worden geweigerd.
  • De bezoeker vult naam, e-mailadres en de variabelen van het sjabloon in en bevestigt daarna een e-mailcode voordat er iets wordt aangemaakt (POST /v1/links/{id}/start, daarna POST /v1/links/{id}/verify).
  • limits beperkt het gebruik per e-mailadres per dag (standaard 3), per IP-adres per uur (standaard 20), per dag in totaal en per e-maildomein. Met dedupe (standaard aan) krijgt een e-mailadres dat al heeft ondertekend 409 already-signed.
  • PATCH /v1/signing-links/{id} pauzeert de link (active: false), hervat hem of zet hem over naar een nieuwere versie; bij het verwijderen van een link blijven de enveloppen die ermee zijn aangemaakt bestaan. Elk gebruik genereert signing_link.used.