Hoppa till innehåll
bona fidedocs

Signeringssessioner och länkar

Mottagare signerar på Bona Fides signeringssida: antingen den hostade sidan på https://sign.bonafidesign.com/s/… eller samma sida inbäddad i din produkt med <bf-signing>. Mottagare behöver inget konto. Det som släpper in dem är en signeringssession.

Signeringssessioner

Section titled “Signeringssessioner”

Leverans via e-post skapar sessioner åt dig (länken i mejlet). För inbäddad signering eller när du själv levererar länkarna skapar du en från 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"
}
Fält Kommentar
recipient En mottagare i kuvertet som fortfarande kan signera (inte CC, inte klar)
mode embedded (standard) eller hosted. Hostade url:er är …/s/<token>, att omdirigera till eller skicka själv
allowedOrigins Upp till 10 ursprung som får rama in den inbäddade sidan
returnUrl Dit den hostade sidan skickar undertecknaren när hen är klar
ttlSeconds 60 till 3600, standard 600

Sessioner är för engångsbruk: när mottagaren har skickat in är sessionen förbrukad, och en använd eller utgången session svarar 410 Gone. Skapa en ny varje gång din sida renderas. Sessioner kan bara skapas medan kuvertet är sent, och om kuvertet makuleras upphör alla sessioner.

Vad undertecknaren går igenom

Section titled “Vad undertecknaren går igenom”

Signeringssidan (och alla egna gränssnitt som du bygger på samma API) följer dessa steg:

  1. Byte: POST /v1/signing/exchange { "token": "bfs_…" } returnerar en kortlivad åtkomsttoken (bfa_…) som hålls i minnet. Inga cookies används, så blockering av tredjepartscookies spelar ingen roll i en iframe.
  2. Inläsning: GET /v1/signing/session returnerar undertecknarvyn (kuvertets titel, avsändaren, mottagarens roll och fält, förifyllda värden, konsumentinformationen) och registrerar recipient.viewed första gången. GET /v1/signing/document är den PDF som ska visas.
  3. Verifiering (bara med email_otp): POST /v1/signing/otp mejlar en sexsiffrig kod (10 minuter) och POST /v1/signing/otp/verify kontrollerar den. En felaktig kod returnerar verified: false med antalet återstående försök. Vyns verification.verified är redan true när mottagarens metod inte kräver någon kod.
  4. Inskickning: POST /v1/signing/submit med fältens values (signaturer som ritats, skrivits eller laddats upp), samtycke till informationen och viewedDocumentHash: SHA-256 för exakt den PDF som visades. Om dokumentet har ändrats sedan dess nekas inskickningen (409).
  5. Eller avböj: POST /v1/signing/decline { "reason": "…" } avslutar kuvertet (envelope.declined).

Det är mottagarens tur först när alla tidigare dirigeringsgrupper är klara; innan dess har vyn canSign: false, och en inskickning svarar 409 not-your-turn.

Verifiering av undertecknare

Section titled “Verifiering av undertecknare”

Varje mottagare har en verification-metod: rollens (anges i rollpanelen i malldesignern) om inte kuvertet åsidosätter den per mottagare (utskicksskärmen eller recipients[].verification).

Metod Vad undertecknaren gör Använd den när
none (standard) Öppnar den unika signeringslänken och signerar Länken mejlas till personen: bara den som har åtkomst till inkorgen har den
email_otp Öppnar länken och anger sedan en sexsiffrig kod som mejlas till samma adress Du vill ha ett andra, färskt bevis i samma ögonblick som signeringen (avtal med högt värde, delade inkorgar)
integrator_asserted Signerar i din produkt, som går i god för vem personen är (externalUserId) Inbäddad signering bakom din egen inloggning

none är standard eftersom länken som Bona Fide mejlar är unik för mottagaren och omöjlig att gissa: att öppna den visar kontroll över e-postadressen, vilket är den tillskrivning som lagar om elektroniska signaturer bygger på (ESIGN / UETA i USA, enkla elektroniska signaturer enligt eIDAS). Jämförbara produkter har också det som standard. Mallar som publicerats med email_otp behåller det, och ett uttryckligt email_otp fortsätter att fungera överallt.

Två flöden förlitar sig aldrig enbart på en länk:

  • Permanenta signeringslänkar (/l/…): besökaren skriver själv in sin adress, så hen bekräftar alltid en kod via e-post innan ett kuvert skapas, oavsett vad mallen anger.
  • Sessioner som du skapar (POST /v1/envelopes/{id}/sessions) innehåller inget bevis alls för e-postadressen: det är din inloggnings uppgift, så använd integrator_asserted (med externalUserId) eller email_otp för dem.

Slutförandecertifikatet registrerar per undertecknare vad som faktiskt användes:

Registreras som När
E-postlänk (unik länk skickad till adress) none, signerat från länken i mejlet
E-postlänk + engångskod (skickad till adress) email_otp, signerat från länken i mejlet
Signeringslänk + engångskod (skickad till adress) En besökare via en permanent länk
Engångskod (skickad till adress) email_otp i en session som du skapade
Signeringssession utfärdad av avsändaren none i en session som du skapade
Intygande från integratören integrator_asserted

Den offentliga verifieringssammanfattningen visar samma etiketter utan adressen.

Språk

Section titled “Språk”

Signeringssidan, dess mejl (begäran, påminnelser, koder, slutfört, makulerat), sidan för permanenta länkar och observatörernas statussida finns på 50 språk. En undertecknare ser dem i den här prioritetsordningen:

  1. det språk hen valde i sidans språkmeny (sparas på den enheten);
  2. <bf-signing locale="…"> (inbäddad signering) eller ?locale= på en hostad länk;
  3. mottagarens locale, som anges när kuvertet skapas (recipients[].locale, eller locale på kuvertet för alla som inte har ett eget);
  4. webbläsarens språk.

Mejl behöver ett språk innan någon öppnar en sida, så de använder mottagarens locale och är på engelska om det saknas. Permanenta länkar skickar kodmejlet på det språk som besökarens sida visar.

{
  "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ärliggande taggar accepteras och lagras som det språk de motsvarar (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); allt annat är ett valideringsfel. Översatt samtyckesinformation anger att den engelska texten gäller, och undertecknaren kan byta till den; det språk som informationen lästes på registreras med signaturen (consentLocale i granskningshändelsen recipient.signed).

Kod Språk Namn på språket
ar Arabiska العربية höger till vänster
hy Armeniska Հայերեն
bn Bengali বাংলা
bg Bulgariska Български
zh-Hans Kinesiska (förenklad) 简体中文
zh-Hant Kinesiska (traditionell) 繁體中文
hr Kroatiska Hrvatski
cs Tjeckiska Čeština
da Danska Dansk
nl Nederländska Nederlands
en-GB Engelska (Storbritannien) English (UK)
en-US Engelska (USA) English (US)
et Estniska Eesti
fil Filippinska Filipino
fi Finska Suomi
fr Franska Français
fr-CA Franska (Kanada) Français (Canada)
de Tyska Deutsch
el Grekiska Ελληνικά
he Hebreiska עברית höger till vänster
hi Hindi हिन्दी
hu Ungerska Magyar
id Indonesiska Bahasa Indonesia
it Italienska Italiano
ja Japanska 日本語
ko Koreanska 한국어
lv Lettiska Latviešu
lt Litauiska Lietuvių
ms Malajiska Bahasa Melayu
mr Marathi मराठी
nb Norska Norsk bokmål
fa Persiska (farsi) فارسی höger till vänster
pl Polska Polski
pt-BR Portugisiska (Brasilien) Português (Brasil)
pt-PT Portugisiska (Portugal) Português (Portugal)
ro Rumänska Română
ru Ryska Русский
sr-Latn Serbiska (latinskt alfabet) Srpski
sk Slovakiska Slovenčina
sl Slovenska Slovenščina
es-419 Spanska (Latinamerika) Español (Latinoamérica)
es-ES Spanska (Spanien) Español (España)
sw Swahili Kiswahili
sv Svenska Svenska
te Telugu తెలుగు
th Thailändska ไทย
tr Turkiska Türkçe
uk Ukrainska Українська
ur Urdu اردو höger till vänster
vi Vietnamesiska Tiếng Việt

Permanenta signeringslänkar

Section titled “Permanenta signeringslänkar”

En signeringslänk är en permanent URL för avtal som många signerar på samma sätt: en ansvarsfriskrivning, ett konsultavtal, villkor för ett pilotprojekt. Varje besökare som slutför den får sitt eget 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 är den undertecknarroll som besökaren tar. Länkar stöder en besökare och högst en kontrasignerare: mode: "auto" kontrasignerar automatiskt med Bona Fide-plattformens försegling, mode: "person" dirigerar kuvertet till angiven email. Alla andra roller som inte är CC skulle sakna mottagare, så sådana mallar nekas.
  • Besökaren anger sitt namn, sin e-postadress och mallens variabler och bekräftar sedan en kod via e-post innan något skapas (POST /v1/links/{id}/start, sedan POST /v1/links/{id}/verify).
  • limits begränsar användningen per e-postadress och dag (standard 3), per IP-adress och timme (standard 20), per dag totalt och per e-postdomän. Med dedupe (aktiverat som standard) får en e-postadress som redan har signerat 409 already-signed.
  • PATCH /v1/signing-links/{id} pausar (active: false) eller återupptar länken eller flyttar den till en nyare version; om en länk tas bort behålls de kuvert den har skapat. Varje användning genererar signing_link.used.