接入指南

本文档面向第三方接入方技术人员，重点说明开放平台 API 的 签名与验签机制。

1. 概述

开放平台所有接口均要求进行请求签名校验，同时对响应内容进行签名，以便接入方校验响应数据的完整性与真实性。

签名算法：SHA256 with RSA（RSA 2048，签名结果 Base64 编码）

签名协议标识：WXH-SHA256-RSA2048

传输协议：HTTPS

数据格式：请求/响应体均为 application/json

2. 接入准备

APPID、密钥交换通过线下业务对接完成，请联系平台商务/技术对接人。

2.1 密钥准备

平台接入方需自行生成一对 RSA 2048 密钥（PKCS#1 或 PKCS#8 格式，PEM 编码）：

密钥	持有方	用途
接入方私钥	接入方（严格保密，切勿外传）	对请求进行签名
接入方公钥	提交给平台	平台对请求进行验签
平台私钥	平台持有	平台对响应进行签名
平台公钥	平台线下提供给接入方	接入方对响应进行验签

接入方完成以下事项后即可联调：

生成 RSA 2048 密钥对；

将接入方公钥提供给平台，平台完成登记后分配 APPID（16 位字符串）；

从平台获取平台公钥与接口域名（测试环境 / 生产环境）。

2.2 密钥生成示例（openssl）

3. 签名机制（重点）

3.1 整体流程

接入方                                          平台
  │                                              │
  │ 1. 用接入方私钥对请求内容签名                    │
  │    Authorization: WXH-SHA256-RSA2048 ...     │
  │ ────────────────────────────────────────────> │
  │                2. 平台用接入方公钥验签             │
  │                                              │
  │    响应头: Wxh-Timestamp / Wxh-Nonce /         │
  │           Wxh-Signature（平台私钥签名）          │
  │ <──────────────────────────────────────────── │
  │ 3. 接入方用平台公钥对响应验签                     │

3.2 请求签名

3.2.1 构造待签名串

待签名串由 5 个部分按顺序拼接，每个部分之后都跟一个换行符 \n：

{HTTPMethod}
{URI}
{Timestamp}
{Nonce}
{Body}

字段	说明
`HTTPMethod`	HTTP 方法，大写，如 `GET`、`POST`、`PUT`
`URI`	请求 URI，包含接口路径与 Query String，如 `/v1/open/orders`、`/v1/open/orders?order_no=123`
`Timestamp`	Unix 时间戳（秒，纯数字），如 `1756700000`
`Nonce`	随机字符串，长度不超过 128，建议使用随机数并保证不重复（防重放）
`Body`	请求体原始字符串（`application/json` 序列化后的原文）；`GET` 等无请求体的方法使用空字符串

注意：参与签名的 Body 必须与实际发送的请求体逐字节一致（包括字段顺序、空格、转义等），否则验签失败。建议先序列化出最终请求体字符串，再用该字符串发起请求。

示例（下单请求）：

POST
/v1/open/orders
1756700000
a1b2c3d4e5f6
{"order_no":"SN202609010001","receiver":{"name":"张三"}}

（每行末尾均有换行符 \n，包括最后一行）

3.2.2 计算签名

使用接入方私钥对待签名串执行 SHA256withRSA 签名，并将签名结果进行 Base64 编码：

Signature = Base64( RSA_SHA256_Sign( 待签名串, 接入方私钥 ) )

3.2.3 组装 Authorization 请求头

将签名结果放入 Authorization 请求头，格式如下：

WXH-SHA256-RSA2048 appid="{APPID}",timestamp="{Timestamp}",nonce="{Nonce}",signature="{Signature}"

格式要求：

以协议标识 WXH-SHA256-RSA2048 开头，后跟一个空格；

各参数以英文逗号 , 分隔（逗号后无空格）；

每个参数值必须使用英文双引号包裹；

仅允许包含 appid、timestamp、nonce、signature 四个参数；

appid 为 16 位字符串；timestamp 为秒级 Unix 时间戳；nonce 长度 ≤ 128；signature 为 Base64 字符串。

完整示例：

Authorization: WXH-SHA256-RSA2048 appid="Ks92mXwQ7pLz3VbN",timestamp="1756700000",nonce="a1b2c3d4e5f6",signature="dGhpcyBpcyBhIGJhc2U2NCBzaWduYXR1cmU..."

3.3 响应验签

平台对每个响应（包括验签失败的错误响应）都会使用平台私钥进行签名，签名信息放在响应头中：

响应头	说明
`Wxh-Timestamp`	平台签名时使用的时间戳（秒）
`Wxh-Nonce`	平台签名时使用的随机串
`Wxh-Signature`	响应签名（Base64 编码）

接入方按如下方式验签：

构造待验证串（每行末尾均有换行符 \n）：

{Wxh-Timestamp}\n{Wxh-Nonce}\n{ResponseBody}\n

其中 ResponseBody 为响应体原始字符串（不要先反序列化再重新序列化）。

使用平台公钥执行 SHA256withRSA 验签：

RSA_SHA256_Verify( 待验证串, Base64Decode(Wxh-Signature), 平台公钥 ) == true

验签失败时，应视为响应数据不可信，建议重试或联系平台排查。

3.4 响应报文结构

响应体统一为 JSON：

{
    "code": "000000",
    "msg": "请求处理成功",
    "data": { }
}

字段	说明
`code`	业务状态码，字符串。`000000` 表示成功
`msg`	提示信息
`data`	业务数据

签名相关错误码：

code	说明
`000000`	成功
`100102`	签名/授权校验失败，`msg` 中为具体原因

100102 常见原因：

msg	可能原因
签名格式错误！	`Authorization` 未以 `WXH-SHA256-RSA2048` 开头
请求签名包含无效信息！	携带了 `appid/timestamp/nonce/signature` 之外的参数
请求签名信息错误！	缺少必填参数或参数为空
appid格式错误！	`appid` 不是 16 位
timestamp格式错误！	`timestamp` 不是秒级 Unix 时间戳
nonce格式错误！	`nonce` 长度超过 128
signature格式错误！	`signature` 超长
应用不存在	`appid` 未在平台登记
签名验证失败	待签名串拼装错误或使用了错误的私钥/公钥

4. 示例代码（PHP）

以下示例与平台官方 SDK 的签名实现一致，可直接参考移植到其他语言。

4.1 请求签名并发起调用

4.2 GET 请求说明

GET 请求 Body 参与签名时使用空字符串，注意待签名串末尾仍需保留对应换行符：

GET
/v1/open/orders?order_no=SN202609010001
{timestamp}
{nonce}

4.3 使用 openssl 命令行辅助调试

5. 接入注意事项

私钥安全：接入方私钥仅保存在服务端安全环境中，严禁写入客户端、日志或通过网络传输。

请求体一致性：签名使用的请求体与实际发送的请求体必须逐字节一致；建议统一由同一个序列化结果完成签名与发送。

URI 一致性：签名使用的 URI 需包含实际请求携带的 Query String，且与实际请求一致。

时间戳：请使用服务器当前时间（秒级），避免使用本地客户端时间导致偏差。

验签失败排查顺序：Authorization 头格式 → 待签名串拼接（换行符）→ 请求体一致性 → 密钥是否配对/用反。

密钥更换：如需更换密钥，请联系平台对接人线下重新登记公钥。

6. 联调与支持

接口域名、APPID、平台公钥均由平台在线下业务对接时提供；

测试环境联调通过后，切换生产环境时请联系平台对接人确认；

接口清单与字段定义见平台提供的接口文档。

1. 概述#

2. 接入准备#

2.1 密钥准备#

2.2 密钥生成示例（openssl）#

3. 签名机制（重点）#

3.1 整体流程#

3.2 请求签名#

3.2.1 构造待签名串#

3.2.2 计算签名#

3.2.3 组装 Authorization 请求头#

3.3 响应验签#

3.4 响应报文结构#

4. 示例代码（PHP）#

4.1 请求签名并发起调用#

4.2 GET 请求说明#

4.3 使用 openssl 命令行辅助调试#

5. 接入注意事项#

6. 联调与支持#