Allekirjoitusistunnot ja -linkit

Vastaanottajat allekirjoittavat Bona Fiden allekirjoitussivulla: joko isännöidyllä sivulla osoitteessa https://sign.bonafidesign.com/s/… tai samalla sivulla upotettuna tuotteeseesi <bf-signing>-komponentilla. Vastaanottajat eivät tarvitse tiliä. Heidät päästää sisään allekirjoitusistunto.

Allekirjoitusistunnot

Sähköpostitoimitus luo istunnot puolestasi (sähköpostin linkki). Upotettua tai itse toimitettua allekirjoitusta varten luo istunto taustajärjestelmästäsi:

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

Kenttä	Huomautukset
`recipient`	Kirjekuoren vastaanottaja, joka voi vielä allekirjoittaa (ei CC, ei valmis)
`mode`	`embedded` (oletus) tai `hosted`. Isännöidyt `url`-osoitteet ovat muotoa `…/s/<token>`, ja niihin voi ohjata tai ne voi lähettää itse
`allowedOrigins`	Enintään 10 alkuperää, jotka saavat näyttää upotetun sivun kehyksessä
`returnUrl`	Minne isännöity sivu ohjaa allekirjoittajan, kun hän on valmis
`ttlSeconds`	60–3600, oletus 600

Istunnot ovat kertakäyttöisiä: kun vastaanottaja lähettää allekirjoituksen, istunto on käytetty, ja käytetty tai vanhentunut istunto vastaa 410 Gone. Luo uusi istunto aina, kun sivusi renderöidään. Istuntoja voi luoda vain, kun kirjekuoren tila on sent, ja kirjekuoren mitätöinti päättää ne kaikki.

Mitä allekirjoittaja käy läpi

Allekirjoitussivu (ja mikä tahansa samalle API:lle rakentamasi oma käyttöliittymä) noudattaa näitä vaiheita:

Vaihto: POST /v1/signing/exchange { "token": "bfs_…" } palauttaa lyhytikäisen käyttötunnuksen (bfa_…), jota säilytetään muistissa. Evästeitä ei käytetä, joten kolmannen osapuolen evästeiden esto ei haittaa iframessa.
Lataus: GET /v1/signing/session palauttaa allekirjoittajan näkymän (kirjekuoren otsikko, lähettäjä, vastaanottajan rooli ja kentät, esitäytetyt arvot, kuluttajalle annettavat tiedot) ja tallentaa recipient.viewed-tapahtuman ensimmäisellä kerralla. GET /v1/signing/document on näytettävä PDF.
Vahvistus (vain email_otp-menetelmällä): POST /v1/signing/otp lähettää kuusinumeroisen koodin sähköpostitse (10 minuuttia), ja POST /v1/signing/otp/verify tarkistaa sen. Väärä koodi palauttaa verified: false ja jäljellä olevat yritykset. Näkymän verification.verified on jo true, kun vastaanottajan menetelmä ei vaadi koodia.
Lähetys: POST /v1/signing/submit kenttien values-arvoilla (piirretyt, kirjoitetut tai ladatut allekirjoitukset), suostumuksella annettuihin tietoihin ja viewedDocumentHash-arvolla: täsmälleen näytetyn PDF:n SHA-256. Jos asiakirja on muuttunut sen jälkeen, lähetys hylätään (409).
Tai kieltäytyminen: POST /v1/signing/decline { "reason": "…" } päättää kirjekuoren (envelope.declined).

Vastaanottajan vuoro on vasta, kun kaikki aiemmat reititysryhmät ovat valmiita; sitä ennen näkymässä on canSign: false, ja lähetys vastaa 409 not-your-turn.

Allekirjoittajan vahvistus

Jokaisella vastaanottajalla on verification-menetelmä: roolin menetelmä (asetetaan mallieditorin roolipaneelissa), ellei kirjekuori ohita sitä vastaanottajakohtaisesti (lähetysnäkymässä tai recipients[].verification-kentällä).

Menetelmä	Mitä allekirjoittaja tekee	Käytä, kun
`none` (oletus)	Avaa yksilöllisen allekirjoituslinkin ja allekirjoittaa	Linkki lähetetään hänelle sähköpostitse: se on vain sillä, jolla on pääsy kyseiseen postilaatikkoon
`email_otp`	Avaa linkin ja syöttää sitten samaan osoitteeseen lähetetyn kuusinumeroisen koodin	Haluat toisen, tuoreen todisteen allekirjoitushetkellä (arvokkaat sopimukset, jaetut postilaatikot)
`integrator_asserted`	Allekirjoittaa tuotteessasi, joka takaa hänen henkilöllisyytensä (`externalUserId`)	Upotettu allekirjoitus oman kirjautumisesi takana

none on oletus, koska Bona Fiden sähköpostitse lähettämä linkki on itsessään vastaanottajakohtainen eikä sitä voi arvata: sen avaaminen osoittaa sähköpostiosoitteen hallinnan, ja siihen sähköisiä allekirjoituksia koskeva lainsäädäntö perustaa allekirjoituksen yhdistämisen henkilöön (ESIGN / UETA Yhdysvalloissa, eIDAS-asetuksen mukaiset yksinkertaiset sähköiset allekirjoitukset). Vastaavat tuotteet käyttävät myös tätä oletuksena. Mallit, jotka on julkaistu email_otp-menetelmällä, säilyttävät sen, ja nimenomaisesti määritetty email_otp toimii edelleen kaikkialla.

Kaksi työnkulkua ei koskaan luota pelkkään linkkiin:

Pysyvät allekirjoituslinkit (/l/…): vierailija kirjoittaa oman osoitteensa, joten hän vahvistaa aina sähköpostitse lähetetyn koodin ennen kirjekuoren luomista, sanoipa malli mitä tahansa.
Itse luomasi istunnot (POST /v1/envelopes/{id}/sessions) eivät sisällä mitään todistetta sähköpostiosoitteesta: se on kirjautumisesi tehtävä, joten käytä niille integrator_asserted (ja externalUserId) tai email_otp.

Valmistumistodistus tallentaa jokaisesta allekirjoittajasta, mitä todellisuudessa käytettiin:

Tallennetaan muodossa	Milloin
Sähköpostilinkki (yksilöllinen linkki lähetetty osoitteeseen osoite)	`none`, allekirjoitettu sähköpostin linkistä
Sähköpostilinkki + kertakäyttökoodi (lähetetty osoitteeseen osoite)	`email_otp`, allekirjoitettu sähköpostin linkistä
Allekirjoituslinkki + kertakäyttökoodi (lähetetty osoitteeseen osoite)	Pysyvän linkin vierailija
Kertakäyttökoodi (lähetetty osoitteeseen osoite)	`email_otp` itse luomassasi istunnossa
Lähettäjän myöntämä allekirjoitusistunto	`none` itse luomassasi istunnossa
Integraattorin vakuutus	`integrator_asserted`

Julkinen tarkistusyhteenveto näyttää samat merkinnät ilman osoitetta.

Kielet

Allekirjoitussivu, sen sähköpostit (pyyntö, muistutukset, koodit, valmis, mitätöity), pysyvän linkin sivu ja katselijan tilasivu ovat saatavilla 50 kielellä. Allekirjoittaja näkee ne tässä etusijajärjestyksessä:

kieli, jonka hän valitsi sivun kielivalikosta (muistetaan kyseisellä laitteella);
<bf-signing locale="…"> (upotettu allekirjoitus) tai ?locale= isännöidyssä linkissä;
vastaanottajan locale, joka asetetaan kirjekuorta luotaessa (recipients[].locale tai kirjekuoren locale kaikille, joilla ei ole omaa);
hänen selaimensa kieli.

Sähköposteille tarvitaan kieli ennen kuin kukaan avaa sivua, joten ne käyttävät vastaanottajan locale-arvoa ja ovat ilman sitä englanniksi. Pysyvät linkit lähettävät koodisähköpostin sillä kielellä, jota vierailijan sivu näyttää.

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

Läheiset kielitunnisteet hyväksytään ja tallennetaan kielenä, jota ne vastaavat (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); kaikki muu on validointivirhe. Käännetyissä suostumustiedoissa todetaan, että englanninkielistä tekstiä sovelletaan, ja allekirjoittaja voi vaihtaa siihen; kieli, jolla tiedot luettiin, tallennetaan allekirjoituksen yhteyteen (consentLocale kirjausketjun tapahtumassa recipient.signed).

Koodi	Kieli	Kielen oma nimi
`ar`	arabia	العربية	oikealta vasemmalle
`hy`	armenia	Հայերեն
`bn`	bengali	বাংলা
`bg`	bulgaria	Български
`zh-Hans`	kiina (yksinkertaistettu)	简体中文
`zh-Hant`	kiina (perinteinen)	繁體中文
`hr`	kroatia	Hrvatski
`cs`	tšekki	Čeština
`da`	tanska	Dansk
`nl`	hollanti	Nederlands
`en-GB`	englanti (Iso-Britannia)	English (UK)
`en-US`	englanti (Yhdysvallat)	English (US)
`et`	viro	Eesti
`fil`	filipino	Filipino
`fi`	suomi	Suomi
`fr`	ranska	Français
`fr-CA`	ranska (Kanada)	Français (Canada)
`de`	saksa	Deutsch
`el`	kreikka	Ελληνικά
`he`	heprea	עברית	oikealta vasemmalle
`hi`	hindi	हिन्दी
`hu`	unkari	Magyar
`id`	indonesia	Bahasa Indonesia
`it`	italia	Italiano
`ja`	japani	日本語
`ko`	korea	한국어
`lv`	latvia	Latviešu
`lt`	liettua	Lietuvių
`ms`	malaiji	Bahasa Melayu
`mr`	marathi	मराठी
`nb`	norja	Norsk bokmål
`fa`	persia (farsi)	فارسی	oikealta vasemmalle
`pl`	puola	Polski
`pt-BR`	portugali (Brasilia)	Português (Brasil)
`pt-PT`	portugali (Portugali)	Português (Portugal)
`ro`	romania	Română
`ru`	venäjä	Русский
`sr-Latn`	serbia (latinalainen)	Srpski
`sk`	slovakki	Slovenčina
`sl`	sloveeni	Slovenščina
`es-419`	espanja (Latinalainen Amerikka)	Español (Latinoamérica)
`es-ES`	espanja (Espanja)	Español (España)
`sw`	swahili	Kiswahili
`sv`	ruotsi	Svenska
`te`	telugu	తెలుగు
`th`	thai	ไทย
`tr`	turkki	Türkçe
`uk`	ukraina	Українська
`ur`	urdu	اردو	oikealta vasemmalle
`vi`	vietnam	Tiếng Việt

Pysyvät allekirjoituslinkit

Allekirjoituslinkki on pysyvä URL-osoite sopimuksille, jotka monet allekirjoittavat samalla tavalla: vastuuvapautuslomake, alihankkijasopimus, pilottihankkeen ehdot. Jokainen vierailija, joka viimeistelee sen, saa oman kirjekuorensa.

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 on allekirjoittajarooli, jonka vierailija saa. Linkit tukevat yhtä vierailijaa ja enintään yhtä vasta-allekirjoittajaa: mode: "auto" vasta-allekirjoittaa automaattisesti Bona Fide -alustan sinetillä, mode: "person" reitittää kirjekuoren annettuun email-osoitteeseen. Kaikilla muilla ei-CC-rooleilla ei olisi vastaanottajaa, joten tällaiset mallit hylätään.
Vierailija syöttää nimensä, sähköpostiosoitteensa ja mallin muuttujat ja vahvistaa sitten sähköpostikoodin ennen kuin mitään luodaan (POST /v1/links/{id}/start, sitten POST /v1/links/{id}/verify).
limits rajoittaa käyttöä sähköpostiosoitetta kohden päivässä (oletus 3), IP-osoitetta kohden tunnissa (oletus 20), päivässä kaikkiaan ja sähköpostin verkkotunnuksen mukaan. Kun dedupe on käytössä (oletuksena on), jo allekirjoittanut sähköpostiosoite saa vastauksen 409 already-signed.
PATCH /v1/signing-links/{id} keskeyttää linkin (active: false), jatkaa sitä tai siirtää sen uudempaan versioon; linkin poistaminen säilyttää sen luomat kirjekuoret. Jokainen käyttökerta lähettää tapahtuman signing_link.used.