API集成

Chaindoc的REST API让您能够自动化文档工作流、收集电子签名并实时同步事件。说实话，这套接口的设计相当直观——本文将带您快速上手，了解核心概念以及常见的集成模式。

API能做什么

通过API，您可以程序化地访问Chaindoc的全部功能：上传文档、创建签名请求、管理团队，以及通过Webhook监听事件。这其实就是支撑Web应用运行的同一套API。

三种集成方式

根据您的技术栈选择合适的方式。大多数生产环境应用会在后端使用Server SDK，前端使用Embed SDK。

• REST API — 直接发送HTTP请求，支持任何编程语言，灵活性最高。
• Server SDK — 类型安全的Node.js封装，内置自动重试和错误处理 (`@chaindoc_io/server-sdk`)
• Embed SDK — 将签名界面嵌入您的Web应用，用户无需离开您的站点 (`@chaindoc_io/embed-sdk`)

如果还没安装SDK，安装指南详细介绍了React、Vue、Angular和Next.js的npm配置步骤。

快速示例

下面是用三种不同方式实现"创建文档"的相同调用。SDK版本最为简洁，不过原始REST调用能让您清楚看到底层实际传输的数据。

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "合同",
    "description": "服务协议",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

身份验证

每个请求都需要在Authorization头部携带API密钥：

Authorization: Bearer sk_live_xxxxxxxxxxxxx

密钥有两种类型，混淆它们是集成时最常见的错误：

• 公钥 (`pk_`) — 只读权限，可以安全地用于前端代码
• 密钥 (`sk_`) — 完整的读写权限，仅限后端使用。千万不要在客户端代码中暴露这类密钥。
• 两种密钥都提供测试版(`_test_`)和生产版(`_live_`)变体。测试密钥会访问沙箱环境。

速率限制

API会在响应头部返回速率限制信息。触发限制时，您会收到429响应。此时需要退避一段时间后重试。

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

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

Server SDK会自动处理重试，采用指数退避策略。如果使用原生HTTP，您需要自行实现重试逻辑。

错误处理

错误以JSON格式返回，包含状态码、消息以及（针对验证错误）具体的字段问题列表：

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

常见状态码：400（请求错误）、401（密钥无效）、403（当前套餐不包含API权限）、404（未找到）、429（速率限制）、500（服务器错误）。遇到5xx错误时，建议退避后重试。

常见集成模式

完整签名流程（嵌入式）

这是最常见的模式：上传文档、发送签名请求、在您的应用内展示签名界面。

快速入门指南提供了这个流程的完整代码示例。

邮件签名（无需嵌入）

如果签名者不使用您的应用，设置`embeddedFlow: false`。Chaindoc会向他们发送包含签名链接的邮件。签名完成后，您仍能通过webhook收到通知。

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // 签名者通过邮件链接访问
  message: '请审阅并签署此文档',
});

批量文档处理

批量导入时，遍历文件列表并逐个上传。但要注意速率限制。如果处理数百份文档，建议在请求之间添加短暂延迟，或使用SDK内置的重试机制。

const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: '批量处理文档',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

KYC集成

对于高安全性工作流，可以要求签名前完成身份验证。Chaindoc与Sumsub集成提供KYC服务。在签名请求上设置`isKycRequired: true`，签名者就必须先通过身份验证才能签署。

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // 可选：预验证用户
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

通过API控制访问权限

您可以程序化地设置文档权限。将访问限制在特定邮箱或团队角色：

await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

最佳实践

• 将API密钥保存在环境变量中。千万不要提交到版本控制。
• 开发时使用测试密钥(`sk_test_`)。生产密钥(`sk_live_`)会访问真实环境。
• 针对429响应实现指数退避。SDK已自动处理此逻辑。
• 使用HMAC验证webhook签名，防止重放攻击。
• 先上传文件再创建文档。API需要上传步骤返回的媒体ID。
• 列表接口使用分页。不要一次性获取所有数据。
• 上线前务必查阅安全指南。

实际应用案例

以下是一些团队使用API构建的真实场景：

• 电商场景 — 为高价值订单自动生成采购协议，在结账时发送签名请求
• HR入职 — 从模板创建雇佣合同，在员工入职当天发送给新人
• CRM集成 — 从Salesforce或HubSpot的交易记录触发签名请求
• 文档归档 — 为现有存储系统中的文档添加区块链验证

接下来做什么

• API文档 — 完整的接口参考，包含请求/响应示例
• SDK文档 — Server SDK和Embed SDK的框架专用指南
• Webhook — 配置实时事件通知
• 快速入门 — 10分钟内跑通第一个集成
• 安装指南 — 所有支持框架的npm配置