xy-shanghai-20260721-181118/refine.md at main

9.1 KiB

Raw Permalink Blame History

文档类型：混合型（前三个接口为调用方需调用的供应商接口，第四个接口为行方需提供的回调接口，即服务端骨架）

接口列表

接口一：卡券/直充权益下单接口

接口名称：卡券/直充权益下单接口
接口描述：适用于卡密，直充商品下单
请求方式：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	回调地址

示例（加密前）

{
  "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

示例（解密后）

{
  "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	供应商订单号

示例（加密前）

{
  "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	微信立减金类型时存在

示例（解密后）

{
  "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	回调地址

示例（加密前）

{
  "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

示例（解密后）

{
  "code": 0,
  "msg": "请求成功",
  "data": "{\"orderNo\":\"0001\",\"couponId\":\"123456\",\"status\":1}"
}

{
  "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	微信立减金类型商品时存在

示例（加密前）

{
  "orderNo":"HM202509291010001",
  "actOrderNum":"XY2025092910100001",
  "status":3,
  "account":"19912345678"
}

响应消息（行方需返回）

状态码	返回内容	说明
200	ok	接收成功，系统认为回调已处理成功，不会重试
其它	任意内容	系统认为接收失败，将按重试策略重试，最多3次

认证/加密/签名细节

需要双方约定的参数

SM3 salt（盐值）
SM4 key（密钥）
供应商侧测试及生产环境的ip/域名和接口地址
行方回调通知接口地址

签名规则

签名内容：timestamp + encryptedData 字符串拼接
签名算法：SM3加盐（使用约定的SM3 salt）
签名示例（Java hutool工具）：

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次。

9.1 KiB Raw Permalink Blame History Unescape Escape

接口列表

接口一：卡券/直充权益下单接口

入参说明

响应消息

接口二：卡券/直充/微信立减金订单查询接口

入参说明

响应消息

接口三：微信立减金订单充值接口

入参说明

响应消息

接口四：卡券/直充/微信立减金充值结果通知接口（行方回调接口）

入参说明

响应消息（行方需返回）

认证/加密/签名细节

需要双方约定的参数

签名规则

加密规则

错误码

9.1 KiB

Raw Permalink Blame History