282 lines
9.1 KiB
Markdown
282 lines
9.1 KiB
Markdown
文档类型：混合型（前三个接口为调用方需调用的供应商接口，第四个接口为行方需提供的回调接口，即服务端骨架）
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 接口一：卡券/直充权益下单接口
|
||
|
||
- **接口名称**：卡券/直充权益下单接口
|
||
- **接口描述**：适用于卡密，直充商品下单
|
||
- **请求方式**：POST
|
||
- **报文格式**：content-type: application/json
|
||
- **接口地址**：（文档未提供，需双方约定）
|
||
|
||
#### 入参说明
|
||
|
||
**通用请求参数（请求头）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 取值说明 |
|
||
|--------|------|------|------|----------|
|
||
| timestamp | 是 | String | 时间戳 | 毫秒级时间戳 |
|
||
| sign | 是 | String | 签名 | 见签名规则 |
|
||
|
||
**通用请求参数（请求体）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 取值说明 |
|
||
|--------|------|------|------|----------|
|
||
| encryptedData | 是 | String | 加密数据 | json格式业务数据进行SM4加密 |
|
||
|
||
**业务数据参数（加密前JSON）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 取值说明 |
|
||
|--------|------|------|------|----------|
|
||
| actCode | 是 | String | 活动code | 可约定为各供应商的项目编号和密钥的拼接加密字符串 |
|
||
| goodsCode | 是 | String | 商品code | 供应商商品编号 |
|
||
| actOrderNum | 是 | String | 活动方订单号 | 唯一，行内活动订单号 |
|
||
| account | 否 | String | 充值账号 | |
|
||
| callbackUrl | 否 | String | 回调地址 | |
|
||
|
||
**示例（加密前）**
|
||
```json
|
||
{
|
||
"actCode": "ACT001",
|
||
"goodsCode": "123456",
|
||
"actOrderNum": "00001",
|
||
"account": "19912345678",
|
||
"callbackUrl": "https://xxx/notice"
|
||
}
|
||
```
|
||
|
||
#### 响应消息
|
||
|
||
**公共响应参数**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| code | 是 | int | 返回状态编码 | 0成功 -1失败 |
|
||
| msg | 是 | String | 返回错误信息 | |
|
||
| data | 否 | Object | 返回数据 | JSON格式业务数据进行SM4加密 |
|
||
|
||
**响应参数名称（data解密后）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| orderNo | 是 | String | 权益订单号 | 唯一，供应商订单号 |
|
||
| couponNo | 否 | String | 卡号 | 卡券/短链类商品返回 |
|
||
| couponCode | 否 | String | 卡密 | 卡券类商品返回 |
|
||
| status | 是 | Integer | 状态 | -1发放中 0成功 1失败 2已核销 3已过期 |
|
||
| expireTime | 否 | String | 有效期 | 卡券/短链类商品返回，格式：yyyy-MM-dd HH:mm:SS |
|
||
|
||
**示例（解密后）**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "请求成功",
|
||
"data": "{\"orderNo\":\"HM17575805323790000127073398f3772c00\",\"expireTime\":\"2025-09-12 00:00:00\",\"couponNo\":\"27073398f3772c00\",\"couponCode\":\"27073398f3772c00\",\"status\":1}"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 接口二：卡券/直充/微信立减金订单查询接口
|
||
|
||
- **接口名称**：卡券/直充/微信立减金订单查询接口
|
||
- **接口描述**：行内通过供应商订单号查询订单状态接口
|
||
- **请求方式**：POST
|
||
- **报文格式**：content-type: application/json
|
||
- **接口地址**：（文档未提供，需双方约定）
|
||
|
||
#### 入参说明
|
||
|
||
**通用请求参数（请求头）** 同接口一
|
||
|
||
**通用请求参数（请求体）** 同接口一
|
||
|
||
**业务数据参数（加密前JSON）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 取值说明 |
|
||
|--------|------|------|------|----------|
|
||
| actCode | 是 | String | 活动code | 可约定为各供应商的项目编号和密钥的拼接加密字符串 |
|
||
| orderNo | 是 | String | 供应商订单号 | |
|
||
|
||
**示例（加密前）**
|
||
```json
|
||
{
|
||
"actCode": "FBG6vdYqGE4mGX7EH/woEg==",
|
||
"orderNo": "HM1757046717684000102707339840b23222"
|
||
}
|
||
```
|
||
|
||
#### 响应消息
|
||
|
||
**公共响应参数** 同接口一
|
||
|
||
**响应参数名称（data解密后）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| orderNo | 是 | String | 权益订单号 | 唯一，供应商订单号 |
|
||
| status | 是 | Integer | 订单状态 | -1发放中 0成功 1失败 2已核销 3已过期 |
|
||
| account | 否 | String | 充值账号 | 直充类型时存在 |
|
||
| cardInfo | 否 | Object | 卡券信息 | 卡券/短链类型时存在 |
|
||
| - couponNo | 是 | String | 卡号/短链 | |
|
||
| - couponCode | 是 | String | 卡密 | |
|
||
| - expireTime | 是 | String | 过期时间 | 格式：yyyy-MM-dd HH:mm:ss |
|
||
| couponId | 是 | String | 优惠id | 微信立减金类型时存在 |
|
||
|
||
**示例（解密后）**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "请求成功",
|
||
"data": "{\"orderNo\":\"HM1757046717684000102707339840b23222\",\"cardInfo\":\"{\\\"couponNo\\\":\\\"11111\\\",\\\"couponCode\\\":\\\"12334\\\",\\\"expireTime\\\":\\\"2029-03-09 00:00:00\\\"}\",\"status\":3}"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 接口三：微信立减金订单充值接口
|
||
|
||
- **接口名称**：微信立减金订单充值接口
|
||
- **请求方式**：POST
|
||
- **报文格式**：content-type: application/json
|
||
- **接口地址**：（文档未提供，需双方约定）
|
||
|
||
#### 入参说明
|
||
|
||
**通用请求参数（请求头）** 同接口一
|
||
|
||
**通用请求参数（请求体）** 同接口一
|
||
|
||
**业务数据参数（加密前JSON）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 取值说明 |
|
||
|--------|------|------|------|----------|
|
||
| actCode | 是 | String | 活动code | 可约定为各供应商的项目编号和密钥的拼接加密字符串 |
|
||
| orderNo | 是 | String | 供应商订单号 | |
|
||
| goodsCode | 是 | String | 商品code | 供应商商品编号 |
|
||
| actOrderNum | 是 | String | 活动方订单号 | 唯一，行内订单号 |
|
||
| appId | 是 | String | 公众账号ID | |
|
||
| openId | 是 | String | 微信用户标识 | 需要与 appId 绑定（同一个 appId 下的 openId） |
|
||
| callbackUrl | 否 | String | 回调地址 | |
|
||
|
||
**示例（加密前）**
|
||
```json
|
||
{
|
||
"actCode": "FBG6vdYqGE4mGX7EH/woEg==",
|
||
"goodsCode": "0001",
|
||
"actOrderNum": "0001",
|
||
"openId": "0001",
|
||
"appId": "00001"
|
||
}
|
||
```
|
||
|
||
#### 响应消息
|
||
|
||
**公共响应参数** 同接口一
|
||
|
||
**响应参数名称（data解密后）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| orderNo | 是 | String | 权益订单号 | 唯一，供应商订单号 |
|
||
| status | 是 | Integer | 订单状态 | -1发放中 0成功 1失败 2已核销 3已过期 |
|
||
| couponId | 是 | String | 微信优惠id | 微信该批次立减金的优惠id |
|
||
|
||
**示例（解密后）**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "请求成功",
|
||
"data": "{\"orderNo\":\"0001\",\"couponId\":\"123456\",\"status\":1}"
|
||
}
|
||
```
|
||
```json
|
||
{
|
||
"code": -1,
|
||
"msg": "库存不足",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 接口四：卡券/直充/微信立减金充值结果通知接口（行方回调接口）
|
||
|
||
- **接口名称**：卡券/直充/微信立减金充值结果通知接口
|
||
- **接口路径**：行内提供回调地址（需双方约定）
|
||
- **请求方式**：POST
|
||
- **报文格式**：content-type: application/json
|
||
|
||
#### 入参说明
|
||
|
||
**通用请求参数（请求头）** 同接口一
|
||
|
||
**通用请求参数（请求体）** 同接口一
|
||
|
||
**业务数据参数（加密前JSON）**
|
||
|
||
| 参数名 | 必填 | 类型 | 描述 | 取值说明 |
|
||
|--------|------|------|------|----------|
|
||
| orderNo | 是 | String | 供应商订单号 | 唯一，供应商订单号 |
|
||
| actOrderNum | 是 | String | 活动方订单号 | 唯一，行内订单号 |
|
||
| status | 是 | Integer | 订单状态 | -1发放中 0成功 1失败 2已核销 3已过期 |
|
||
| account | 否 | String | 直充账号 | 直充类型商品时存在 |
|
||
| cardInfo | 否 | Object | 卡券信息 | 卡券/短链类型商品时存在 |
|
||
| - couponNo | 是 | String | 卡号/短链 | |
|
||
| - couponCode | 是 | String | 卡密 | |
|
||
| - expireTime | 是 | String | 卡券过期时间 | |
|
||
| couponId | 否 | String | 微信优惠id | 微信立减金类型商品时存在 |
|
||
|
||
**示例（加密前）**
|
||
```json
|
||
{
|
||
"orderNo":"HM202509291010001",
|
||
"actOrderNum":"XY2025092910100001",
|
||
"status":3,
|
||
"account":"19912345678"
|
||
}
|
||
```
|
||
|
||
#### 响应消息（行方需返回）
|
||
|
||
| 状态码 | 返回内容 | 说明 |
|
||
|--------|----------|------|
|
||
| 200 | ok | 接收成功，系统认为回调已处理成功，不会重试 |
|
||
| 其它 | 任意内容 | 系统认为接收失败，将按重试策略重试，最多3次 |
|
||
|
||
---
|
||
|
||
## 认证/加密/签名细节
|
||
|
||
### 需要双方约定的参数
|
||
- SM3 salt（盐值）
|
||
- SM4 key（密钥）
|
||
- 供应商侧测试及生产环境的ip/域名和接口地址
|
||
- 行方回调通知接口地址
|
||
|
||
### 签名规则
|
||
- 签名内容：`timestamp + encryptedData` 字符串拼接
|
||
- 签名算法：SM3加盐（使用约定的SM3 salt）
|
||
- 签名示例（Java hutool工具）：
|
||
```java
|
||
import cn.hutool.crypto.SmUtil;
|
||
String sign = SmUtil.sm3WithSalt(sm3Salt.getBytes()).digestHex(timestamp + encryptedData);
|
||
```
|
||
- 签名值放入请求头 `sign` 字段
|
||
|
||
### 加密规则
|
||
- 业务数据（JSON格式）使用SM4加密，得到字符串放入请求体 `encryptedData` 字段
|
||
- 响应中的 `data` 字段也是SM4加密后的JSON字符串，需解密后使用
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| code | 含义 |
|
||
|------|------|
|
||
| 0 | 成功 |
|
||
| -1 | 失败（具体错误信息见 msg 字段） |
|
||
|
||
注：回调接口的响应状态码200且返回内容为"ok"表示成功，其他状态码或内容视为失败，会重试最多3次。 |