Phong bì và người nhận

Một phong bì là một hợp đồng đang trên đường được ký: một phiên bản mẫu được kết xuất với các biến của bạn, những người nhận thao tác trên đó, và bằng chứng về mọi việc diễn ra. Tạo phong bì bằng POST /v1/envelopes.

Tạo phong bì

Trường	Kiểu	Ghi chú
`template`	`tpl_…`	Bắt buộc
`version`	số hoặc `"latest"`	Mặc định `latest`; được xác định và cố định khi tạo. Phải đã được xuất bản
`variables`	object	Được kiểm tra theo JSON Schema của phiên bản
`recipients`	mảng	Một người cho mỗi vai trò (`role`, `name`, `email`; tùy chọn `externalUserId`, `verification`, `fields` để điền sẵn theo id trường, `order` để thay đổi thứ tự ký)
`subject`, `message`	chuỗi	Dùng trong email mời ký và hiển thị trên trang ký
`delivery`	`email` · `embedded` · `none`	Mặc định `email`
`expiresAt`	RFC 3339	Phải là thời điểm trong tương lai; khi đó phong bì hết hạn, liên kết ký và liên kết người xem ngừng hoạt động
`cc`	mảng	Người nhận CC bổ sung (`name`, `email`) ngoài các vai trò CC của mẫu; tối đa 50
`viewers`	mảng	Những người theo dõi phong bì mà không ký (`name`, `email`, tùy chọn `notifyOnSignature`); số lượng mỗi phong bì giới hạn theo gói
`viewerDocumentAccess`	boolean	Cho phép người xem mở tài liệu trên trang trạng thái của họ. Mặc định `false` (chỉ trạng thái); từ gói Team trở lên
`reminders`	object	`{ "enabled": false }` tắt nhắc nhở; `{ "enabled": true, "intervalHours": 24 }` thay đổi khoảng thời gian (từ 1 đến 720)
`externalId`	chuỗi	Id của riêng bạn, tối đa 200 ký tự
`dedupeOn`	`"external_id"`	Trả về phong bì hiện có với `externalId` này thay vì tạo phong bì khác
`metadata`	object gồm các chuỗi	Tối đa 500 ký tự mỗi giá trị; được trả về trên phong bì và trong webhook

Mỗi người nhận cần một vai trò của phiên bản; mỗi vai trò không phải CC cần đúng một người nhận. Các lỗi được báo cùng lúc, kèm con trỏ như /recipients/1/role hoặc /recipients/0/fields/start_date.

Phản hồi: 201 kèm phong bì và header Location; 200 kèm phong bì hiện có và x-deduplicated: true khi dedupeOn khớp; 200 kèm bản tóm tắt chạy thử với ?dry_run=true; 402 khi một không gian làm việc Free đã dùng hết số phong bì được bao gồm; 403 plan-upgrade-required khi số người xem vượt mức cho phép của gói hoặc viewerDocumentAccess không có trong gói (Gói và giới hạn). Chạy thử cũng kiểm tra giới hạn của gói.

Mọi trường được thêm sau bản phát hành đầu tiên đều là tùy chọn: một yêu cầu không có chúng hoạt động y như trước.

Tùy chọn khi gửi

Mẫu xác định ai ký theo thứ tự nào. Với một phong bì cụ thể, bạn có thể thay đổi điều đó mà không cần sửa mẫu:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

Thứ tự: recipients[].order là bước mà người nhận ký; những người nhận có cùng số sẽ ký đồng thời. Nếu không có, order của vai trò trong mẫu được áp dụng. Thứ tự là số nguyên dương; vai trò CC không thể sắp thứ tự; mọi vai trò vẫn cần người nhận của mình (để các trường của mẫu vẫn có người ký); ít nhất một người nhận phải ký. Sự kiện envelope.created ghi lại routingOverridden: true.
CC: người nhận CC bổ sung nhận email tài liệu đã hoàn tất và không bao giờ ký. Họ xuất hiện trong recipients với kind: "cc" và vai trò _cc.
Nhắc nhở: người đang đến lượt được nhắc mỗi intervalHours (mặc định: giá trị REMINDER_INTERVAL_HOURS của bản triển khai, 72), tối đa ba lần; enabled: false không gửi nhắc nhở nào. Nhắc nhở áp dụng cho phương thức gửi email.
Xác thực người ký được đặt riêng cho từng người nhận: verification ghi đè phương thức của vai trò. none (chỉ riêng liên kết ký duy nhất, mặc định cho các vai trò không đặt phương thức) và email_otp (liên kết kèm mã gửi qua email) hiện đã có; passkey và id_check bị từ chối vì chưa khả dụng. Xem xác minh người ký.
Ngôn ngữ: locale trên một người nhận, CC hoặc người xem (hoặc trên phong bì, cho tất cả những ai không có ngôn ngữ riêng) đặt ngôn ngữ cho trang ký và email của họ, là một trong 50 ngôn ngữ ký. Nếu không có, trang ký theo ngôn ngữ trình duyệt và email được gửi bằng tiếng Anh.

Màn hình gửi trong bảng điều khiển cung cấp các tùy chọn tương tự: dời bước sớm hơn hoặc muộn hơn, đánh dấu Sign at the same time, thêm CC và người xem, chọn phương thức xác thực cho từng người ký (Email link only hoặc Email link + code) cùng ngôn ngữ, và đặt ngày hết hạn cùng lịch nhắc nhở.

Phương thức gửi

email: mỗi người nhận được gửi email chứa liên kết đến trang ký lưu trữ sẵn khi đến lượt họ. Người nhận chưa ký sẽ được nhắc vài ngày một lần (tối đa ba lần), và mọi người đều nhận email khi phong bì hoàn tất.
embedded: không gửi email cho người ký. Hãy tạo một phiên ký khi người ký đang ở trong sản phẩm của bạn. Người xem vẫn được gửi email chứa liên kết trạng thái.
none: hoàn toàn không gửi email (kể cả người xem); dùng khi bạn tự chuyển liên kết (phiên lưu trữ sẵn).

POST /v1/envelopes/{id}/recipients/{recipient}/resend gửi email một liên kết mới đến người nhận đang đến lượt (tối đa một lần mỗi phút).

Vòng đời

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

`status`	Ý nghĩa
`rendering`	Đang được chuẩn bị
`sent`	Đang xử lý: người nhận đang ký theo thứ tự chuyển tiếp
`completed`	Mọi người nhận đã xong. Bắt đầu niêm phong
`declined`	Một người nhận đã từ chối; phong bì kết thúc
`voided`	Bạn đã hủy phong bì (`{ "reason": "…" }`); các phiên ký đang mở ngừng hoạt động
`expired`	`expiresAt` đã qua trước khi hoàn tất

seal theo dõi tệp PDF đã niêm phong: not_started, pending (đã hoàn tất, đang niêm phong), sealed, hoặc failed. Việc niêm phong không bao giờ chặn việc hoàn tất: phong bì hoàn tất trước và được niêm phong ngay sau đó.

Người nhận và chuyển tiếp

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

status của người nhận là pending (chưa đến lượt), sent, viewed, completed hoặc declined, và kind là loại của vai trò: signer, approver, form_filler hoặc cc. Việc chuyển tiếp dựa trên order (của vai trò, hoặc giá trị ghi đè khi gửi): tất cả người nhận thuộc thứ tự chưa hoàn tất thấp nhất thao tác song song, và nhóm tiếp theo bắt đầu khi họ xong. Người nhận CC không bao giờ chặn việc chuyển tiếp.

Người xem

Một người xem theo dõi phong bì mà không ký: một người quản lý, một trợ lý pháp lý, người phụ trách tài khoản phía khách hàng. Người xem không phải là người nhận. Họ không có vai trò và không có lượt, không bao giờ chặn hay hoàn tất điều gì, và không bao giờ xuất hiện trong danh sách người ký trên chứng nhận.

Khi phong bì được gửi (hoặc khi bạn thêm họ sau đó bằng POST /v1/envelopes/{id}/viewers), mỗi người xem nhận một email mang thương hiệu kèm liên kết đến trang trạng thái chỉ đọc: tiêu đề phong bì, người gửi, từng bước kèm tên, vai trò, trạng thái và dấu thời gian của người nhận, cập nhật trực tiếp khi mọi người ký. Địa chỉ email của người nhận không được hiển thị.
Người xem được gửi email lần nữa khi phong bì hoàn tất, bị từ chối hoặc bị hủy, và sau mỗi chữ ký nếu notifyOnSignature là true (mặc định tắt).
Tài liệu chỉ có trên trang khi bạn đặt viewerDocumentAccess: true (từ gói Team trở lên): bản gốc khi đang xử lý, tệp PDF đã niêm phong khi đã niêm phong. Nếu không, người xem chỉ thấy trạng thái.
DELETE /v1/envelopes/{id}/viewers/{viewer} thu hồi một người xem: mọi liên kết đã gửi cho họ ngừng hoạt động ngay lập tức.
Liên kết là capability URL cá nhân. Chỉ giá trị SHA-256 của mỗi token liên kết được lưu. Một liên kết hoạt động cho đến khi phong bì hết hạn (tối đa 90 ngày), trong 30 ngày sau khi phong bì kết thúc, và không bao giờ hoạt động sau khi người xem bị thu hồi.
Việc thêm, mở (lần xem đầu tiên trang và tài liệu) và thu hồi được ghi vào nhật ký kiểm tra dưới dạng viewer.added, viewer.viewed, viewer.document_viewed và viewer.revoked, và do đó cũng có trên chứng nhận.

Các phản hồi cho một phong bì (tạo, lấy, hủy) liệt kê người xem:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

Số người xem mỗi phong bì phụ thuộc vào gói (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform không giới hạn); người nhận CC không được tính. Người xem bị thu hồi sẽ giải phóng chỗ của họ.

Tài liệu

GET /v1/envelopes/{id}/document?version=… tải xuống một tệp PDF, với giá trị SHA-256 trong x-document-sha256:

`version`	Tệp
`original` (mặc định)	Tài liệu đã kết xuất như khi được gửi để ký
`sealed`	Tệp PDF cuối cùng: các giá trị được làm phẳng, chứng nhận hoàn tất được nối thêm, có dấu thời gian tài liệu. Sau `envelope.sealed`
`certificate`	Riêng chứng nhận hoàn tất

documentHash của phong bì là SHA-256 của bản gốc và sealedDocumentHash là SHA-256 của tệp đã niêm phong; đó là những gì xác minh tra cứu.

Nhật ký kiểm tra

Mọi hành động là một sự kiện trong chuỗi băm riêng của từng phong bì: hash = SHA-256(prevHash ‖ canonical JSON of the event), với prevHash đầu tiên là 64 số không. GET /v1/envelopes/{id}/events trả về các sự kiện và kiểm tra chuỗi:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Ngoài các loại sự kiện webhook, nhật ký còn có các mục chỉ dành cho kiểm tra như session.created, recipient.verified, recipient.reminded và các sự kiện của người xem (actor kind viewer khi người xem mở trang của họ).

Để hiển thị trạng thái trực tiếp trong giao diện, GET /v1/envelopes/{id}/events/stream là một luồng server-sent events: tên sự kiện của mỗi khung là type của sự kiện và id của khung là seq; kết nối lại với Last-Event-ID để tiếp tục.

Liệt kê

GET /v1/envelopes lọc theo status, seal, template và q (văn bản tự do trên tên và email người nhận, externalId và id phong bì). Giống mọi danh sách khác, nó được phân trang bằng con trỏ:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Gửi lại nextCursor dưới dạng cursor; limit từ 1 đến 100 (mặc định 20).