Phiên ký và liên kết ký

Người nhận ký trên trang ký của Bona Fide: hoặc trang lưu trữ sẵn tại https://sign.bonafidesign.com/s/…, hoặc chính trang đó được nhúng vào sản phẩm của bạn bằng <bf-signing>. Người nhận không cần tài khoản. Thứ cho phép họ vào là một phiên ký.

Phiên ký

Phương thức gửi qua email tự tạo phiên cho bạn (liên kết trong email). Với việc ký nhúng hoặc tự chuyển liên kết, hãy tạo phiên từ backend của bạn:

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

Trường	Ghi chú
`recipient`	Một người nhận của phong bì vẫn còn có thể ký (không phải CC, chưa hoàn thành)
`mode`	`embedded` (mặc định) hoặc `hosted`. `url` của phiên lưu trữ sẵn có dạng `…/s/<token>`, để chuyển hướng đến hoặc tự gửi
`allowedOrigins`	Tối đa 10 origin được phép đặt trang nhúng trong khung
`returnUrl`	Nơi trang lưu trữ sẵn đưa người ký đến khi họ xong
`ttlSeconds`	Từ 60 đến 3600, mặc định 600

Phiên chỉ dùng một lần: khi người nhận gửi, phiên coi như đã dùng, và một phiên đã dùng hoặc đã hết hạn sẽ trả về 410 Gone. Hãy tạo phiên mới mỗi lần trang của bạn được kết xuất. Chỉ có thể tạo phiên khi phong bì ở trạng thái sent, và việc hủy phong bì sẽ kết thúc tất cả các phiên.

Những bước người ký trải qua

Trang ký (và mọi giao diện tùy chỉnh bạn xây dựng trên cùng API) đi theo các bước sau:

Trao đổi: POST /v1/signing/exchange { "token": "bfs_…" } trả về một token truy cập ngắn hạn (bfa_…) được giữ trong bộ nhớ. Không dùng cookie, nên việc chặn cookie của bên thứ ba không ảnh hưởng đến iframe.
Tải: GET /v1/signing/session trả về dữ liệu hiển thị cho người ký (tiêu đề phong bì, người gửi, vai trò và các trường của người nhận, giá trị điền sẵn, thông báo công bố cho người tiêu dùng) và ghi lại recipient.viewed ở lần đầu tiên. GET /v1/signing/document là tệp PDF để hiển thị.
Xác minh (chỉ với email_otp): POST /v1/signing/otp gửi email một mã sáu chữ số (10 phút) và POST /v1/signing/otp/verify kiểm tra mã. Mã sai trả về verified: false kèm số lần thử còn lại. Trường verification.verified của dữ liệu hiển thị đã là true khi phương thức của người nhận không cần mã.
Gửi: POST /v1/signing/submit với values của các trường (chữ ký được vẽ, gõ hoặc tải lên), sự đồng ý với thông báo công bố, và viewedDocumentHash: SHA-256 của đúng tệp PDF đã được hiển thị. Nếu tài liệu đã thay đổi kể từ đó, yêu cầu gửi bị từ chối (409).
Hoặc từ chối: POST /v1/signing/decline { "reason": "…" } kết thúc phong bì (envelope.declined).

Chỉ đến lượt người nhận khi mọi nhóm chuyển tiếp trước đó đã xong; trước đó dữ liệu hiển thị có canSign: false, và yêu cầu gửi sẽ nhận phản hồi 409 not-your-turn.

Xác minh người ký

Mỗi người nhận có một phương thức verification: phương thức của vai trò (đặt trong bảng vai trò của trình thiết kế mẫu), trừ khi phong bì ghi đè nó cho từng người nhận (màn hình gửi, hoặc recipients[].verification).

Phương thức	Người ký làm gì	Dùng khi
`none` (mặc định)	Mở liên kết ký duy nhất và ký	Liên kết được gửi email cho họ: chỉ người có quyền truy cập hộp thư đó mới có
`email_otp`	Mở liên kết, rồi nhập mã sáu chữ số được gửi email đến cùng địa chỉ	Bạn muốn có thêm một bằng chứng mới tại thời điểm ký (hợp đồng giá trị cao, hộp thư dùng chung)
`integrator_asserted`	Ký trong sản phẩm của bạn, nơi bảo đảm danh tính của họ (`externalUserId`)	Ký nhúng phía sau hệ thống đăng nhập của riêng bạn

none là mặc định vì liên kết Bona Fide gửi qua email vốn đã là duy nhất cho người nhận và không thể đoán được: việc mở nó cho thấy quyền kiểm soát địa chỉ email, đây là căn cứ quy kết mà luật chữ ký điện tử dựa vào (ESIGN / UETA ở Hoa Kỳ, chữ ký điện tử đơn giản theo eIDAS). Các sản phẩm tương tự cũng mặc định như vậy. Mẫu đã xuất bản với email_otp vẫn giữ phương thức đó, và email_otp được đặt tường minh vẫn tiếp tục hoạt động ở mọi nơi.

Có hai luồng không bao giờ chỉ dựa vào liên kết:

Liên kết ký luôn hoạt động (/l/…): khách truy cập tự nhập địa chỉ của mình, nên họ luôn xác nhận một mã gửi qua email trước khi phong bì được tạo, bất kể mẫu quy định thế nào.
Phiên do bạn tạo (POST /v1/envelopes/{id}/sessions) hoàn toàn không mang bằng chứng nào về địa chỉ email: đó là việc của hệ thống đăng nhập của bạn, vì vậy hãy dùng integrator_asserted (với externalUserId) hoặc email_otp cho các phiên này.

Chứng nhận hoàn tất ghi lại, cho từng người ký, phương thức thực sự đã được dùng:

Được ghi là	Khi
Liên kết email (liên kết duy nhất gửi đến địa chỉ)	`none`, ký từ liên kết trong email
Liên kết email + mã dùng một lần (gửi đến địa chỉ)	`email_otp`, ký từ liên kết trong email
Liên kết ký + mã dùng một lần (gửi đến địa chỉ)	Khách truy cập liên kết luôn hoạt động
Mã dùng một lần (gửi đến địa chỉ)	`email_otp` trong phiên do bạn tạo
Phiên ký do người gửi cấp	`none` trong phiên do bạn tạo
Xác nhận của bên tích hợp	`integrator_asserted`

Bản tóm tắt xác minh công khai hiển thị cùng các nhãn này nhưng không có địa chỉ.

Ngôn ngữ

Trang ký, các email của nó (yêu cầu, nhắc nhở, mã, hoàn tất, đã hủy), trang liên kết luôn hoạt động và trang trạng thái của người xem có sẵn bằng 50 ngôn ngữ. Người ký thấy chúng theo thứ tự ưu tiên sau:

ngôn ngữ họ chọn từ menu ngôn ngữ của trang (được ghi nhớ trên thiết bị đó);
<bf-signing locale="…"> (ký nhúng) hoặc ?locale= trên liên kết lưu trữ sẵn;
locale của người nhận, được đặt khi tạo phong bì (recipients[].locale, hoặc locale trên phong bì cho tất cả những ai không có ngôn ngữ riêng);
ngôn ngữ trình duyệt của họ.

Email cần có ngôn ngữ trước khi bất kỳ ai mở trang, nên email dùng locale của người nhận và là tiếng Anh nếu không có giá trị này. Liên kết luôn hoạt động gửi email chứa mã bằng ngôn ngữ mà trang của khách truy cập đang hiển thị.

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

Các thẻ gần đúng được chấp nhận và lưu thành ngôn ngữ tương ứng (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); mọi giá trị khác là lỗi xác thực dữ liệu. Các thông báo công bố về sự đồng ý đã được dịch đều ghi rõ rằng văn bản tiếng Anh được áp dụng, và người ký có thể chuyển sang văn bản đó; ngôn ngữ mà thông báo công bố được đọc sẽ được ghi lại cùng chữ ký (consentLocale trong sự kiện kiểm tra recipient.signed).

Mã	Ngôn ngữ	Tên bản địa
`ar`	Tiếng Ả Rập	العربية	từ phải sang trái
`hy`	Tiếng Armenia	Հայերեն
`bn`	Tiếng Bengal	বাংলা
`bg`	Tiếng Bulgaria	Български
`zh-Hans`	Tiếng Trung (Giản thể)	简体中文
`zh-Hant`	Tiếng Trung (Phồn thể)	繁體中文
`hr`	Tiếng Croatia	Hrvatski
`cs`	Tiếng Séc	Čeština
`da`	Tiếng Đan Mạch	Dansk
`nl`	Tiếng Hà Lan	Nederlands
`en-GB`	Tiếng Anh (Anh)	English (UK)
`en-US`	Tiếng Anh (Mỹ)	English (US)
`et`	Tiếng Estonia	Eesti
`fil`	Tiếng Philippines	Filipino
`fi`	Tiếng Phần Lan	Suomi
`fr`	Tiếng Pháp	Français
`fr-CA`	Tiếng Pháp (Canada)	Français (Canada)
`de`	Tiếng Đức	Deutsch
`el`	Tiếng Hy Lạp	Ελληνικά
`he`	Tiếng Do Thái	עברית	từ phải sang trái
`hi`	Tiếng Hindi	हिन्दी
`hu`	Tiếng Hungary	Magyar
`id`	Tiếng Indonesia	Bahasa Indonesia
`it`	Tiếng Ý	Italiano
`ja`	Tiếng Nhật	日本語
`ko`	Tiếng Hàn	한국어
`lv`	Tiếng Latvia	Latviešu
`lt`	Tiếng Litva	Lietuvių
`ms`	Tiếng Mã Lai	Bahasa Melayu
`mr`	Tiếng Marathi	मराठी
`nb`	Tiếng Na Uy	Norsk bokmål
`fa`	Tiếng Ba Tư (Farsi)	فارسی	từ phải sang trái
`pl`	Tiếng Ba Lan	Polski
`pt-BR`	Tiếng Bồ Đào Nha (Brazil)	Português (Brasil)
`pt-PT`	Tiếng Bồ Đào Nha (Bồ Đào Nha)	Português (Portugal)
`ro`	Tiếng Romania	Română
`ru`	Tiếng Nga	Русский
`sr-Latn`	Tiếng Serbia (Latinh)	Srpski
`sk`	Tiếng Slovakia	Slovenčina
`sl`	Tiếng Slovenia	Slovenščina
`es-419`	Tiếng Tây Ban Nha (Mỹ Latinh)	Español (Latinoamérica)
`es-ES`	Tiếng Tây Ban Nha (Tây Ban Nha)	Español (España)
`sw`	Tiếng Swahili	Kiswahili
`sv`	Tiếng Thụy Điển	Svenska
`te`	Tiếng Telugu	తెలుగు
`th`	Tiếng Thái	ไทย
`tr`	Tiếng Thổ Nhĩ Kỳ	Türkçe
`uk`	Tiếng Ukraina	Українська
`ur`	Tiếng Urdu	اردو	từ phải sang trái
`vi`	Tiếng Việt	Tiếng Việt

Liên kết ký luôn hoạt động

Một liên kết ký là URL cố định cho các hợp đồng mà nhiều người ký theo cùng một cách: bản miễn trừ trách nhiệm, hợp đồng với nhà thầu, điều khoản cho một chương trình thí điểm. Mỗi khách truy cập hoàn tất liên kết sẽ có phong bì riêng của mình.

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 là vai trò người ký mà khách truy cập đảm nhận. Liên kết hỗ trợ một khách truy cập và tối đa một người ký đối ứng: mode: "auto" tự động ký đối ứng bằng con dấu nền tảng Bona Fide, mode: "person" chuyển phong bì đến email được chỉ định. Mọi vai trò không phải CC khác sẽ không có người nhận, nên các mẫu như vậy bị từ chối.
Khách truy cập nhập tên, email và các biến của mẫu, rồi xác nhận mã gửi qua email trước khi bất cứ thứ gì được tạo (POST /v1/links/{id}/start, sau đó POST /v1/links/{id}/verify).
limits giới hạn mức sử dụng theo email mỗi ngày (mặc định 3), theo IP mỗi giờ (mặc định 20), tổng số mỗi ngày, và theo tên miền email. Với dedupe (mặc định bật), một địa chỉ email đã ký sẽ nhận 409 already-signed.
PATCH /v1/signing-links/{id} tạm dừng (active: false), tiếp tục hoặc chuyển liên kết sang phiên bản mới hơn; xóa một liên kết vẫn giữ lại các phong bì nó đã tạo. Mỗi lượt sử dụng phát ra signing_link.used.