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