菜单

验签参数以及验签的工具【产研】

1. 文档概述

为确保API调用过程中的数据安全性与请求合法性，牛信云开放平台对所有接口请求实施了基于MD5或SHA-256的签名机制。调用方必须在每个请求的Header中包含根据特定算法生成的数字签名（sign），平台服务器会验证此签名，签名不合法或已过期的请求将被拒绝。

本文档详细说明了签名算法、必备参数、生成步骤，并提供了签名模拟器工具和多种编程语言的完整验签工具示例。

2. 必备公共参数

所有API调用都必须在HTTP请求头（Header） 中包含以下公共参数：

参数名称	类型	是否必填	示例值	描述
`accessKey`	String	是	`fme2na3kdi3ki`	用户身份标识，在平台控制台获取。
`ts`	String	是	`1655710885431`	当前请求的13位时间戳（毫秒）。服务器允许最大时间误差为±60000毫秒。
`bizType`	String	是	`1`	业务类型，详见下方`bizType`参数说明。
`action`	String	是	`send`	API接口方法，值参照具体API接口文档。
`sign`	String	是	`6e9506557d1f289501d333ee2c365826`	API入参签名，根据算法生成。
`algorithm`	String	否	`md5`	签名哈希算法，可选`md5`或`sha256`，默认`md5`。

`bizType`参数说明

参数值	业务描述
1	号码检测
2	WhatsApp业务
3	短信
4	DID业务
5	隐私号
6	OTA
7	Viber
8	Voice语音业务
9	Zalo通知服务业务

3. 签名生成算法

签名算法根据请求的Content-Type有所不同。

3.1 算法规则

对于 Content-Type: application/json的接口：

sign = hex(md5(headersStr + bodyStr + accessSecretStr))
对于 Content-Type: multipart/form-data的接口：

sign = hex(md5(headersStr + accessSecretStr))

3.2 生成步骤（以 `application/json`为例）

步骤1：拼接Header参数字符串 (headersStr)

取全部必传的Header参数（不包括sign和algorithm），按参数名ASCII码升序排序，以 key=value格式，用 &连接。

格式：accessKey=YOUR_ACCESS_KEY&action=ACTION&bizType=BIZ_TYPE&ts=TIMESTAMP

步骤2：拼接Body参数字符串 (bodyStr)

如果请求Body为有效的非空JSON字符串，则在headersStr后拼接 &body=和完整的Body字符串。
注意：计算签名时使用的Body字符串必须与HTTP请求中发送的Body完全一致（包括空格、换行符、字段顺序等）。

步骤3：拼接访问密钥 (accessSecretStr)

在步骤2得到的字符串末尾拼接 &accessSecret=YOUR_ACCESS_SECRET。

步骤4：计算签名

使用指定的哈希算法（默认MD5）计算步骤3所得字符串的哈希值。
将哈希值的字节流结果转换为十六进制小写字符串，即得到最终的sign值。

4. 调用示例（代码示例）

为帮助开发者理解上述签名算法，官方文档中提供了 Java, C#, PHP, Python, Go 等多种编程语言的完整代码示例。

建议您直接访问官方文档页面查看代码示例：

👉 牛信云开放平台 - 接口合约（含代码示例） https://www.nxcloud.com/document/common/interface-contract#cjcwm

通过阅读官方示例，您可以更直观地掌握每一步的拼接逻辑和加密方法。

5. 常见错误码

错误码	错误信息	原因与解决方案
1001	Missing common parameters	Header中缺少必填的公共参数。检查参数是否完整。
1003	Invalid signature	签名无效。这是最常见错误。1) 使用签名模拟器进行验证；2) 检查`Content-Type`是否正确；3) 确保计算签名用的Body与发送的Body完全一致；4) 检查`accessSecret`是否正确；5) 按本文档步骤检查签名计算过程。
1004	Timestamp has expired	时间戳`ts`已过期。确保发送13位毫秒时间戳，并且与服务器时间差在±60秒内。
1005	Insufficient permissions	`accessKey`错误或当前账号无该业务权限。

6. 签名模拟器（工具）使用说明

为帮助开发者快速验证签名计算过程、排查“签名无效”错误，平台在控制台左侧导航栏特别提供了“签名模拟器”在线工具。

6.1 工具入口

登录NXCloud控制台，在左侧导航菜单中找到并点击 “签名模拟器” 即可进入。

6.2 操作界面与参数填写

工具界面如下图所示，请依次填写或选择以下参数：

（此处可插入您提供的工具截图）

BizType：选择业务类型，如“短信”、“WhatsApp业务”等。
AccessKey：填写您的accessKey。
Action：填写您要调用的接口方法名，如“send”。
Ts：填写13位时间戳。您可以直接输入，或点击右侧的 “生成” 按钮，系统会自动填入当前时间戳。
Algorithm：选择签名算法，支持MD5和SHA256。
Content-Type：根据您的接口选择，通常为application/json。
Request Body (JSON)：如果接口需要Body，在此处填入完整的JSON字符串。请务必确保此处的JSON格式与您最终API请求的Body完全一致。
AccessSecret：输入您的accessSecret（非常重要，请确保正确且保密）。

6.3 生成与验证签名

填写完所有参数后，点击页面底部的 “生成签名” 按钮。

结果获取：生成的sign签名值将显示在按钮下方的结果框中。
验证与调试：
- 将模拟器生成的sign值，与您程序计算出的sign值进行比较。
- 如果两者不一致，请逐一核对每个参数的取值，特别是Body字符串的格式、空格、换行和字段顺序。
- 您可以通过对比，快速定位是哪个步骤或参数输入有误。

6.4 核心价值与最佳实践

快速排错：当API调用因“签名无效”失败时，第一时间使用此工具，用相同的参数生成签名，进行比对。
理解算法：通过修改参数观察签名变化，可以直观理解签名算法的拼接过程。
安全便捷：该工具在您的浏览器本地运行，AccessSecret等敏感参数不会被发送到服务器，请放心使用。

最近修改: 2026-01-18Powered by

大纲