Gå til innholdet
bona fidedocs

Signeringsøkter og -lenker

Mottakere signerer på Bona Fides signeringsside: enten den hostede siden på https://sign.bonafidesign.com/s/…, eller den samme siden innebygd i produktet ditt med <bf-signing>. Mottakere trenger ikke konto. Det som slipper dem inn, er en signeringsøkt.

Signeringsøkter

Section titled “Signeringsøkter”

Levering på e-post oppretter økter for deg (lenken i e-posten). For innebygd signering eller signering du leverer selv, oppretter du en fra backenden din:

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 Merknader
recipient En mottaker i konvolutten som fortsatt kan signere (ikke CC, ikke ferdig)
mode embedded (standard) eller hosted. Hostede url-er er …/s/<token>, til å videresende til eller sende selv
allowedOrigins Opptil 10 opprinnelser som kan vise den innebygde siden i en ramme
returnUrl Hvor den hostede siden sender signataren når de er ferdige
ttlSeconds 60 til 3600, standard 600

Økter er til engangsbruk: når mottakeren sender inn, er økten brukt opp, og en brukt eller utløpt økt svarer 410 Gone. Opprett en ny hver gang siden din rendres. Økter kan bare opprettes mens konvolutten er sent, og annullering av konvolutten avslutter alle.

Hva signataren går gjennom

Section titled “Hva signataren går gjennom”

Signeringssiden (og ethvert eget grensesnitt du bygger på det samme API-et) følger disse stegene:

  1. Bytt: POST /v1/signing/exchange { "token": "bfs_…" } returnerer et kortlivet tilgangstoken (bfa_…) som holdes i minnet. Ingen cookies er involvert, så blokkering av tredjepartscookies spiller ingen rolle i en iframe.
  2. Last inn: GET /v1/signing/session returnerer signatarvisningen (konvoluttens tittel, avsender, mottakerens rolle og felt, forhåndsutfylte verdier, forbrukerinformasjonen) og registrerer recipient.viewed første gang. GET /v1/signing/document er PDF-en som skal vises.
  3. Bekreft (bare med email_otp): POST /v1/signing/otp sender en sekssifret kode på e-post (10 minutter), og POST /v1/signing/otp/verify kontrollerer den. En feil kode returnerer verified: false med gjenværende forsøk. Visningens verification.verified er allerede true når mottakerens metode ikke krever kode.
  4. Send inn: POST /v1/signing/submit med feltenes values (signaturer tegnet, skrevet eller lastet opp), samtykke til informasjonen og viewedDocumentHash: SHA-256 av nøyaktig den PDF-en som ble vist. Hvis dokumentet er endret siden, avvises innsendingen (409).
  5. Eller avslå: POST /v1/signing/decline { "reason": "…" } avslutter konvolutten (envelope.declined).

Det er mottakerens tur først når alle tidligere rutinggrupper er ferdige; før det har visningen canSign: false, og en innsending svarer 409 not-your-turn.

Verifisering av signatarer

Section titled “Verifisering av signatarer”

Hver mottaker har en verification-metode: rollens (angitt i rollepanelet i maldesigneren) med mindre konvolutten overstyrer den per mottaker (sendeskjermen, eller recipients[].verification).

Metode Hva signataren gjør Bruk den når
none (standard) Åpner den unike signeringslenken og signerer Lenken sendes til dem på e-post: bare noen med tilgang til den innboksen har den
email_otp Åpner lenken og skriver deretter inn en sekssifret kode sendt på e-post til samme adresse Du vil ha et ekstra, ferskt bevis i signeringsøyeblikket (kontrakter med høy verdi, delte innbokser)
integrator_asserted Signerer i produktet ditt, som går god for hvem de er (externalUserId) Innebygd signering bak din egen innlogging

none er standard fordi lenken Bona Fide sender på e-post, i seg selv er unik for mottakeren og ikke kan gjettes: å åpne den viser kontroll over e-postadressen, og det er den tilknytningen lover om elektroniske signaturer bygger på (ESIGN / UETA i USA, enkle elektroniske signaturer etter eIDAS). Sammenlignbare produkter bruker også dette som standard. Maler som er publisert med email_otp, beholder det, og en eksplisitt email_otp fortsetter å virke overalt.

To flyter er aldri avhengige av en lenke alene:

  • Faste signeringslenker (/l/…): den besøkende skriver inn sin egen adresse, så de bekrefter alltid en kode på e-post før en konvolutt opprettes, uansett hva malen sier.
  • Økter du oppretter (POST /v1/envelopes/{id}/sessions) har ikke noe bevis for e-postadressen i det hele tatt: det er innloggingen din sin jobb, så bruk integrator_asserted (med externalUserId) eller email_otp for dem.

Fullføringssertifikatet registrerer per signatar hva som faktisk ble brukt:

Registrert som Når
E-postlenke (unik lenke sendt til adresse) none, signert fra lenken i e-posten
E-postlenke + engangskode (sendt til adresse) email_otp, signert fra lenken i e-posten
Signeringslenke + engangskode (sendt til adresse) En besøkende på en fast lenke
Engangskode (sendt til adresse) email_otp i en økt du opprettet
Signeringsøkt utstedt av avsenderen none i en økt du opprettet
Bekreftelse fra integratoren integrator_asserted

Det offentlige verifiseringssammendraget viser de samme betegnelsene uten adressen.

Språk

Section titled “Språk”

Signeringssiden, e-postene (forespørsel, påminnelser, koder, fullført, annullert), siden for faste lenker og observatørenes statusside er tilgjengelige på 50 språk. En signatar ser dem i denne prioriteringsrekkefølgen:

  1. språket de valgte i sidens språkmeny (huskes på den enheten);
  2. <bf-signing locale="…"> (innebygd signering) eller ?locale= på en hostet lenke;
  3. mottakerens locale, angitt når konvolutten opprettes (recipients[].locale, eller locale på konvolutten for alle som ikke har sin egen);
  4. nettleserens språk.

E-poster trenger et språk før noen åpner en side, så de bruker mottakerens locale og er på engelsk uten den. Faste lenker sender e-posten med koden på det språket den besøkendes 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ærliggende språkkoder godtas og lagres som språket de tilsvarer (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); alt annet er en valideringsfeil. Oversatt samtykkeinformasjon opplyser om at den engelske teksten gjelder, og signataren kan bytte til den; språket informasjonen ble lest på, registreres sammen med signaturen (consentLocale i revisjonshendelsen recipient.signed).

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

Faste signeringslenker

Section titled “Faste signeringslenker”

En signeringslenke er en permanent URL for kontrakter som mange signerer på samme måte: en ansvarsfraskrivelse, en avtale med en oppdragstaker, vilkår for et pilotprosjekt. Hver besøkende som fullfører den, får sin egen konvolutt.

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 signatarrollen den besøkende får. Lenker støtter én besøkende og høyst én medsignatar: mode: "auto" medsignerer automatisk med Bona Fide-plattformens segl, mode: "person" ruter konvolutten til den oppgitte email. Alle andre roller som ikke er CC, ville stått uten mottaker, så slike maler avvises.
  • Den besøkende skriver inn navn, e-postadresse og malens variabler og bekrefter deretter en kode på e-post før noe opprettes (POST /v1/links/{id}/start, deretter POST /v1/links/{id}/verify).
  • limits begrenser bruken per e-postadresse per dag (standard 3), per IP-adresse per time (standard 20), per dag totalt og etter e-postdomene. Med dedupe (standard på) får en e-postadresse som allerede har signert, 409 already-signed.
  • PATCH /v1/signing-links/{id} setter lenken på pause (active: false), gjenopptar den eller flytter den til en nyere versjon; sletter du en lenke, beholdes konvoluttene den har opprettet. Hver bruk sender ut signing_link.used.