Chaindoc logoChaindoc

Last updated: April 28, 2026

安装

将 Chaindoc SDK 添加到您的项目中。有两个软件包：用于后端工作（文档、签名、验证）的 Server SDK 和用于将签名 UI 放入前端的 Embed SDK。

开始之前

如果您还没有帐户，请从快速入门指南开始进行设置。在 Node.js LTS 版本 中了解更多信息。

服务器软件开发工具包

Server SDK 处理后端的所有事务：创建文档、发送签名请求、管理团队以及触发区块链验证。它是 REST API 的薄包装，因此如果您阅读过 API 文档，方法名称会感到熟悉。

安装包

npm install @chaindoc_io/server-sdk

设置环境变量

在项目根目录中创建一个 `.env` 文件。你在这里需要你的密钥。

.env
# Your Chaindoc secret key (starts with sk_)
CHAINDOC_SECRET_KEY=sk_xxxxxxxxxxxxx

# Optional: override the API endpoint
# (only needed for self-hosted deployments or custom staging URLs)
# CHAINDOC_API_URL=https://api.chaindoc.io

初始化SDK

lib/chaindoc.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';

// Basic initialization
export const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Advanced configuration
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  environment: 'production',       // 'production' | 'staging' | 'development'
  baseUrl: process.env.CHAINDOC_API_URL, // Optional. overrides the environment-derived URL
  timeout: 60000,                  // ms; default 30000
  retry: {
    maxRetries: 5,                 // default 3
    baseDelayMs: 1000,             // starting backoff delay
    maxDelayMs: 10000,             // ceiling
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

基本配置对于大多数项目来说已经足够了。如果您要批量处理大量文档，则重试设置值得调整，因为 API 的速率为 limit。

验证您的连接

terminal
// Test API connection
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('Connected to Chaindoc API at', health.timestamp);
} else {
  console.error('Connection failed');
}

如果失败，请仔细检查您的密钥是否以 `sk_` 开头（而不是 `pk_`。公钥用于前端的 Embed SDK，而不是服务器 SDK）。在需要秘密密钥的地方使用公共密钥是最常见的错误。

嵌入SDK

Embed SDK 可让您在 Web 应用程序内显示 Chaindoc 签名界面。您的用户无需离开您的网站即可签署文档。它适用于 React、Vue、Angular 或纯 JavaScript。

安装包

npm install @chaindoc_io/embed-sdk

CDN 选项对于快速原型或无需构建步骤的站点非常方便。对于生产，请使用 npm 包，以便获得树摇动和适当的版本控制。

设置环境变量

Embed SDK 在初始化时采用公钥 (`pk_`)。包含在客户端代码中是安全的。 SDK 会验证前缀并将其保留在本地，但签名流程的运行时身份验证由后端创建的 `sessionId` 进行（有关详细信息，请参阅 sdks），而不是由公钥进行。

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_xxxxx
# or for Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_xxxxx

在您的应用程序中初始化

// hooks/useChaindoc.ts
import { useRef, useEffect } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export function useChaindoc() {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.REACT_APP_CHAINDOC_PUBLIC_KEY!,
      environment: 'production',
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return sdkRef.current;
}

特定于框架的设置

这些示例展示了如何将 Embed SDK 连接为每个框架中的提供程序或服务。如果您在后端使用 Server SDK，则不需要提供程序；只需将其导入到您需要的地方即可。

Next.js（应用程序路由器）

app/providers.tsx
'use client';

import { createContext, useContext, useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

const ChaindocContext = createContext<ChaindocEmbed | null>(null);

export function ChaindocProvider({ children }: { children: React.ReactNode }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    if (!sdkRef.current) {
      sdkRef.current = new ChaindocEmbed({
        publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
      });
    }

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return (
    <ChaindocContext.Provider value={sdkRef.current}>
      {children}
    </ChaindocContext.Provider>
  );
}

export const useChaindoc = () => useContext(ChaindocContext);

Next.js（页面路由器）

pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default function App({ Component, pageProps }: AppProps) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return <Component {...pageProps} />;
}

努克斯特3

plugins/chaindoc.client.ts
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const chaindoc = new ChaindocEmbed({
    publicKey: config.public.chaindocPublicKey,
  });

  return {
    provide: {
      chaindoc,
    },
  };
});

角

services/chaindoc.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';
import { environment } from '../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class ChaindocService implements OnDestroy {
  private sdk: ChaindocEmbed;

  constructor() {
    this.sdk = new ChaindocEmbed({
      publicKey: environment.chaindocPublicKey,
    });
  }

  getSdk(): ChaindocEmbed {
    return this.sdk;
  }

  ngOnDestroy(): void {
    this.sdk.destroy();
  }
}

TypeScript 配置

这两个 SDK 都附带完整的 TypeScript 定义。您不需要任何额外的 `@types` 包。

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

如果您使用的是旧版 TypeScript 设置 (< 5.0)，请使用 `"moduleResolution": "node"` 而不是 `"bundler"`。

开发与生产

API 键不带有环境标志。相同的 `sk_` 或 `pk_` 键适用于生产、登台或开发。您可以使用每个 SDK 上的 `environment` 选项选择要使用的 Chaindoc 环境。始终为开发和生产保留一组单独的密钥，这样泄漏或轮换就不会影响另一个密钥。

开发设置

terminal
// Server SDK. point at staging, use dev key from .env
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  environment: 'staging',
});

// Embed SDK. staging + debug logs
const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
  environment: 'staging',
  debug: true,  // prints postMessage traffic to the console
});

Embed SDK 上的 `debug: true` 打印 iframe 和父级之间的 postMessage 流量。噪音很大，但当流量被卡住时，它的价值是无价的。

生产设置

terminal
// Server SDK. production (environment: 'production' is the default, shown here for clarity)
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  environment: 'production',
});

// Embed SDK. production, debug off
const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
  environment: 'production',
});

验证您的安装

运行这些检查以确保一切都正确连接：

1检查SDK版本在您的应用中运行 `console.log(ChaindocEmbed.version)`。如果打印版本号，则说明软件包安装正确。

2测试 API 连接从您的后端调用 `chaindoc.healthCheck()`。成功的响应意味着您的密钥有效并且 API 可达。

3尝试文件上传使用`chaindoc.media.upload()`上传一个小测试PDF。这证实了身份验证、网络和文件处理的所有工作。

4打开签名 UI初始化 Embed SDK 并通过测试会话调用 `openSignatureFlow()`。如果出现模式，就可以开始了。

故障排除

“找不到模块”错误

这通常意味着软件包未正确安装或存在缓存版本冲突。清除所有内容并重新安装：

terminal
# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

TypeScript 类型错误

确保您安装了 Node.js 类型并且您的 `tsconfig.json` 使用正确的模块分辨率。大多数问题都源自 `moduleResolution` 设置不匹配。

terminal
npm install --save-dev @types/node

API 个按键错误

如果您收到 401 或 403 响应，请检查以下内容：

  • 401 Unauthorized：密钥无效或已被撤销。在仪表板中重新生成它。
  • 403 禁止：您的计划不包含 API 访问权限。您需要一份商业计划。
  • 确保您使用正确的密钥类型：`pk_` 键用于 Embed SDK（前端），`sk_` 键用于 Server SDK（后端）。将它们混淆是最常见的错误。
  • 如果您要针对登台或开发运行，请在 SDK 上设置 `environment: 'staging'`（或 `'development'`）。键本身不带有环境标志。

接下来做什么

现在 SDK 已安装，请选择下一步：

系统要求是什么？▼

Chaindoc 在现代网络浏览器中运行。对于 API 和 SDK，您需要 Node.js 18+ 或 Python 3.9+。 Web 应用程序不需要本地服务器设置。

你们提供npm套餐吗？▼

是的。 Chaindoc JavaScript SDK 在 npm 上以 @chaindoc/sdk 形式提供。使用npm install @chaindoc/sdk或yarn add @chaindoc/sdk来安装它。

我可以自行托管 Chaindoc 吗？▼

自托管不可用。 Chaindoc 作为托管云服务提供，以确保安全补丁、合规性更新和可靠的基础设施。

如何获得 API 键？▼

登录您的 Chaindoc 帐户，导航至“设置”> API，然后生成新密钥。安全地存储它，因为它允许访问您的帐户数据。

你支持Python吗？▼

是的。 Python SDK 可在 PyPI 上使用。使用 pip install chaindoc-sdk 安装它。