合同进来，签好出去。

整体架构

模板

上传 PDF（或 Word 文件）并放置字段，或在文档模式下直接撰写合同。变量是一个 JSON Schema，因此 API 会在发送任何内容之前校验您的数据。版本一经发布便不可更改。

信封

一次 POST /v1/envelopes 调用即可用您的变量渲染模板，并按角色和顺序开始流转给各个收件人。试运行、幂等键和 externalId 去重均为内置功能。

随心签署

电子邮件链接、托管页面，或在您自己的应用中使用 <bf-signing> Web 组件（提供 React 和 Vue 封装），签署会话由您的后端签发，短时有效且仅限使用一次。

人人可查验的证据

每份完成的文档都会获得由公共时间戳机构签发的 PAdES 文档时间戳，其指纹会写入一棵 Merkle 树， Bona Fide 用 Ed25519 对树根签名。任何人都可以验证副本，无需账户。

一图看懂生命周期

1. 设计：在控制台中或通过 API 设计模板，然后发布一个版本。
2. 发送信封：调用 POST /v1/envelopes，传入模板 ID、您的变量，并为每个角色指定一位收件人。
3. 签署：收件人会收到电子邮件链接；您也可以签发签署会话并将其嵌入（delivery: "embedded"）。
4. 完成：最后一位收件人签署后，您会收到 envelope.completed Webhook，其中包含所有填写的值。
5. 封存：收到 envelope.sealed 时，已封存的 PDF（附完成证书）即已就绪。
6. 验证：任何人都可以把 PDF 拖到验证页面上，或调用公开验证 API。

好用的 API

• 可据以处理的错误。 每个错误都采用 RFC 9457 problem+json 格式；校验错误会为每个问题附带一个 JSON Pointer，例如 /variables/client/email。
• 安全重试。 在 POST 请求中发送 Idempotency-Key，重试时将重放第一次的响应。
• 免费、无限量的测试模式。 使用 bf_test_ 密钥创建的信封带有水印，且永不计费。请参阅身份验证。
• 遵循标准的 Webhook。 投递按照 Standard Webhooks 签名，失败后会在三天内重试，并且可以重放。
• 从代码生成的 OpenAPI 3.1。 参考文档以及可下载的 openapi.json / openapi.yaml 都基于 API 用于校验的同一套 zod 契约构建。

后续步骤

快速入门十分钟内完成 API 密钥、基于模板的信封、签署和完成 Webhook。

核心概念模板、角色、字段、信封、收件人、会话和组织。

嵌入式签署使用 把签署体验放进您的产品。

验证封存和锚定的工作原理，以及如何自行检查文档。

API 的地址为 https://api.bonafidesign.com。本文档中的所有路径都相对于该地址。