开发指南

从零开始完成闪链签企业集成，包含环境准备、快速开始、集成流程和最佳实践

概述

欢迎使用闪链签开放平台！本指南面向企业开发者，帮助您在最短时间内将电子签章能力集成至自有业务系统。

闪链签提供 RESTful API、多语言 SDK 及 Webhook 回调通知，覆盖以下核心能力：

合同签署：创建签署任务、配置签署方、设置签署顺序
实名认证：企业认证、个人认证、多维度身份核验
印章管理：电子印章创建、授权审批、用印记录
模板管理：合同模板创建、参数填充、批量生成
区块链存证：合同哈希上链、链上验证、司法鉴定报告

建议在沙箱环境（api-test.flashsign.cn）完成所有开发和测试，验证通过后再切换至生产环境。沙箱环境完全免费，接口与生产环境一致。

准备工作

第一步：注册企业账号

访问闪链签官网（www.flashsign.cn）注册账号，并完成企业实名认证。认证通过后，您将获得「开发者中心」的访问权限。

第二步：创建应用获取密钥

登录控制台，进入「开发者中心」→「应用管理」，点击「创建应用」：

填写应用名称和描述
选择应用类型（Web 应用 / 移动应用）
系统自动生成 AppKey 和 AppSecret
将密钥妥善保存至安全位置

每个企业最多创建 3 个应用。建议为测试环境和生产环境分别创建独立应用。AppSecret 仅在创建时展示一次，请务必立即保存。

请勿将 AppSecret 硬编码在客户端代码中或提交至版本控制系统。建议通过环境变量、Vault 等密钥管理服务安全存储。

第三步：选择 SDK 或直接调用 API

闪链签提供两种集成方式：

方式	适用场景	开发成本
使用 SDK（推荐）	标准业务场景，快速集成	低 — SDK 封装了签名、请求、错误处理
直接调用 API	定制化需求，非标准语言环境	中 — 需自行实现签名和请求逻辑

支持的 SDK 语言及安装方式：

语言	安装方式	最低版本
Java	Maven: cn.flashsign:flashsign-sdk	JDK 8+
Python	pip install flashsign-sdk	Python 3.8+
Node.js	npm install flashsign-sdk	Node.js 16+
Go	go get github.com/flashsign/flashsign-sdk-go	Go 1.19+
PHP	composer require flashsign/sdk	PHP 8.0+

快速开始

以 Node.js SDK 为例，演示在 5 分钟内完成首次 API 调用。完整示例代码可在 GitHub（github.com/flashsign/examples）获取。

1. 安装 SDK

Bash

npm install flashsign-sdk

2. 初始化客户端

JavaScript

const FlashSignClient = require('flashsign-sdk');

const client = new FlashSignClient({
  appKey: process.env.FLASHSIGN_APP_KEY,
  appSecret: process.env.FLASHSIGN_APP_SECRET,
  env: 'sandbox',  // 沙箱环境；上线时改为 'production'
});

3. 发起第一份合同

JavaScript

const fs = require('fs');

const contract = await client.createContract({
  contractName: '技术服务协议',
  contractFile: fs.readFileSync('./contract.pdf').toString('base64'),
  contractFileName: 'contract.pdf',
  signers: [
    {
      name: '张三',
      phone: '13800138000',
      role: 'signer',       // 'signer' | 'approver' | 'cc'
      signType: 'seal',      // 'seal' | 'signature'
    },
  ],
  signOrder: 1,             // 1=顺序签署  2=并行签署
  expireAt: '2025-02-15',   // 签署截止日期
});

console.log('合同创建成功，编号：', contract.data.contractId);

4. 查询签署状态

JavaScript

const status = await client.getContractStatus({
  contractId: 'CT202501150001',
});

console.log('签署状态：', status.data.status);
// draft(草稿) | pending(待签署) | signed(已完成) | expired(已过期) | cancelled(已取消)

5. 下载已签署合同

JavaScript

const file = await client.downloadContract({
  contractId: 'CT202501150001',
  format: 'pdf',  // 'pdf' | 'ofd'
});

fs.writeFileSync('./signed-contract.pdf', Buffer.from(file.data.content, 'base64'));
console.log('合同下载完成');

集成流程

企业集成闪链签的典型流程分为四个阶段，总周期约为 7-17 天：

阶段一：沙箱测试（1-3 天）

注册企业账号并完成企业认证
在开发者中心创建沙箱应用
下载并安装对应语言的 SDK
在沙箱环境完成核心 API 联调
验证签署流程、回调通知等功能

阶段二：功能集成（3-7 天）

在业务系统中实现合同创建和签署入口
集成身份认证、印章管理等辅助模块
配置 Webhook 回调地址和事件订阅
实现合同管理、下载、验签等辅助功能
与业务系统的用户体系和权限系统对接

阶段三：测试验证（2-5 天）

端到端全流程测试（正常流程 + 异常流程）
签署方身份验证失败、合同过期等边界测试
压力测试（建议目标 QPS ≥ 100）
验证回调通知的可靠性和幂等性处理

阶段四：上线部署（1-2 天）

在开发者中心创建生产环境应用
将 SDK 环境配置切换为 production
通过灰度发布先用少量真实业务验证
监控 API 调用成功率和响应时间
全量上线，进入正式服务

切换生产环境前请务必：① 所有测试用例通过 ② 回调 URL 可公网访问 ③ 错误监控和告警已配置 ④ 密钥已安全存储。

签名机制

为保证 API 调用安全，每次请求都需携带签名。闪链签使用 HMAC-SM3 算法计算请求签名，服务端以同样方式计算并比对，防止请求被篡改或伪造。

请求头

Header	必填	说明
Content-Type	是	固定值 application/json
X-FlashSign-AppId	是	应用 ID
X-FlashSign-Timestamp	是	请求时间戳（毫秒）
X-FlashSign-Nonce	是	随机字符串（防重放）
X-FlashSign-Signature	是	请求签名值

签名计算步骤

将请求参数（不含 sign）按 key 的 ASCII 升序排列
拼接为 key1=value1&key2=value2 格式
在末尾追加 &secret=AppSecret
使用 SM3 哈希算法计算摘要，转为十六进制字符串

JavaScript

// 签名计算实现
const crypto = require('crypto');

function calculateSign(params, secret) {
  // 1. 按 key 排序
  const keys = Object.keys(params).sort();
  // 2. 拼接参数字符串
  const queryStr = keys
    .map(k => `${k}=${params[k]}`)
    .join('&');
  // 3. 追加 secret
  const signStr = queryStr + '&secret=' + secret;
  // 4. SM3 哈希
  const hash = crypto.createHash('sm3');
  hash.update(signStr);
  return hash.digest('hex');
}

SDK 已内置签名计算和自动续签逻辑。仅在自行实现 HTTP 调用时才需关注上述细节。

Webhook 回调

闪链签通过 Webhook 机制向您的服务端推送事件通知，包括签署完成、签署状态变更、认证结果等。

配置回调地址

在「开发者中心」→「回调配置」中设置回调 URL。回调地址必须是公网可访问的 HTTPS URL，建议为不同环境配置不同的回调地址。

支持的事件类型

事件	触发时机	说明
contract.signed	合同签署完成	所有签署方均完成签署
contract.status-changed	合同状态变更	草稿→待签署→已完成→已过期等
signer.signed	单个签署方完成	某个签署方完成签署操作
signer.refused	签署方拒签	签署方拒绝签署合同
identity.verified	实名认证通过	个人/企业实名认证审核通过

回调安全验证

每次回调请求都会携带签名（算法与 API 请求签名一致），请在接收回调时验证签名，确保请求来自闪链签服务端。

回调地址需在 5 秒内返回 HTTP 200 确认接收。如超时或返回非 200，闪链签将按指数退避策略重试（最多 3 次）。请确保回调处理逻辑实现了幂等性。

最佳实践

安全性

始终使用 HTTPS 通信
AppSecret 仅在后端使用，绝不出现在前端代码中
接口签名验证不可或缺，防止请求伪造
实现 API 调用频率控制，避免触发限流
定期轮换 API 密钥

可靠性

API 调用实现重试机制，建议使用指数退避法
回调处理实现幂等性（以 eventId 去重）
通过消息队列异步处理回调，避免阻塞
监控 API 调用成功率、响应时间和错误率

性能

使用 HTTP 连接池减少 TLS 握手开销
合同文件大于 5MB 时使用分片上传接口
签署状态查询等高频场景使用本地缓存（TTL 30s）
批量签署场景使用合同模板 + 批量接口

错误处理参考代码

JavaScript

/** 带指数退避的 API 调用包装器 */
async function callWithRetry(fn, options = {}) {
  const { maxRetries = 3, baseDelay = 1000 } = options;
  
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // 不可重试的错误直接抛出
      if (!error.isRetryable || attempt === maxRetries) {
        throw error;
      }
      // 指数退避：1s, 2s, 4s
      const delay = baseDelay * Math.pow(2, attempt);
      console.warn(`API call failed, retrying in ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

常见问题

Q：沙箱环境和生产环境有什么区别？

沙箱环境和生产环境的 API 接口完全一致，区别在于：① 域名不同（api-test vs api）② 密钥独立管理 ③ 沙箱签署的合同不具备法律效力，仅供测试使用。开发完成后，只需修改域名和密钥即可切换至生产环境。

Q：API 调用频率有限制吗？

默认限制为 100 次/秒/应用。如需更高并发，请联系商务团队申请提额。建议在业务侧做好本地调用控制和缓存，避免因瞬时高峰触发限流。

Q：合同文件支持哪些格式？大小限制是多少？

支持 PDF、Word (.doc/.docx)、OFD 格式。单个文件不超过 50MB。大于 5MB 的文件建议使用分片上传接口以提高上传稳定性。

Q：如何实现批量签署？

先创建合同模板并标记变量占位符，再调用批量创建接口传入数据列表（Excel 导入或 JSON 数组），系统自动生成多份合同并发起签署。单次批量上限为 500 份。

Q：支持私有化部署吗？

支持。闪链签为金融、政务等对数据安全有特殊要求的企业提供私有化部署方案。详情请联系商务团队或拨打 400-6690-636。

Q：遇到技术问题如何寻求帮助？

可通过以下渠道获取技术支持：① 查看 API 文档和错误码文档 ② 在开发者社区（developers.flashsign.cn）搜索或提问 ③ 提交工单（控制台 → 工单中心） ④ 拨打技术支持热线 400-6690-636（工作日 9:00-18:00）。

认证常见问题

认证鉴权

方式

适用场景

开发成本

使用 SDK（推荐）

标准业务场景，快速集成

低 — SDK 封装了签名、请求、错误处理

直接调用 API

定制化需求，非标准语言环境

中 — 需自行实现签名和请求逻辑

语言

安装方式

最低版本

Java

Maven: cn.flashsign:flashsign-sdk

JDK 8+

Python

pip install flashsign-sdk

Python 3.8+

Node.js

npm install flashsign-sdk

Node.js 16+

go get github.com/flashsign/flashsign-sdk-go

Go 1.19+

PHP

composer require flashsign/sdk

PHP 8.0+

const FlashSignClient = require('flashsign-sdk'); const client = new FlashSignClient({ appKey: process.env.FLASHSIGN_APP_KEY, appSecret: process.env.FLASHSIGN_APP_SECRET, env: 'sandbox', // 沙箱环境；上线时改为 'production' });

const fs = require('fs'); const contract = await client.createContract({ contractName: '技术服务协议', contractFile: fs.readFileSync('./contract.pdf').toString('base64'), contractFileName: 'contract.pdf', signers: [ { name: '张三', phone: '13800138000', role: 'signer', // 'signer' | 'approver' | 'cc' signType: 'seal', // 'seal' | 'signature' }, ], signOrder: 1, // 1=顺序签署 2=并行签署 expireAt: '2025-02-15', // 签署截止日期 }); console.log('合同创建成功，编号：', contract.data.contractId);

const status = await client.getContractStatus({ contractId: 'CT202501150001', }); console.log('签署状态：', status.data.status); // draft(草稿) | pending(待签署) | signed(已完成) | expired(已过期) | cancelled(已取消)

const file = await client.downloadContract({ contractId: 'CT202501150001', format: 'pdf', // 'pdf' | 'ofd' }); fs.writeFileSync('./signed-contract.pdf', Buffer.from(file.data.content, 'base64')); console.log('合同下载完成');

Header

必填

说明

Content-Type

是

固定值 application/json

X-FlashSign-AppId

是

应用 ID

X-FlashSign-Timestamp

是

请求时间戳（毫秒）

X-FlashSign-Nonce

是

随机字符串（防重放）

X-FlashSign-Signature

是

请求签名值

// 签名计算实现 const crypto = require('crypto'); function calculateSign(params, secret) { // 1. 按 key 排序 const keys = Object.keys(params).sort(); // 2. 拼接参数字符串 const queryStr = keys .map(k => `${k}=${params[k]}`) .join('&'); // 3. 追加 secret const signStr = queryStr + '&secret=' + secret; // 4. SM3 哈希 const hash = crypto.createHash('sm3'); hash.update(signStr); return hash.digest('hex'); }

事件

触发时机

说明

contract.signed

合同签署完成

所有签署方均完成签署

contract.status-changed

合同状态变更

草稿→待签署→已完成→已过期等

signer.signed

单个签署方完成

某个签署方完成签署操作

signer.refused

签署方拒签

签署方拒绝签署合同

identity.verified

实名认证通过

个人/企业实名认证审核通过

/** 带指数退避的 API 调用包装器 */ async function callWithRetry(fn, options = {}) { const { maxRetries = 3, baseDelay = 1000 } = options; for (let attempt = 0; attempt <= maxRetries; attempt++) { try { return await fn(); } catch (error) { // 不可重试的错误直接抛出 if (!error.isRetryable || attempt === maxRetries) { throw error; } // 指数退避：1s, 2s, 4s const delay = baseDelay * Math.pow(2, attempt); console.warn(`API call failed, retrying in ${delay}ms...`); await new Promise(r => setTimeout(r, delay)); } } }