Chaindoc logoChaindoc

Chaindoc REST API 参考文档

完整指南，助您将Chaindoc的REST API集成至应用程序。管理文档、签名、区块链验证及嵌入式签名工作流。

概述

Chaindoc REST API 提供对文档管理、区块链验证及数字签名功能的程序化访问。该 API 专为服务器间集成设计，同时支持公钥与私钥两种 API 密钥类型。

主要功能

  • 文档管理 - 通过区块链验证创建、更新和管理文档
  • 数字签名 - 向多个方请求并收集数字签名
  • 区块链验证 - 在区块链网络上验证文档真实性
  • 嵌入式会话 - 为前端签名工作流创建安全会话
  • 媒体上传 - 上传文件（PDF、图片、视频）用于文档创建
  • KYC集成 - 通过Sumsub共享并验证身份数据

认证

Chaindoc API 使用 API 密钥进行身份验证。密钥分为两种类型，具有不同的访问权限级别。

API密钥类型

  • 公钥 (pk_) - 前端应用的只读访问权限及验证
  • 密钥 (sk_) - 后端服务器完整读写权限

获取 API 密钥

1订阅商业计划仅商业版用户可创建API密钥

2导航至 API 访问前往控制台的“设置”→“API访问”

3创建 API 密钥点击创建API密钥按钮

4安全存储安全存储密钥（仅显示一次）

使用 API 密钥

在授权标头中包含您的API密钥，并使用Bearer身份验证：

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

速率限制

为防止滥用，API 端点均设置了速率限制。不同类型的端点速率限制各不相同。

  • 通用接口：每10秒限3次请求
  • 媒体上传：每10秒3次请求
  • OTP验证：每60秒限5次请求
  • 读取操作：每60秒10次请求
  • 签名创建：每3秒限20次请求

当超过速率限制时，您将收到429请求过多的响应。响应中包含速率限制标头：

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

错误处理

HTTP状态码

  • 200 - 成功
  • 201 - 资源创建成功
  • 400 - 请求错误（验证失败）
  • 401 - 未授权（API密钥无效或缺失）
  • 403 - 禁止访问（权限不足）
  • 404 - 资源未找到
  • 429 - 请求过多（超出速率限制）
  • 500 - 服务器内部错误

错误响应格式

terminal
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

通用API

获取API密钥信息

获取当前API密钥的相关信息。

GET /me

Authorization: Bearer sk_live_xxxxx

健康检查

验证API连接性和密钥有效性。

GET /health

Authorization: Bearer sk_live_xxxxx

文档 API

创建文档

创建具有区块链验证的新文档。当状态设置为"已发布"时，文档将自动在区块链上完成验证。

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

签名 API

创建签名请求

为一个或多个收件人创建签名请求。启用嵌入式流程以实现前端集成。

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密钥持有者为签署方）。

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

媒体上传API

上传文件用于文档创建。支持PDF、图片和视频格式。每次请求最多可上传10个文件。

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

KYC API

共享KYC数据

向接收方共享KYC（了解你的客户）数据以进行身份验证。

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

嵌入式会话 API

在前端应用中创建用于文档签名的嵌入式会话。会话有效期为10分钟。

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json