认证鉴权

API 密钥获取、HMAC-SM3 签名算法详解及多语言签名示例

密钥管理

闪链签使用 AppKey + AppSecret 进行 API 调用鉴权。AppKey 和 AppSecret 在创建应用时自动生成。

参数	说明	安全要求
AppKey	应用唯一标识，用于识别调用方身份	可在请求中明文传输
AppSecret	应用密钥，用于计算请求签名	仅保存在服务端，绝不可暴露

密钥管理操作指引：

创建：控制台 → 开发者中心 → 应用管理 → 创建应用
查看：已创建的 AppKey 可随时查看，AppSecret 仅在创建时展示一次
重置：若 AppSecret 泄露或遗忘，可点击「重置密钥」生成新密钥（重置后旧密钥立即失效）
删除：删除应用后，对应密钥不可恢复

AppSecret 仅在创建时展示一次。请务必立即复制保存至安全的密钥管理服务（如 Vault、KMS）中。

签名算法详解

闪链签使用国家密码管理局认证的 SM3 哈希算法进行请求签名，确保请求在传输过程中不被篡改。

签名步骤

收集所有请求参数（appId, timestamp, nonce, data 中的业务参数）
将参数按 key 的 ASCII 码升序排列
拼接为 key1=value1&key2=value2 格式
在末尾追加 &secret=AppSecret，得到待签名串
使用 SM3 算法计算待签名串的哈希值
将哈希值转为十六进制字符串，即为签名

签名示例

假设请求参数如下：

JSON

{
  "appId": "app_myapp",
  "timestamp": 1705312800000,
  "nonce": "abc123xyz",
  "data": {
    "contractName": "测试合同"
  }
}

则待签名串为（注意 data 内的参数需展平到顶层参与排序）：

Text

appId=app_myapp&contractName=测试合同&nonce=abc123xyz&secret=your_secret&timestamp=1705312800000

SDK 已完全封装签名计算逻辑。使用 SDK 时无需手动处理以上步骤。

多语言签名示例

Java

import cn.flashsign.sdk.FlashSignClient;
import cn.flashsign.sdk.model.*;

// 初始化客户端（自动处理签名）
FlashSignClient client = new FlashSignClient.Builder()
    .appKey("app_xxxxxx")
    .appSecret("your_secret")
    .env(Env.SANDBOX)  // SANDBOX | PRODUCTION
    .build();

// 发起合同
CreateContractRequest req = new CreateContractRequest();
req.setContractName("技术服务协议");
req.setContractFile(Base64.getEncoder().encodeToString(fileBytes));
// ...
CreateContractResponse resp = client.createContract(req);

Python

from flashsign_sdk import FlashSignClient

client = FlashSignClient(
    app_key='app_xxxxxx',
    app_secret='your_secret',
    env='sandbox'  # 'sandbox' | 'production'
)

contract = client.create_contract(
    contract_name='技术服务协议',
    contract_file=base64.b64encode(file_bytes).decode(),
    signers=[{
        'name': '张三',
        'phone': '13800138000',
        'role': 'signer'
    }]
)
print(contract.data.contract_id)

Go

import "github.com/flashsign/flashsign-sdk-go"

client := flashsign.NewClient(flashsign.Config{
    AppKey:    "app_xxxxxx",
    AppSecret: "your_secret",
    Env:       flashsign.EnvSandbox,
})

resp, err := client.CreateContract(&flashsign.CreateContractRequest{
    ContractName: "技术服务协议",
    ContractFile: base64Content,
    Signers: []flashsign.Signer{
        {Name: "张三", Phone: "13800138000", Role: "signer"},
    },
})

安全建议

API Secret 使用密钥管理服务（HashiCorp Vault、AWS KMS 等）安全存储
定期轮换 API 密钥（建议每 90 天轮换一次）
生产环境和沙箱环境使用不同密钥
API 调用日志中掩码或移除敏感字段（手机号、身份证号等）
为 API 调用设置 IP 白名单（控制台 → 安全设置）
异常调用（签名失败、频率超限）设置告警通知

开发指南

合同签署接口

参数

说明

安全要求

AppKey

应用唯一标识，用于识别调用方身份

可在请求中明文传输

AppSecret

应用密钥，用于计算请求签名

仅保存在服务端，绝不可暴露

import cn.flashsign.sdk.FlashSignClient; import cn.flashsign.sdk.model.*; // 初始化客户端（自动处理签名） FlashSignClient client = new FlashSignClient.Builder() .appKey("app_xxxxxx") .appSecret("your_secret") .env(Env.SANDBOX) // SANDBOX | PRODUCTION .build(); // 发起合同 CreateContractRequest req = new CreateContractRequest(); req.setContractName("技术服务协议"); req.setContractFile(Base64.getEncoder().encodeToString(fileBytes)); // ... CreateContractResponse resp = client.createContract(req);

from flashsign_sdk import FlashSignClient client = FlashSignClient( app_key='app_xxxxxx', app_secret='your_secret', env='sandbox' # 'sandbox' | 'production' ) contract = client.create_contract( contract_name='技术服务协议', contract_file=base64.b64encode(file_bytes).decode(), signers=[{ 'name': '张三', 'phone': '13800138000', 'role': 'signer' }] ) print(contract.data.contract_id)

import "github.com/flashsign/flashsign-sdk-go" client := flashsign.NewClient(flashsign.Config{ AppKey: "app_xxxxxx", AppSecret: "your_secret", Env: flashsign.EnvSandbox, }) resp, err := client.CreateContract(&flashsign.CreateContractRequest{ ContractName: "技术服务协议", ContractFile: base64Content, Signers: []flashsign.Signer{ {Name: "张三", Phone: "13800138000", Role: "signer"}, }, })