Bỏ qua để đến nội dung
bona fidedocs

Mẫu, vai trò và trường

Một mẫu là một hợp đồng có thể dùng lại. Mẫu có tên, một bản nháp duy nhất và số lượng bất kỳ phiên bản đã xuất bản. Phong bì luôn được tạo từ một phiên bản đã xuất bản, và phiên bản đó không thể thay đổi: chỉnh sửa mẫu nghĩa là lưu một bản nháp mới và xuất bản nó thành phiên bản tiếp theo. Các phong bì đã gửi vẫn giữ phiên bản mà chúng đã cố định.

GET /v1/templates/tpl_…
{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

Id là chuỗi có tiền tố (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); dấu thời gian theo RFC 3339 ở múi giờ UTC.

Hai cách soạn mẫu

Phần tiêu đề “Hai cách soạn mẫu”

Chế độ Overlay (source: "pdf") bắt đầu từ một tài liệu được tải lên. Các trường là hình chữ nhật đặt trên các trang của tài liệu theo đơn vị điểm PDF (1/72 inch), gốc tọa độ ở góc trên bên trái của trang, chỉ số trang bắt đầu từ 0. Tệp .docx tải lên được chuyển đổi sang PDF một lần (bằng LibreOffice, giữ nguyên bố cục Word; các phông chữ không được nhúng trong tệp có thể bị thay thế), và từ đó trở đi nó là một tệp PDF như mọi tệp khác: tệp báo convertedFrom: "docx". Phiên bản Overlay cũng có thể chứa chỉnh sửa nội dung (văn bản được sửa tại chỗ, lớp che trắng, hộp văn bản, hình ảnh, thao tác trên trang) được áp dụng khi phiên bản được xuất bản.

Chế độ Document (source: "document") lưu chính hợp đồng dưới dạng văn bản định dạng (ProseMirror JSON) với các chip biến như {{client.name}}, khối trường nội tuyến, các mục có điều kiện (chỉ được giữ khi biểu thức showIf đúng) và các mục cùng hàng bảng lặp lại (một mục cho mỗi phần tử của biến mảng). Mỗi phong bì kết xuất tệp PDF riêng, và vị trí các trường được đọc từ bản kết xuất đó. Trong bảng điều khiển, chế độ Document có tên “Start from blank document”. Qua API, một tệp Word cũng có thể được nhập vào chế độ Document bằng POST /v1/templates/{id}/import: các {{tags}} trở thành biến hoặc trường, và các dòng chữ ký (“Signature: ____”, “By: ____”, “Date: ____”) trở thành khối trường.

Trong bảng điều khiển

Phần tiêu đề “Trong bảng điều khiển”

New template cung cấp hai cách bắt đầu:

  • Upload document: một vùng thả cho tệp .pdf và .docx dung lượng tối đa 25 MB. Tệp Word được chuyển đổi sang PDF và mở trong trình thiết kế kèm lời nhắc kiểm tra bố cục sau chuyển đổi trước khi đặt trường. Các sửa đổi nhỏ được thực hiện ngay trên PDF (“Edit content”); với thay đổi lớn hơn, hãy sửa tệp Word và tải lên lại.
  • Start from blank document: soạn hợp đồng ở chế độ Document.

Chỉnh sửa nội dung

Phần tiêu đề “Chỉnh sửa nội dung”

Chế độ Edit content của trình thiết kế thay đổi những gì người ký nhìn thấy mà không đụng đến tệp đã tải lên. Công cụ mặc định của nó, Edit text, làm nổi bật các khối văn bản của trang (các dòng và đoạn được nhóm từ lớp văn bản của PDF); nhấp vào một khối, hoặc dùng Tab để di chuyển đến và nhấn Enter, để sửa tại chỗ với cùng vị trí, kích thước, màu sắc, căn lề và phông chữ. Ctrl/Cmd+Enter để lưu, Esc để hủy, và mỗi chỉnh sửa có thể hoàn tác từ danh sách chỉnh sửa. Chỉnh sửa có thể hoàn tác như mọi thay đổi khác. Các công cụ còn lại thêm lớp che trắng, hộp văn bản và hình ảnh, cũng như chèn, xóa, sắp xếp lại hoặc xoay trang.

Một chỉnh sửa văn bản tại chỗ được lưu thành hai mục có chung group: một lớp che trắng phủ lên khối gốc (theo màu nền của trang) và một mục văn bản được dàn trang trong khối, với chiều cao dòng và đường cơ sở đầu tiên của khối:

edits.items (excerpt)
[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face chọn phông chữ: phông chữ nhúng của PDF khi nó vẽ được mọi ký tự của văn bản mới, nếu không thì dùng một phông chữ đi kèm tương thích về số đo (sans Arimo cho Helvetica/Arial, serif Tinos cho Times, mono Cousine cho Courier, carlito Carlito cho Calibri) với độ đậm và kiểu tương ứng. Văn bản được ngắt dòng trong khối; khi cần nhiều dòng hơn bản gốc, chỉnh sửa sẽ mở rộng xuống khoảng trống bên dưới, và trình thiết kế từ chối lưu khi không còn khoảng trống (“text doesn’t fit — shorten it or add space”). Trình thiết kế và API dùng chung mã dàn trang và phông chữ, nên tệp PDF được xuất bản khớp với bản xem trước đến từng dòng.

Chỉnh sửa chỉ có thể thay đổi bản nháp. Việc xuất bản áp dụng chúng lên một tệp PDF nền mới, có SHA-256 là documentHash của phiên bản (giá trị băm của những gì người ký thấy); tệp gốc đã tải lên được giữ làm sourceFile của phiên bản, và bản nháp tiếp theo bắt đầu từ tệp đó với cùng các chỉnh sửa. Lớp che trắng chỉ che nội dung về mặt hiển thị; văn bản gốc vẫn còn trong tệp bên dưới, nên đây không phải là cách biên tập xóa thông tin an toàn.

Vai trò

Phần tiêu đề “Vai trò”

Vai trò là các bên của hợp đồng. Người nhận của phong bì được khớp với vai trò theo key.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }
Thuộc tính Ý nghĩa
key Định danh chữ thường (^[a-z][a-z0-9_]*$) được các trường và người nhận của phong bì sử dụng
kind signer (phải có trường chữ ký hoặc chữ ký tắt), approver, form_filler, hoặc cc (nhận bản sao, không bao giờ ký)
order Thứ tự chuyển tiếp bắt đầu từ 1. Các vai trò có cùng thứ tự ký song song; thứ tự tiếp theo bắt đầu khi họ xong
verification Cách người nhận của vai trò chứng minh danh tính: none (mặc định: chỉ riêng liên kết ký duy nhất) hoặc email_otp (liên kết kèm mã gửi qua email). Người nhận có thể ghi đè giá trị này; xem xác minh người ký

passkey, id_check và sms_otp có trong schema nhưng chưa dùng được để ký: mẫu dùng passkey hoặc id_check không thể xuất bản, và mã SMS hiện chưa được gửi.

Trường

Phần tiêu đề “Trường”
{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

Các loại trường: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp, và variable_text (do người gửi điền từ một biến, không phải người ký). Trường cũng có thể có:

  • variable: một JSON Pointer trỏ vào các biến (/client/name) để liên kết hoặc điền sẵn trường;
  • options cho radio và dropdown;
  • validation: pattern, min, max, maxLength, hoặc một format (email, phone, date, number, currency);
  • showIf: một điều kiện trên các biến và các trường khác, chẳng hạn plan != "free";
  • formula: một giá trị được tính toán, chỉ đọc;
  • overflow: cách xử lý khi giá trị không vừa ô: shrink (mặc định), wrap hoặc reject.

Biến

Phần tiêu đề “Biến”

variables của một phiên bản là JSON Schema (draft 2020-12) cho dữ liệu bạn gửi kèm mỗi phong bì; sampleVariables của phiên bản là một ví dụ. POST /v1/envelopes kiểm tra variables của bạn theo schema đó và báo mọi vấn đề kèm một JSON Pointer:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

Để xem kết quả trước khi gửi, hãy kết xuất bản xem trước có hình mờ của bất kỳ phiên bản nào bằng POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF), hoặc tạo phong bì với ?dry_run=true.

Xây dựng mẫu bằng API

Phần tiêu đề “Xây dựng mẫu bằng API”

Hầu hết các nhóm thiết kế mẫu trong trình thiết kế của bảng điều khiển. Mọi việc trình thiết kế làm đều có thể thực hiện qua API:

  1. POST /v1/templates với { "name": "Mutual NDA" }.
  2. POST /v1/templates/{id}/files với tệp PDF (hoặc .docx) làm nội dung (Content-Type: application/pdf) hoặc làm trường multipart file. Tối đa 25 MB. Phản hồi chứa id của tệp (tfl_…), số trang và kích thước trang.
  3. PUT /v1/templates/{id}/draft với roles, fields, variables (và file, hoặc source: "document" với content). Bản nháp được lưu nguyên trạng; chưa có gì được kiểm tra.
  4. POST /v1/templates/{id}/publish. Việc xuất bản sẽ lint bản nháp: vai trò của mọi trường đều tồn tại, mọi vai trò người ký đều có trường chữ ký, các trường nằm vừa trong trang, trường radio và dropdown có các lựa chọn, biểu thức phân tích được. Các vấn đề được trả về dưới dạng 422 kèm con trỏ như /fields/3/rect.
Terminal window
curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

Các endpoint phiên bản chấp nhận một số, latest hoặc draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (tệp PDF nền). Một mẫu chưa từng được phong bì hay liên kết ký nào sử dụng thì có thể xóa; nếu không, DELETE trả về 409 in-use.