添加 README 文档
This commit is contained in:
parent
8a9147a270
commit
16b40c7e7b
|
|
@ -0,0 +1,238 @@
|
|||
## 文档概述
|
||||
- 接口总数：4个
|
||||
|
||||
## 认证与安全
|
||||
### 约定前置参数
|
||||
1. SM3 salt：双方预先约定的盐值
|
||||
2. SM4 key：双方预先约定的加密密钥
|
||||
3. 供应商侧测试及生产环境的ip/域名和接口地址
|
||||
4. 行方回调通知接口地址
|
||||
|
||||
### 加密与签名规则
|
||||
1. 业务数据加密：所有业务参数JSON字符串使用SM4算法加密，得到encryptedData字段
|
||||
2. 签名生成规则：将毫秒级时间戳timestamp字符串与encryptedData字符串直接拼接，使用SM3算法结合预先约定的SM3 salt进行加密，最终输出十六进制字符串作为sign值
|
||||
3. 签名示例代码：
|
||||
```java
|
||||
import cn.hutool.crypto.SmUtil;
|
||||
String sign = SmUtil.sm3WithSalt(sm3Salt.getBytes()).digestHex(timestamp+ encryptedData);
|
||||
```
|
||||
4. 所有接口请求头必须携带timestamp和sign两个参数，请求体为encryptedData加密字符串，Content-Type统一为application/json
|
||||
|
||||
## 接口列表
|
||||
### 接口 1：卡券/直充权益下单接口
|
||||
- 路径：双方约定的供应商下单接口地址
|
||||
- 方法：POST
|
||||
- 描述：适用于卡密，直充商品下单
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| 请求头参数 | - | - | - |
|
||||
| timestamp | String | 是 | 毫秒级时间戳 |
|
||||
| sign | String | 是 | 签名，见签名规则 |
|
||||
| 请求体参数 | - | - | - |
|
||||
| encryptedData | String | 是 | json格式业务数据进行SM4加密后的字符串 |
|
||||
| 加密后业务参数（解密后） | - | - | - |
|
||||
| actCode | String | 是 | 活动code，可约定为各供应商的项目编号和密钥的拼接加密字符串 |
|
||||
| goodsCode | String | 是 | 供应商商品编号 |
|
||||
| actOrderNum | String | 是 | 活动方订单号，唯一，行内活动订单号 |
|
||||
| account | String | 否 | 充值账号 |
|
||||
| callbackUrl | String | 否 | 回调地址 |
|
||||
|
||||
#### 响应参数
|
||||
| 参数名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| 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
|
||||
{
|
||||
"actCode": "ACT001",
|
||||
"goodsCode": "123456",
|
||||
"actOrderNum": "00001",
|
||||
"account": "19912345678",
|
||||
"callbackUrl": "https://xxx/notice"
|
||||
}
|
||||
```
|
||||
- 解密后响应示例：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "请求成功",
|
||||
"data": "{\"orderNo\":\"HM17575805323790000127073398f3772c00\",\"expireTime\":\"2025-09-12 00:00:00\",\"couponNo\":\"27073398f3772c00\",\"couponCode\":\"27073398f3772c00\",\"status\":1}"
|
||||
}
|
||||
```
|
||||
|
||||
### 接口 2：卡券/直充/微信立减金订单查询接口
|
||||
- 路径：双方约定的供应商查询接口地址
|
||||
- 方法：POST
|
||||
- 描述：行内通过供应商订单号查询订单状态接口
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| 请求头参数 | - | - | - |
|
||||
| timestamp | String | 是 | 毫秒级时间戳 |
|
||||
| sign | String | 是 | 签名，见签名规则 |
|
||||
| 请求体参数 | - | - | - |
|
||||
| encryptedData | String | 是 | json格式业务数据进行SM4加密后的字符串 |
|
||||
| 加密后业务参数（解密后） | - | - | - |
|
||||
| actCode | String | 是 | 活动code，可约定为各供应商的项目编号和密钥的拼接加密字符串 |
|
||||
| orderNo | String | 是 | 供应商订单号 |
|
||||
|
||||
#### 响应参数
|
||||
| 参数名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| code | int | 返回状态编码，0成功 -1失败 |
|
||||
| msg | String | 返回错误信息 |
|
||||
| data | Object | JSON格式业务数据进行SM4加密后的字符串 |
|
||||
| 解密后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
|
||||
{
|
||||
"actCode": "FBG6vdYqGE4mGX7EH/woEg==",
|
||||
"orderNo": "HM1757046717684000102707339840b23222"
|
||||
}
|
||||
```
|
||||
- 解密后响应示例：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "请求成功",
|
||||
"data": "{\"orderNo\":\"HM1757046717684000102707339840b23222\",\"cardInfo\":\"{\\\"couponNo\\\":\\\"11111\\\",\\\"couponCode\\\":\\\"12334\\\",\\\"expireTime\\\":\\\"2029-03-09 00:00:00\\\"}\",\"status\":3}"
|
||||
}
|
||||
```
|
||||
|
||||
### 接口 3：微信立减金订单充值接口
|
||||
- 路径：双方约定的微信立减金充值接口地址
|
||||
- 方法：POST
|
||||
- 描述：微信立减金订单充值
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| 请求头参数 | - | - | - |
|
||||
| timestamp | String | 是 | 毫秒级时间戳 |
|
||||
| sign | String | 是 | 签名，见签名规则 |
|
||||
| 请求体参数 | - | - | - |
|
||||
| encryptedData | String | 是 | json格式业务数据进行SM4加密后的字符串 |
|
||||
| 加密后业务参数（解密后） | - | - | - |
|
||||
| actCode | String | 是 | 活动code，可约定为各供应商的项目编号和密钥的拼接加密字符串 |
|
||||
| orderNo | String | 是 | 供应商订单号 |
|
||||
| goodsCode | String | 是 | 供应商商品编号 |
|
||||
| actOrderNum | String | 是 | 活动方订单号，唯一，行内订单号 |
|
||||
| appId | String | 是 | 公众账号ID |
|
||||
| openId | String | 是 | 微信用户标识，需要与 appId 绑定（同一个 appId 下的 openId） |
|
||||
| callbackUrl | String | 否 | 回调地址 |
|
||||
|
||||
#### 响应参数
|
||||
| 参数名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| code | int | 返回状态编码，0成功 -1失败 |
|
||||
| msg | String | 返回错误信息 |
|
||||
| data | Object | json格式业务数据进行SM4加密后的字符串 |
|
||||
| 解密后data业务参数 | - | - |
|
||||
| orderNo | String | 权益订单号，唯一，供应商订单号 |
|
||||
| status | Integer | 订单状态，-1发放中 0成功 1失败 2已核销 3已过期 |
|
||||
| couponId | String | 微信优惠id，微信该批次立减金的优惠id |
|
||||
|
||||
#### 示例
|
||||
- 加密前业务请求示例：
|
||||
```json
|
||||
{
|
||||
"actCode": "FBG6vdYqGE4mGX7EH/woEg==",
|
||||
"goodsCode": "0001",
|
||||
"actOrderNum": "0001",
|
||||
"openId": "0001",
|
||||
"appId": "00001"
|
||||
}
|
||||
```
|
||||
- 解密后响应示例：
|
||||
成功响应：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "请求成功",
|
||||
"data": "{\"orderNo\":\"0001\",\"couponId\":\"123456\",\"status\":1}"
|
||||
}
|
||||
```
|
||||
失败响应：
|
||||
```json
|
||||
{
|
||||
"code": -1,
|
||||
"msg": "库存不足",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 接口 4：卡券/直充/微信立减金充值结果通知接口
|
||||
- 路径：行方提供的回调地址
|
||||
- 方法：POST
|
||||
- 描述：供应商主动推送充值结果通知给行方
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| 请求头参数 | - | - | - |
|
||||
| timestamp | String | 是 | 毫秒级时间戳 |
|
||||
| sign | String | 是 | 签名，见签名规则 |
|
||||
| 请求体参数 | - | - | - |
|
||||
| encryptedData | String | 是 | json格式业务数据进行SM4加密后的字符串 |
|
||||
| 加密后业务参数（解密后） | - | - | - |
|
||||
| orderNo | String | 是 | 供应商订单号，唯一 |
|
||||
| actOrderNum | String | 是 | 活动方订单号，唯一，行内订单号 |
|
||||
| status | Integer | 是 | 订单状态，-1发放中 0成功 1失败 2已核销 3已过期 |
|
||||
| account | String | 否 | 直充账号，直充类型商品时存在 |
|
||||
| cardInfo | Object | 否 | 卡券信息，卡券/短链类型商品时存在 |
|
||||
| -couponNo | String | 是 | 卡号/短链，卡券/短链类型商品时存在 |
|
||||
| -couponCode | String | 是 | 卡密，卡券类型商品时存在 |
|
||||
| -expireTime | String | 是 | 卡券过期时间，卡券/短链类型商品时存在 |
|
||||
| couponId | String | 否 | 微信优惠id，微信立减金类型商品时存在 |
|
||||
|
||||
#### 响应参数
|
||||
| 参数名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| HTTP状态码200 | String | 返回内容为ok，代表接收成功，系统认为回调已处理成功，不会重试 |
|
||||
| HTTP状态码非200 | 任意内容 | 系统认为接收失败，将按重试策略重试，最多3次 |
|
||||
|
||||
#### 示例
|
||||
- 加密前回调业务参数示例：
|
||||
```json
|
||||
{
|
||||
"orderNo":"HM202509291010001",
|
||||
"actOrderNum":"XY2025092910100001",
|
||||
"status":3,
|
||||
"account":"19912345678"
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码
|
||||
| 错误码 | 说明 | 处理建议 |
|
||||
|--------|------|----------|
|
||||
| 0 | 请求成功 | 正常处理返回数据 |
|
||||
| -1 | 请求失败 | 读取msg字段获取具体失败原因，例如库存不足等 |
|
||||
|
||||
## 回调通知
|
||||
回调机制说明：
|
||||
1. 供应商在订单状态发生变更时，主动调用行方提供的回调通知接口推送最新订单状态
|
||||
2. 回调请求同样遵循SM4加密、SM3签名的安全规则
|
||||
3. 行方收到回调后，校验签名、解密数据处理完成后，必须返回HTTP 200状态码且响应内容为ok，否则供应商侧会进行重试，最多重试3次
|
||||
Loading…
Reference in New Issue