ChaindocChaindoc REST API 参考
Chaindoc REST API 的完整端点参考。涵盖身份验证、文档、签名、媒体上传、嵌入式会话和区块链验证。
概述
API 使您能够以编程方式访问 Chaindoc 中的所有内容：文档、签名、区块链验证和团队管理。它专供服务器到服务器使用，并支持公共和秘密 API 密钥。如需了解更多信息，请参阅 RFC 9110, HTTP 语义。
- 文档：在区块链上创建、更新和验证文档
- 签名：发送签名请求并跟踪完成情况
- 媒体：上传 PDF 秒、图像和视频（每个请求最多 10 个）
- 合同：起草、发送、取消和终止具有可选付款条件的合同
- 发票和交易：向代理商开具账单、节省费用的付款方式、跟踪结算
- 模板：根据已发布的模板呈现文档、签名请求和合同
- 嵌入式会话：为您的前端创建签名会话（使用 Embed SDK）
验证
每个请求在授权标头中都需要一个 API 键。有两种类型：。如需了解更多信息，请参阅 RFC 6749, OAuth 2.0。
按键类型
- 公钥 (`pk_`)。只读，对前端代码安全
- 密钥 (`sk_`)。完全读/写，仅限后端。切勿在客户端代码中公开。
获取钥匙
1订阅商业计划只有商业计划用户可以创建 API 个密钥
2导航至 API 访问转到仪表板中的设置 → API 访问
3创建API键单击创建 API 密钥按钮
4安全存放安全地存储密钥（仅显示一次）
使用API键
将您的 API 密钥包含在具有承载身份验证的授权标头中：
curl -X GET https://api.chaindoc.io/api/v1/me \
-H "Authorization: Bearer sk_xxxxxxxxxxxxx"评价mit
所有公共API端点都限制mit每个API密钥每60秒10个请求。当超过 limit 时，您将收到 429 Too Many Requests 响应。短暂延迟后退出并重试。
错误处理
HTTP 状态代码
- 200 - 成功
- 201 - 资源创建成功
- 400 - 错误请求（验证错误）
- 401 - 未经授权（API 键无效或丢失）
- 403 - 禁止（权限不足）
- 404 - 找不到资源
- 429 - 请求过多（超出速率 limit）
- 500 - 内部服务器错误
错误响应格式
{
"statusCode": 400,
"message": [
"name must be a string",
"recipients should not be empty"
],
"error": "Bad Request"
}验证错误将 `message` 作为人类可读字符串数组返回，每个失败的约束一个。对于非验证错误（401、403、404、500），`message` 是单个字符串。
一般API
获取API个关键信息
获取有关当前 API 键的信息。
GET /me
Authorization: Bearer sk_xxxxx健康检查
验证 API 连接和密钥有效性。
GET /health
Authorization: Bearer sk_xxxxx文档API
创建文档
创建一个带有区块链验证的新文档。当状态设置为“已发布”时，文档会自动在区块链上进行验证。
POST /documents
Headers:
Authorization: Bearer sk_xxxxx
Content-Type: application/json更新文档
通过创建新版本来更新文档。保留以前的版本以供审计跟踪。
PUT /documents/:documentId
Authorization: Bearer sk_xxxxx
Content-Type: application/json更新文档访问权限
更新文档访问控制设置。
PUT /documents/:documentId/rights
Authorization: Bearer sk_xxxxx
Content-Type: application/json验证文件
使用区块链验证文件的真实性。返回带有交易哈希和链 ID 的验证状态。
POST /documents/verify
Authorization: Bearer pk_xxxxx
Content-Type: application/json
{
"versionHash": "0x123abc...",
"certificateHash": "0x456def..."
}获取验证状态
获取文档版本的区块链验证状态。
GET /documents/versions/:versionId/verification
Authorization: Bearer sk_xxxxx签名API
创建签名请求
为一个或多个收件人创建签名请求。启用前端集成的嵌入式流程。
curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
-H "Authorization: Bearer sk_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
"recipients": [
{ "email": "signer@example.com", "signingMethod": "embedded" }
],
"deadline": "2026-12-31T23:59:59Z",
"embeddedFlow": true,
"isKycRequired": false
}'预先放置的字段（高级）。 如果您上传自己的 PDF 并希望精确控制签名、缩写、日期、文本或复选框字段的显示位置，请在 `versionId` 旁边传递可选的 `fields` 数组。当您从模板渲染文档时（请参阅下面的模板API），放置的字段自动来自模板定义。跳过此选项。
{
"fields": [
{
"signerEmail": "signer@example.com",
"fieldType": "signature",
"pageIndex": 0,
"xPct": 0.15,
"yPct": 0.78,
"wPct": 0.25,
"hPct": 0.05,
"required": true,
"label": "Client signature"
},
{
"signerEmail": "signer@example.com",
"fieldType": "date_signed",
"pageIndex": 0,
"xPct": 0.45,
"yPct": 0.78,
"wPct": 0.15,
"hPct": 0.03
}
]
}获取签名请求状态
检查签名请求的状态并查看哪些签名者已完成签名。
GET /signatures/requests/:requestId/status
Authorization: Bearer sk_xxxxx签署文件
签署文档（如果 API 密钥所有者是签名者）。
POST /signatures/sign
Authorization: Bearer sk_xxxxx
Content-Type: application/json获取用户签名
获取经过身份验证的用户的所有签名。
GET /signatures?pageNumber=1&pageSize=10
Authorization: Bearer sk_xxxxx获取签名请求
通过分页支持获取经过身份验证的用户的所有签名请求。
GET /signatures/requests?pageNumber=1&pageSize=10
Authorization: Bearer sk_xxxxx媒体上传API
上传用于创建文档的文件。支持PDF、图像和视频。每个请求最多 10 个文件。
curl -X POST https://api.chaindoc.io/api/v1/media/upload \
-H "Authorization: Bearer sk_xxxxx" \
-F "media=@contract.pdf"合约API
创建和管理从草稿到签署、生效和终止的合同生命周期。每份合同都包含一份文件、合同信息、可选付款条款和签署政策。支持支付的合约需要 Stripe Connect 账户。请参阅安全指南进行设置。
创建合同
从现有文档创建状态为 `draft` 的合同。付款条件是可选的。您可以稍后通过付款设置添加它们。
POST /contracts
Authorization: Bearer sk_xxxxx
Content-Type: application/json列出合约
列出通过 API 创建的合约，带有分页和可选的状态/搜索过滤器。
GET /contracts?page=1&limit=10&status=active&search=acme
Authorization: Bearer sk_xxxxx获得合同
获取完整的合同详细信息，包括付款条款、签署状态和合同信息。
GET /contracts/:contractId
Authorization: Bearer sk_xxxxx获取合同状态
用于监控合同生命周期的轻量级端点，无需获取完整的有效负载。返回当前状态、签名进度和付款摘要。
GET /contracts/:contractId/status
Authorization: Bearer sk_xxxxx获取合同活动
用于审核和 Webhook 协调的分页活动日志（创建、发送、签名、修改、终止等）。
GET /contracts/:contractId/activities?page=1&limit=20
Authorization: Bearer sk_xxxxx设置付款条件
在`draft`份合同上附加或替换付款条款。当您创建合约 shell 第一个 并单独配置计费时很有用。
POST /contracts/:contractId/payment-setup
Authorization: Bearer sk_xxxxx
Content-Type: application/json发送合同以供签署
将 `draft` 合约转换为 `pending_signature` 并通知双方。所有正文字段都是可选的。
POST /contracts/:contractId/send
Authorization: Bearer sk_xxxxx
Content-Type: application/json取消合同
在任何人签署之前取消 `draft` 份合同（从未发送）或 `pending_signature` 份合同。不可逆转。
POST /contracts/:contractId/cancel
Authorization: Bearer sk_xxxxx终止合同
终止`active`合同。对于 `mutual_approval` 合约，这会启动另一方必须确认的 `termination_pending` 流程；对于 `one_side` 份合同，它会立即终止。
POST /contracts/:contractId/terminate
Authorization: Bearer sk_xxxxx
Content-Type: application/json合同发票 API
根据 `active` 合同向合同方开具账单。发票可以根据定期付款条件自动生成，也可以手动创建临时计费。支持 Stripe 的合约支持对已保存的付款方式进行收费。
创建发票
针对 `active` 合同创建手动发票。设置`sendImmediately: true`立即发送给合同方，设置`autoCharge: true`在发送时通过其保存的付款方式收费。
POST /contracts/:contractId/invoices
Authorization: Bearer sk_xxxxx
Content-Type: application/json列出合同发票
使用分页和可选状态过滤器列出合同的所有发票。
GET /contracts/:contractId/invoices?page=1&limit=10&status=unpaid
Authorization: Bearer sk_xxxxx获取发票
获取完整的发票详细信息，包括行项目、交易和 Stripe 结账 URL（如果适用）。
GET /contracts/:contractId/invoices/:invoiceUuid
Authorization: Bearer sk_xxxxx发送发票
向合同方发送`draft`张发票。设置`autoCharge: true`以尝试立即通过保存的付款方式收费。
POST /contracts/:contractId/invoices/:invoiceUuid/send
Authorization: Bearer sk_xxxxx
Content-Type: application/json收费发票
使用承包商保存的付款方式对已发送的发票进行收费。用于重试失败的付款或按需收费。
POST /contracts/:contractId/invoices/:invoiceUuid/charge
Authorization: Bearer sk_xxxxx将发票标记为已付款
记录离线/外部结算。电汇、现金或通过其他铁路付款。记录手动交易以供审计。
POST /contracts/:contractId/invoices/:invoiceUuid/mark-paid
Authorization: Bearer sk_xxxxx
Content-Type: application/json交易API
读取与合同发票链接的付款交易。交易捕获每次收费尝试（成功、失败或待处理）以及 Stripe 费用明细、净额和重试历史记录。
列出合约交易
列出合同发票中的所有交易。
GET /contracts/:contractId/transactions
Authorization: Bearer sk_xxxxx获取交易
通过 UUID 获取单个交易的完整详细信息：金额、费用、收据 URL 和重试元数据。
GET /transactions/:transactionUuid
Authorization: Bearer sk_xxxxx模板API
将已发布的模板呈现为草稿文档、签名请求或合同。传递变量值和槽分配。模板系统支持合约模板的每个签名者变量和基于角色的槽分配。
从模板创建文档
渲染带有变量的模板并创建一个新的草稿文档。这里不需要插槽分配。该端点仅生成文档外壳。
POST /templates/:templateId/documents
Authorization: Bearer sk_xxxxx
Content-Type: application/json从模板创建签名请求
渲染模板、创建文档并立即发送以供签名。每个 `slotAssignment` 将模板签名者密钥绑定到真实的收件人电子邮件。
POST /templates/:templateId/signature-requests
Authorization: Bearer sk_xxxxx
Content-Type: application/json从模板创建合同
渲染包含变量和合约信息的合同模板，创建合同并将其发送以在一次调用中进行签名。槽分配将模板签名者密钥绑定到角色 (`business` | `contragent`)。电子邮件取自 API 密钥所有者（企业）和 `contragent.email`。
POST /templates/:templateId/contracts
Authorization: Bearer sk_xxxxx
Content-Type: application/json嵌入会话 API
在前端应用程序中创建用于文档或合同签署的嵌入式会话。会议有效期为 10 分钟。对于standa单独文档签名，请在`metadata`中传递`documentId`和`signatureRequestId`。对于合同签名，传递 `contractId` 和 Chaindoc 解析活动签名请求。
POST /embedded/sessions
Authorization: Bearer sk_xxxxx
Content-Type: application/json