Gå til indhold
bona fidedocs

Signeringssessioner og links

Modtagere underskriver på Bona Fides underskriftsside: enten den hostede side på https://sign.bonafidesign.com/s/… eller den samme side indlejret i dit produkt med <bf-signing>. Modtagere behøver ingen konto. Det, der giver dem adgang, er en signeringssession.

Signeringssessioner

Sektion kaldt “Signeringssessioner”

Levering pr. e-mail opretter sessioner for dig (linket i e-mailen). Til indlejret underskrift, eller når du selv leverer linkene, opretter du en fra din 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"
}
Felt Bemærkninger
recipient En modtager i kuverten, som stadig kan underskrive (ikke CC, ikke færdig)
mode embedded (standard) eller hosted. Hostede url’er er …/s/<token>, som du kan omdirigere til eller selv sende
allowedOrigins Op til 10 origins, der må vise den indlejrede side i en ramme
returnUrl Hvor den hostede side sender underskriveren hen, når vedkommende er færdig
ttlSeconds 60 til 3600, standard 600

Sessioner er til engangsbrug: når modtageren har indsendt, er sessionen brugt, og en brugt eller udløbet session svarer 410 Gone. Opret en ny, hver gang din side renderes. Sessioner kan kun oprettes, mens kuverten er sent, og hvis kuverten annulleres, ophører de alle.

Hvad underskriveren går igennem

Sektion kaldt “Hvad underskriveren går igennem”

Underskriftssiden (og enhver egen brugerflade, du bygger på det samme API) følger disse trin:

  1. Udveksling: POST /v1/signing/exchange { "token": "bfs_…" } returnerer et kortlivet adgangstoken (bfa_…), der holdes i hukommelsen. Der bruges ingen cookies, så blokering af tredjepartscookies betyder intet i en iframe.
  2. Indlæsning: GET /v1/signing/session returnerer underskrivervisningen (kuvertens titel, afsenderen, modtagerens rolle og felter, forudfyldte værdier, forbrugeroplysningerne) og registrerer recipient.viewed første gang. GET /v1/signing/document er den PDF, der skal vises.
  3. Verificering (kun med email_otp): POST /v1/signing/otp sender en sekscifret kode pr. e-mail (10 minutter), og POST /v1/signing/otp/verify tjekker den. En forkert kode returnerer verified: false med antallet af resterende forsøg. Visningens verification.verified er allerede true, når modtagerens metode ikke kræver kode.
  4. Indsendelse: POST /v1/signing/submit med felternes values (signaturer, der er tegnet, skrevet eller uploadet), samtykke til oplysningerne og viewedDocumentHash: SHA-256 af præcis den PDF, der blev vist. Hvis dokumentet er ændret siden, afvises indsendelsen (409).
  5. Eller afvis: POST /v1/signing/decline { "reason": "…" } afslutter kuverten (envelope.declined).

Det er først modtagerens tur, når alle tidligere grupper i rækkefølgen er færdige; indtil da har visningen canSign: false, og en indsendelse svarer 409 not-your-turn.

Verificering af underskrivere

Sektion kaldt “Verificering af underskrivere”

Hver modtager har en verification-metode: rollens (angivet i rollepanelet i skabelondesigneren), medmindre kuverten tilsidesætter den pr. modtager (afsendelsesskærmen eller recipients[].verification).

Metode Hvad underskriveren gør Brug den, når
none (standard) Åbner det unikke underskriftslink og underskriver Linket sendes til vedkommende pr. e-mail: kun den, der har adgang til indbakken, har det
email_otp Åbner linket og indtaster derefter en sekscifret kode, der sendes til samme adresse Du vil have et ekstra, friskt bevis i selve underskriftsøjeblikket (kontrakter af høj værdi, delte indbakker)
integrator_asserted Underskriver i dit produkt, som indestår for, hvem vedkommende er (externalUserId) Indlejret underskrift bag dit eget login

none er standard, fordi det link, Bona Fide sender pr. e-mail, er unikt for modtageren og umuligt at gætte: at åbne det viser kontrol over e-mailadressen, hvilket er den tilknytning, som love om elektroniske signaturer bygger på (ESIGN / UETA i USA, simple elektroniske signaturer under eIDAS). Sammenlignelige produkter har også det som standard. Skabeloner, der er udgivet med email_otp, beholder det, og et udtrykkeligt email_otp virker fortsat overalt.

To forløb bygger aldrig alene på et link:

  • Permanente underskriftslinks (/l/…): den besøgende indtaster selv sin adresse og bekræfter derfor altid en kode pr. e-mail, før der oprettes en kuvert, uanset hvad skabelonen angiver.
  • Sessioner, du opretter (POST /v1/envelopes/{id}/sessions), indeholder slet intet bevis for e-mailadressen: det er dit logins opgave, så brug integrator_asserted (med externalUserId) eller email_otp til dem.

Fuldførelsescertifikatet registrerer pr. underskriver, hvad der faktisk blev brugt:

Registreres som Hvornår
E-maillink (unikt link sendt til adresse) none, underskrevet fra linket i e-mailen
E-maillink + engangskode (sendt til adresse) email_otp, underskrevet fra linket i e-mailen
Underskriftslink + engangskode (sendt til adresse) En besøgende via et permanent link
Engangskode (sendt til adresse) email_otp i en session, du har oprettet
Signeringssession udstedt af afsenderen none i en session, du har oprettet
Erklæring fra integratoren integrator_asserted

Den offentlige verificeringsoversigt viser de samme betegnelser uden adressen.

Sprog

Sektion kaldt “Sprog”

Underskriftssiden, dens e-mails (anmodning, påmindelser, koder, fuldført, annulleret), siden til permanente links og observatørernes statusside findes på 50 sprog. En underskriver ser dem i denne prioriterede rækkefølge:

  1. det sprog, vedkommende valgte i sidens sprogmenu (huskes på den enhed);
  2. <bf-signing locale="…"> (indlejret underskrift) eller ?locale= på et hostet link;
  3. modtagerens locale, angivet ved oprettelsen af kuverten (recipients[].locale, eller locale på kuverten for alle uden deres eget);
  4. browserens sprog.

E-mails skal have et sprog, før nogen åbner en side, så de bruger modtagerens locale og er på engelsk uden en. Permanente links sender kode-e-mailen på det sprog, den besøgendes side viser.

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

Nærtbeslægtede tags accepteres og gemmes som det sprog, de svarer til (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); alt andet er en valideringsfejl. Oversatte samtykkeoplysninger angiver, at den engelske tekst gælder, og underskriveren kan skifte til den; det sprog, oplysningerne blev læst på, registreres sammen med underskriften (consentLocale i revisionshændelsen recipient.signed).

Kode Sprog Navn på sproget
ar Arabisk العربية højre mod venstre
hy Armensk Հայերեն
bn Bengali বাংলা
bg Bulgarsk Български
zh-Hans Kinesisk (forenklet) 简体中文
zh-Hant Kinesisk (traditionelt) 繁體中文
hr Kroatisk Hrvatski
cs Tjekkisk Čeština
da Dansk Dansk
nl Nederlandsk Nederlands
en-GB Engelsk (Storbritannien) English (UK)
en-US Engelsk (USA) English (US)
et Estisk Eesti
fil Filippinsk Filipino
fi Finsk Suomi
fr Fransk Français
fr-CA Fransk (Canada) Français (Canada)
de Tysk Deutsch
el Græsk Ελληνικά
he Hebraisk עברית højre mod venstre
hi Hindi हिन्दी
hu Ungarsk Magyar
id Indonesisk Bahasa Indonesia
it Italiensk Italiano
ja Japansk 日本語
ko Koreansk 한국어
lv Lettisk Latviešu
lt Litauisk Lietuvių
ms Malajisk Bahasa Melayu
mr Marathi मराठी
nb Norsk Norsk bokmål
fa Persisk (farsi) فارسی højre mod venstre
pl Polsk Polski
pt-BR Portugisisk (Brasilien) Português (Brasil)
pt-PT Portugisisk (Portugal) Português (Portugal)
ro Rumænsk Română
ru Russisk Русский
sr-Latn Serbisk (latinsk skrift) Srpski
sk Slovakisk Slovenčina
sl Slovensk Slovenščina
es-419 Spansk (Latinamerika) Español (Latinoamérica)
es-ES Spansk (Spanien) Español (España)
sw Swahili Kiswahili
sv Svensk Svenska
te Telugu తెలుగు
th Thai ไทย
tr Tyrkisk Türkçe
uk Ukrainsk Українська
ur Urdu اردو højre mod venstre
vi Vietnamesisk Tiếng Việt
Sektion kaldt “Permanente underskriftslinks”

Et underskriftslink er en permanent URL til kontrakter, som mange underskriver på samme måde: en ansvarsfraskrivelse, en aftale med en freelancer, vilkår for et pilotprojekt. Hver besøgende, der fuldfører det, får sin egen kuvert.

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 er den underskriverrolle, den besøgende indtager. Links understøtter én besøgende og højst én medunderskriver: mode: "auto" medunderskriver automatisk med Bona Fide-platformens segl, mode: "person" sender kuverten videre til den angivne email. Alle andre roller, der ikke er CC, ville stå uden modtager, så sådanne skabeloner afvises.
  • Den besøgende indtaster sit navn, sin e-mail og skabelonens variabler og bekræfter derefter en kode pr. e-mail, før noget oprettes (POST /v1/links/{id}/start, derefter POST /v1/links/{id}/verify).
  • limits begrænser brugen pr. e-mail pr. dag (standard 3), pr. IP-adresse pr. time (standard 20), pr. dag i alt og efter e-maildomæne. Med dedupe (slået til som standard) får en e-mailadresse, der allerede har underskrevet, 409 already-signed.
  • PATCH /v1/signing-links/{id} sætter linket på pause (active: false), genoptager det eller flytter det til en nyere version; hvis et link slettes, bevares de kuverter, det har oprettet. Hver brug udsender signing_link.used.