ChaindocChaindoc REST API 接口文档
这里提供 Chaindoc REST API 的完整接口参考。涵盖认证、文档管理、电子签名、媒体上传、嵌入式会话，还有区块链验证等核心功能。
接口概览
这套 API 让你能用代码操作 Chaindoc 的所有功能：文档管理、电子签名、区块链验证，还有团队管理。设计上主打服务端调用，同时支持 public 和 secret 两种 API key。
- 文档 — 创建、更新文档，并在区块链上完成验证
- 签名 — 发起签名请求，追踪签署进度
- 媒体 — 上传 PDF、图片、视频（单次最多 10 个文件）
- 嵌入式会话 — 为前端创建签署会话（需要配合 Embed SDK 使用）
- KYC — 通过 Sumsub 集成共享和验证身份信息
认证方式
每个请求都要在 Authorization header 里带上 API key。key 分两种类型：
密钥类型
- Public key (`pk_`) — 只读权限，可以放在前端代码里
- Secret key (`sk_`) — 完整读写权限，仅限后端使用。千万别暴露在客户端代码中。
获取密钥
1订阅 Business 套餐只有 Business 套餐用户才能创建 API 密钥
2进入 API Access 页面在控制台中前往 Settings → API Access
3创建 API key点击 Create API Key 按钮
4安全保存妥善保管 secret key（只显示一次）
使用 API key
在 Authorization header 中用 Bearer 方式带上你的 API key：
curl -X GET https://api.chaindoc.io/api/v1/me \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"速率限制
接口都有限流机制来防止滥用。不同类型的接口，限制也不一样。
- 通用接口: 每 10 秒 3 次请求
- 媒体上传: 每 10 秒 3 次请求
- OTP 验证: 每 60 秒 5 次请求
- 读取操作: 每 60 秒 10 次请求
- 创建签名: 每 3 秒 20 次请求
触限后会返回 429 Too Many Requests。响应头里能看到限流详情：
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000错误处理
HTTP 状态码
- 200 - 请求成功
- 201 - 资源创建成功
- 400 - 请求参数错误（验证失败）
- 401 - 未授权（API key 无效或缺失）
- 403 - 禁止访问（权限不足）
- 404 - 资源不存在
- 429 - 请求过于频繁（超出限流）
- 500 - 服务器内部错误
错误响应格式
{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request",
"details": [
{
"field": "name",
"message": "name must be a string"
}
]
}通用接口
获取 API key 信息
查询当前 API key 的基本信息。
GET /me
Authorization: Bearer sk_live_xxxxx健康检查
验证 API 连通性和 key 的有效性。
GET /health
Authorization: Bearer sk_live_xxxxx文档接口
创建文档
创建新文档并自动进行区块链验证。status 设为 'published' 时会自动上链存证。
POST /documents
Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json更新文档
通过创建新版本来更新文档。历史版本会被保留，方便审计追溯。
PUT /documents/:documentId
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json更新文档权限
修改文档的访问控制设置。
PUT /documents/:documentId/rights
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json验证文档
通过区块链验证文档真伪。返回验证状态和交易哈希、链 ID 等信息。
POST /documents/verify
{
"versionHash": "0x123abc...",
"certificateHash": "0x456def..."
}获取验证状态
查询指定文档版本的区块链验证状态。
GET /documents/versions/:versionId/verification
Authorization: Bearer sk_live_xxxxx签名接口
创建签名请求
为一个或多个收件人创建签名请求。开启 embedded flow 可以直接集成到你的前端界面。
curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
"recipients": [{"email": "signer@example.com"}],
"deadline": "2024-12-31T23:59:59Z",
"embeddedFlow": true
}'获取签名请求状态
查看签名请求的状态，了解哪些人已经完成签署。
GET /signatures/requests/:requestId/status
Authorization: Bearer sk_live_xxxxx签署文档
签署文档（前提是 API key 所有者是该文档的签署人之一）。
POST /signatures/sign
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json获取用户签名
获取当前认证用户的所有签名。
GET /signatures
Authorization: Bearer sk_live_xxxxx获取签名请求列表
获取当前用户的所有签名请求，支持分页。
GET /signatures/requests?pageNumber=1&pageSize=10
Authorization: Bearer sk_live_xxxxx媒体上传接口
上传文件用于创建文档。支持 PDF、图片和视频，单次最多传 10 个文件。
curl -X POST https://api.chaindoc.io/api/v1/media/upload \
-H "Authorization: Bearer sk_live_xxxxx" \
-F "media=@contract.pdf"KYC 接口
共享 KYC 数据
向指定收件人共享 KYC (Know Your Customer) 数据，用于身份验证场景。
POST /kyc/share
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json嵌入式会话接口
为你的前端应用创建嵌入式签署会话。会话有效期 10 分钟。
POST /embedded/sessions
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json