Chaindoc logoChaindoc

快速入门指南

在10分钟内上手 Chaindoc。本指南将带您了解网页界面和 API 两种使用方式，您可以根据需求选择适合的路径。

通过网页界面进行签名

无需编写任何代码即可发送您的第一份签名请求。网页应用会处理所有流程：上传文件、添加签署人、签署流程以及区块链验证。

分步指南：您的第一次签名

1创建账户在 app.chaindoc.io 注册并验证您的邮箱。大约需要30秒。

2上传文档点击「新建文档」并拖拽您的文件。Chaindoc 支持 PDF、Office 文档和图片，最大50MB。

3填写详细信息给文档命名，可选添加描述，并选择访问级别（私有、团队或公开）。标签是可选的，但有助于后续搜索。

4创建签名请求点击「请求签名」，添加签署人邮箱，设置截止日期，并撰写消息。签署顺序可以是并行（所有人同时签署）或顺序（逐一签署）。

5发送请求检查详情后点击发送。每位收件人都会收到一封包含安全签署链接的邮件。如需身份验证，您还可以启用 KYC 验证。

6跟踪进度仪表板实时显示谁已签署、谁尚未签署。每当有新的签名提交时，您都会收到通知。

7下载已签署副本所有人签署完成后，下载最终文档。文档附带区块链验证证书，证明文档未被篡改。

想了解不同的签名类型（简单签名、高级签名、合格签名）？这关系到合规性问题。大多数商业合同使用简单电子签名即可，但受监管行业通常需要高级或合格签名。

通过 API 集成

如果您要在自己的应用中集成签名功能，可以使用 REST API 和 TypeScript SDK。流程与网页界面相同，只是实现了自动化。

1. 获取 API 密钥

API 访问需要商业套餐。在仪表板的设置 > API 访问中创建两个密钥：

  • 公钥 (`pk_`) 用于前端 Embed SDK
  • 密钥 (`sk_`) 用于后端 Server SDK。请勿在客户端代码中使用此密钥。

2. 安装 SDK

选择适合您使用场景的 SDK。大多数应用需要同时使用两者：Server SDK 用于创建文档，Embed SDK 用于签署界面。

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

如需详细的框架设置（React、Vue、Angular、Next.js），请参阅安装指南。

3. 上传并创建文档

server.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

设置 `status: 'published'` 会自动触发区块链验证。如果您想稍后发布，请使用 `'draft'` 状态。

4. 创建签名请求

server.ts
// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

如果您要在应用内显示签署界面，请设置 `embeddedFlow: true`。如果不设置，签署人将收到 Chaindoc 托管签署页面的链接。

5. 显示签署界面（前端）

此步骤是可选的。如果您设置了 `embeddedFlow: true`，可以在应用内直接打开签署界面。首先在后端创建会话，然后将会话 ID 传递给前端。

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. 检查状态并监听事件

您可以轮询状态，但对于生产环境，webhooks 是更好的选择。它们会在事件发生时立即通知您的服务器。

terminal
// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. 设置 webhooks（推荐）

Webhooks 实时推送事件到您的服务器，无需不断检查。以下是一个基本的 Express 处理程序：

webhooks.ts
// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

在生产环境中，您应该使用 HMAC 验证 webhook 签名，确保 payload 确实来自 Chaindoc。webhooks 指南 详细介绍了这一点。

完整工作流示例

以下是完整流程：上传、创建、签署、验证。复制代码，替换您的 API 密钥，您就拥有了一个可用的原型。

complete-workflow.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

下一步

既然您已经掌握了基础知识，根据您正在构建的内容，可以深入研究以下内容：

  • 安装指南 — React、Vue、Angular 和 Next.js 的框架特定设置
  • API 文档 — 完整的端点参考，包含请求/响应示例
  • SDK — Server SDK 和 Embed SDK，以及各框架集成指南
  • Webhooks — 生产应用的实时事件通知
  • 安全最佳实践 — 上线前需要加固的内容

常见问题

区块链验证需要多长时间？

通常需要1-5分钟，具体取决于网络情况。您的文档会立即可用。验证在后台运行，完成后您会收到 webhook 事件通知。

我可以在不付费的情况下测试 API 吗？

免费套餐让您可以访问网页界面。API 访问需要商业套餐，但沙盒环境允许您测试所有功能，而不会影响真实数据或消耗配额。

这些签名具有法律约束力吗？

是的。Chaindoc 签名符合欧洲的 eIDAS、美国的 ESIGN Act 和 UETA，以及大多数其他司法管辖区的同等法规。区块链验证在此基础上增加了一层额外的证据，这在争议中可能很重要。有关哪种签名类型符合您合规需求的详细信息，请参阅签名文档。

我可以上传哪些文件格式？

PDF、DOC、DOCX、XLS、XLSX、PPT、PPTX、TXT、JPG、PNG、GIF、WEBP、SVG、MP4、AVI、MOV 和 WMV。最大文件大小为50MB。