Chaindoc logoChaindoc

API集成

通过强大的REST API和SDK将Chaindoc集成至您的应用程序。自动化文档工作流、收集签名并实时同步事件。

概述

Chaindoc提供全面的REST API，支持构建自定义文档签名工作流、自动化流程以及与现有系统集成。该API专为开发者设计，提供完整的TypeScript支持和自动重试功能。

入门指南

1. 获取 API 访问权限

2. 选择集成方式

Chaindoc提供三种集成方案：

  • REST API - 直接HTTP请求实现最大灵活性
  • 服务器 SDK - 类型安全的 Node.js SDK，支持自动重试 (@chaindoc_io/server-sdk)
  • 嵌入式SDK - 面向网页应用的前端签名接口 (@chaindoc_io/embed-sdk)

3. 快速示例

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

核心API概念

认证

所有API请求均需在Authorization头中使用API密钥进行身份验证：

terminal
Authorization: Bearer sk_live_xxxxxxxxxxxxx
  • 公钥（pk_） - 前端应用程序的只读访问权限
  • 密钥 (sk_) - 后端服务器完整读写权限
  • 测试密钥（pk_test_, sk_test_）- 用于预发布/开发环境
  • 实时密钥（pk_live_, sk_live_）- 用于生产环境

速率限制

API 端点设有速率限制以确保公平使用：

terminal
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000
  • 通用接口：每10秒限3次请求
  • 媒体上传：每10秒3次请求
  • 读取操作：每60秒10次请求
  • 签名创建：每3秒限20次请求

错误处理

API返回标准HTTP状态码及详细错误信息：

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

常见集成模式

文档上传与签署流程

1上传文件POST /media/upload - 上传PDF、Office文档或图片

2创建文档POST /documents - 创建状态为'published'的文档记录，用于区块链验证

3创建签名请求POST /signatures/requests - 添加收件人并配置工作流

4创建嵌入式会话POST /embedded/sessions - 为每位签署人生成会话

5开放签名接口使用嵌入式SDK并传入sessionId，在前端打开签名流程

6跟踪进度GET /signatures/requests/:id/status - 监控签名进度

7接收 Webhook当所有签名收集完毕时触发 signature.request.completed 事件

仅限后端的工作流

针对签字方未使用您界面的场景：

terminal
// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

批量文档处理

terminal
// Process multiple documents in batch
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: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

高级功能

Webhooks

接收文档事件的实时通知：

terminal
// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

KYC 集成

在高安全性工作流中集成身份验证：

terminal
// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

访问控制

通过精细化访问控制管理文档权限：

terminal
// Update document access rights
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' }, // Team role
  ],
});

最佳实践

  • 将API密钥存储在环境变量中，切勿写入代码
  • 开发环境使用测试密钥，生产环境使用正式密钥
  • 采用指数退避算法处理速率限制
  • 验证Webhook签名以防止重放攻击
  • 在适当情况下缓存API响应
  • 为提升性能，请在创建文档前上传文件
  • 对于大型数据集请使用分页功能
  • 监控速率限制标头并调整请求频率

示例集成

电子商务平台

自动生成并签署高价值订单的采购协议。

人力资源系统

与人力资源信息系统集成，实现入职期间雇佣合同的自动化签署。

CRM集成

直接从Salesforce、HubSpot或自定义CRM的客户记录中创建签名请求。

文档管理系统

为现有文档管理系统添加区块链验证功能，实现防篡改的审计追踪。

资源

  • API文档 - 包含所有端点的完整REST API参考
  • SDK - 服务器端SDK与嵌入式SDK文档及框架示例
  • Webhooks - 实时事件通知设置指南
  • 快速入门 - 10分钟内完成首次集成部署
  • GitHub示例 - 集成示例与代码片段