Sesje i linki do podpisu

Odbiorcy podpisują na stronie podpisywania Bona Fide: na stronie hostowanej pod adresem https://sign.bonafidesign.com/s/… albo na tej samej stronie osadzonej w Twoim produkcie za pomocą <bf-signing>. Odbiorcy nie potrzebują konta. Dostęp daje im sesja podpisywania.

Sesje podpisywania

Przy dostarczaniu e-mailem sesje są tworzone automatycznie (link w wiadomości). Przy podpisywaniu osadzonym lub dostarczanym samodzielnie utwórz sesję w swoim backendzie:

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

Pole	Uwagi
`recipient`	Odbiorca koperty, który nadal może podpisać (nie CC, jeszcze nie zakończył)
`mode`	`embedded` (domyślnie) lub `hosted`. Hostowane `url` mają postać `…/s/<token>` – możesz pod nie przekierować lub wysłać je samodzielnie
`allowedOrigins`	Do 10 źródeł (origin), które mogą osadzić stronę w ramce
`returnUrl`	Dokąd hostowana strona przekierowuje osobę podpisującą po zakończeniu
`ttlSeconds`	Od 60 do 3600, domyślnie 600

Sesje są jednorazowe: gdy odbiorca prześle podpis, sesja zostaje zużyta, a sesja wykorzystana lub wygasła odpowiada 410 Gone. Twórz nową przy każdym renderowaniu strony. Sesje można tworzyć tylko wtedy, gdy koperta ma status sent, a unieważnienie koperty kończy je wszystkie.

Przebieg procesu po stronie osoby podpisującej

Strona podpisywania (i każdy własny interfejs zbudowany na tym samym API) wykonuje następujące kroki:

Wymiana: POST /v1/signing/exchange { "token": "bfs_…" } zwraca krótkotrwały token dostępu (bfa_…) przechowywany w pamięci. Pliki cookie nie są używane, więc blokowanie plików cookie stron trzecich w ramce iframe nie ma znaczenia.
Wczytanie: GET /v1/signing/session zwraca widok osoby podpisującej (tytuł koperty, nadawca, rola i pola odbiorcy, wstępnie wypełnione wartości, informacja dla konsumenta) i za pierwszym razem zapisuje recipient.viewed. GET /v1/signing/document to PDF do wyświetlenia.
Weryfikacja (tylko z email_otp): POST /v1/signing/otp wysyła e-mailem sześciocyfrowy kod (ważny 10 minut), a POST /v1/signing/otp/verify go sprawdza. Błędny kod zwraca verified: false wraz z liczbą pozostałych prób. verification.verified w widoku ma od razu wartość true, gdy metoda odbiorcy nie wymaga kodu.
Przesłanie: POST /v1/signing/submit z values pól (podpisy narysowane, wpisane lub przesłane), zgodą na treść informacji oraz viewedDocumentHash: SHA-256 dokładnie tego pliku PDF, który został wyświetlony. Jeśli dokument od tego czasu się zmienił, przesłanie jest odrzucane (409).
Albo odmowa: POST /v1/signing/decline { "reason": "…" } kończy kopertę (envelope.declined).

Kolej odbiorcy przypada dopiero wtedy, gdy wszystkie wcześniejsze grupy kierowania zakończyły działania; do tego czasu widok ma canSign: false, a przesłanie zwraca 409 not-your-turn.

Weryfikacja osoby podpisującej

Każdy odbiorca ma metodę verification: metodę swojej roli (ustawioną w panelu ról edytora szablonów), chyba że koperta nadpisuje ją dla danego odbiorcy (na ekranie wysyłki lub przez recipients[].verification).

Metoda	Co robi osoba podpisująca	Kiedy jej używać
`none` (domyślnie)	Otwiera unikalny link do podpisu i podpisuje	Link jest wysyłany e-mailem: ma go tylko ktoś z dostępem do tej skrzynki
`email_otp`	Otwiera link, a potem wpisuje sześciocyfrowy kod wysłany e-mailem na ten sam adres	Chcesz drugiego, świeżego dowodu w chwili podpisywania (umowy o wysokiej wartości, współdzielone skrzynki)
`integrator_asserted`	Podpisuje w Twoim produkcie, który poświadcza jej tożsamość (`externalUserId`)	Osadzone podpisywanie za Twoim własnym logowaniem

none jest metodą domyślną, ponieważ link, który wysyła Bona Fide, jest unikalny dla odbiorcy i niemożliwy do odgadnięcia: jego otwarcie wykazuje kontrolę nad adresem e-mail, a na takim przypisaniu opierają się przepisy o podpisach elektronicznych (ESIGN / UETA w USA, zwykłe podpisy elektroniczne w rozumieniu eIDAS). Porównywalne produkty również domyślnie z niej korzystają. Szablony opublikowane z email_otp ją zachowują, a jawnie ustawione email_otp nadal działa wszędzie.

Dwa procesy nigdy nie opierają się na samym linku:

Stałe linki do podpisu (/l/…): odwiedzający sam wpisuje swój adres, więc zawsze potwierdza kod wysłany e-mailem, zanim zostanie utworzona koperta, niezależnie od ustawień szablonu.
Sesje tworzone przez Ciebie (POST /v1/envelopes/{id}/sessions) nie niosą żadnego dowodu dotyczącego adresu e-mail: to zadanie Twojego logowania, więc używaj dla nich integrator_asserted (z externalUserId) lub email_otp.

Certyfikat ukończenia zapisuje dla każdej osoby podpisującej, czego faktycznie użyto:

Zapisywane jako	Kiedy
Link e-mail (unikalny link wysłany na adres)	`none`, podpisano z linku z wiadomości e-mail
Link e-mail + jednorazowy kod (wysłany na adres)	`email_otp`, podpisano z linku z wiadomości e-mail
Link do podpisu + jednorazowy kod (wysłany na adres)	Odwiedzający stały link
Jednorazowy kod (wysłany na adres)	`email_otp` w sesji utworzonej przez Ciebie
Sesja podpisywania wydana przez nadawcę	`none` w sesji utworzonej przez Ciebie
Poświadczenie integratora	`integrator_asserted`

Publiczne podsumowanie weryfikacji pokazuje te same etykiety bez adresu.

Języki

Strona podpisywania, wysyłane z niej wiadomości e-mail (prośba, przypomnienia, kody, zakończenie, unieważnienie), strona stałego linku i strona statusu obserwatora są dostępne w 50 językach. Osoba podpisująca widzi je w następującej kolejności preferencji:

język wybrany w menu językowym strony (zapamiętywany na tym urządzeniu);
<bf-signing locale="…"> (podpisywanie osadzone) lub ?locale= w hostowanym linku;
locale odbiorcy ustawione przy tworzeniu koperty (recipients[].locale lub locale w kopercie dla wszystkich bez własnego ustawienia);
język przeglądarki.

Wiadomości e-mail potrzebują języka, zanim ktokolwiek otworzy stronę, więc korzystają z locale odbiorcy, a bez niego są po angielsku. Stałe linki wysyłają wiadomość z kodem w języku, w którym wyświetlana jest strona odwiedzającego.

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

Pokrewne tagi są akceptowane i zapisywane jako język, któremu odpowiadają (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); każdy inny jest błędem walidacji. Przetłumaczone informacje o zgodzie zaznaczają, że obowiązuje tekst angielski, a osoba podpisująca może się na niego przełączyć; język, w którym przeczytano informację, jest zapisywany wraz z podpisem (consentLocale w zdarzeniu audytu recipient.signed).

Kod	Język	Nazwa własna
`ar`	arabski	العربية	od prawej do lewej
`hy`	ormiański	Հայերեն
`bn`	bengalski	বাংলা
`bg`	bułgarski	Български
`zh-Hans`	chiński (uproszczony)	简体中文
`zh-Hant`	chiński (tradycyjny)	繁體中文
`hr`	chorwacki	Hrvatski
`cs`	czeski	Čeština
`da`	duński	Dansk
`nl`	niderlandzki	Nederlands
`en-GB`	angielski (Wielka Brytania)	English (UK)
`en-US`	angielski (USA)	English (US)
`et`	estoński	Eesti
`fil`	filipiński	Filipino
`fi`	fiński	Suomi
`fr`	francuski	Français
`fr-CA`	francuski (Kanada)	Français (Canada)
`de`	niemiecki	Deutsch
`el`	grecki	Ελληνικά
`he`	hebrajski	עברית	od prawej do lewej
`hi`	hindi	हिन्दी
`hu`	węgierski	Magyar
`id`	indonezyjski	Bahasa Indonesia
`it`	włoski	Italiano
`ja`	japoński	日本語
`ko`	koreański	한국어
`lv`	łotewski	Latviešu
`lt`	litewski	Lietuvių
`ms`	malajski	Bahasa Melayu
`mr`	marathi	मराठी
`nb`	norweski	Norsk bokmål
`fa`	perski (farsi)	فارسی	od prawej do lewej
`pl`	polski	Polski
`pt-BR`	portugalski (Brazylia)	Português (Brasil)
`pt-PT`	portugalski (Portugalia)	Português (Portugal)
`ro`	rumuński	Română
`ru`	rosyjski	Русский
`sr-Latn`	serbski (łaciński)	Srpski
`sk`	słowacki	Slovenčina
`sl`	słoweński	Slovenščina
`es-419`	hiszpański (Ameryka Łacińska)	Español (Latinoamérica)
`es-ES`	hiszpański (Hiszpania)	Español (España)
`sw`	suahili	Kiswahili
`sv`	szwedzki	Svenska
`te`	telugu	తెలుగు
`th`	tajski	ไทย
`tr`	turecki	Türkçe
`uk`	ukraiński	Українська
`ur`	urdu	اردو	od prawej do lewej
`vi`	wietnamski	Tiếng Việt

Stałe linki do podpisu

Link do podpisu to stały adres URL dla umów, które wiele osób podpisuje w ten sam sposób: oświadczenie o zrzeczeniu się roszczeń, umowa z wykonawcą, warunki programu pilotażowego. Każdy odwiedzający, który go ukończy, otrzymuje własną kopertę.

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 to rola osoby podpisującej, którą przyjmuje odwiedzający. Linki obsługują jednego odwiedzającego i najwyżej jedną osobę kontrasygnującą: mode: "auto" kontrasygnuje automatycznie pieczęcią platformy Bona Fide, a mode: "person" kieruje kopertę na podany email. Każda inna rola niż CC nie miałaby odbiorcy, dlatego takie szablony są odrzucane.
Odwiedzający wpisuje imię i nazwisko, adres e-mail oraz zmienne szablonu, a następnie potwierdza kod z wiadomości e-mail, zanim cokolwiek zostanie utworzone (POST /v1/links/{id}/start, potem POST /v1/links/{id}/verify).
limits ogranicza użycie na adres e-mail dziennie (domyślnie 3), na adres IP na godzinę (domyślnie 20), łącznie na dzień oraz według domeny e-mail. Przy dedupe (domyślnie włączone) adres e-mail, który już podpisał, otrzymuje 409 already-signed.
PATCH /v1/signing-links/{id} wstrzymuje link (active: false), wznawia go lub przenosi na nowszą wersję; usunięcie linku zachowuje utworzone przez niego koperty. Każde użycie emituje signing_link.used.