抵扣券原理说明 | GHOME SDK 文档

# 抵扣券原理说明

抵扣券原理
1. 游戏发货通知响应coupon自动发放抵扣券或者运营在后台登记；
2. 游戏服务端查询待领取优惠券进行领取；
3. 游戏服务端发起消耗抵扣券成功后，由SDK服务器通知游戏服务器发货至游戏，需要游戏提供“订单通知接口”进行接收（参考GHOME SDK 服务端 API （国际） 2.2节）；
抵扣券时线图

# 待领取抵扣券查询接口

# 接口url

正式环境：https://service-sin.shengqugames-corp.com/coupon/queryUnclaimedCouponList

灰度联调环境：https://service-sin-gray.shengqugames-corp.com/coupon/queryUnclaimedCouponList

# 接口说明

查询待领取抵扣券列表

# 接口加密及格式

hps协议

# 请求参数

字段名	类型	必填	说明
uniqueId	string	Y	请求标识
appId	string	Y	游戏ID
areaId	string	N	区ID
groupId	string	N	服ID
appMid	string	Y	账号ID

# 响应参数

参数名	类型	说明
resultCode	int	错误码
resultMsg	string	错误描述
uniqueId	string	请求标识
couponList	string	待领取抵扣券列表例：[{"couponCode":"couponCode","couponName":"couponName","couponPrice":"couponPrice","balance":0}]

# 请求示例

https://service-sin-gray.shengqugames-corp.com/coupon/queryUnclaimedCouponList?appId=791000615&appMid=10484498&merchant_name=MEIYU_791000615&signature_method=MD5&timestamp=1686038799&uniqueId=123456&signature=7BF69C7CE7DF8B30DB2222D4EFB07BBA

# 响应示例

{ "return_code": 0, "error_type": 0, "return_message": "", "data": { "couponList":
"[{\"balance\":2,\"couponPrice\":\"0.99\",\"couponName\":\"99美分\",\"couponCode\":\"50\"},{\"balance\":3,\"couponPrice\":\"4.99\",\"couponName\":\"499美分\",\"couponCode\":\"53\"}]",
"resultCode": 0, "uniqueId": "123456" } }

1
2
3

# 签名原串

appId=791000615appMid=10484498merchant_name=MEIYU_791000615signature_method=MD5timestamp=1686038799uniqueId=123456 +secretKey

# 错误码列表

错误码	错误描述	说明
0	成功	成功
-10310901	uniqueId为空或格式不正确	请校验请求参数
-10310902	appId为空或格式不正确	请校验请求参数
-10310903	areaId格式不正确	请校验请求参数
-10310904	groupId格式不正确	请校验请求参数
-10310905	appMid为空或格式不正确	请校验请求参数
-10310951	查询数据库失败	请重试
-10310972	用户无待领取抵扣券	用户无待领取抵扣券

# 抵扣券查询接口

# 接口url

正式环境：https://service-sin.shengqugames-corp.com/coupon/queryCouponList

灰度联调环境：https://service-sin-gray.shengqugames-corp.com/coupon/queryCouponList

# 接口说明

查询抵扣券列表

# 接口加密及格式

hps协议

# 请求参数

字段名	类型	必填	说明
uniqueId	string	Y	请求标识
appId	string	Y	游戏ID
areaId	string	Y	区ID
groupId	string	N	服ID
appMid	string	Y	账号ID
roleId	string	Y	角色ID

# 响应参数

参数名	类型	说明
resultCode	int	错误码
resultMsg	string	错误描述
uniqueId	string	请求标识
couponList	string	抵扣券列表例：[{"couponCode":"couponCode","couponName":"couponName","couponPrice":"couponPrice","balance":0}]

# 请求示例

https://service-sin-gray.shengqugames-corp.com/coupon/queryCouponList?appId=791000615&appMid=10484498&areaId=6001&merchant_name=MEIYU_791000615&roleId=105577614114095105&signature_method=MD5&timestamp=1686038799&uniqueId=123456&signature=2675E820A965D2E1B28FCA9CB353E79F

# 响应示例

{ "return_code": 0, "error_type": 0, "return_message": "", "data": { "couponList":
"[{\"balance\":1,\"couponPrice\":\"1.99\",\"couponName\":\"199美分\",\"couponCode\":\"51\"}]", "resultCode": 0,
"uniqueId": "123456" } }

1
2
3

# 签名原串

appId=791000615appMid=10484498areaId=6001merchant_name=MEIYU_791000615roleId=105577614114095105signature_method=MD5timestamp=1686038799uniqueId=123456 +secretKey

# 错误码列表

错误码	错误描述	说明
0	成功	成功
-10310901	uniqueId为空或格式不正确	请校验请求参数
-10310902	appId为空或格式不正确	请校验请求参数
-10310903	areaId为空格式不正确	请校验请求参数
-10310904	groupId格式不正确	请校验请求参数
-10310905	appMid为空或格式不正确	请校验请求参数
-10310906	roleId为空或格式不正确	请校验请求参数
-10310951	查询数据库失败	请重试
-10310973	用户无已领取抵扣券	用户无已领取抵扣券

# 抵扣券领取接口

# 接口url

正式环境：https://service-sin.shengqugames-corp.com/coupon/couponClaim

灰度联调环境：https://service-sin-gray.shengqugames-corp.com/coupon/couponClaim

# 接口说明

领取抵扣券

# 接口加密及格式

hps协议

# 请求参数

字段名	类型	必填	说明
uniqueId	string	Y	请求标识
appId	string	Y	游戏ID
areaId	string	Y	区ID
groupId	string	N	服ID
appMid	string	Y	账号ID
roleId	string	Y	角色ID
couponList	string	Y	抵扣券列表例：[{"couponCode":"couponCode","balance":0}]

# 响应参数

参数名	类型	说明
resultCode	int	错误码
resultMsg	string	错误描述
uniqueId	string	请求标识

# 请求示例

https://service-sin-gray.shengqugames-corp.com/coupon/couponClaim?appId=791000615&appMid=10484498&areaId=6001&couponList=[{"couponCode":"52","balance":0}]&merchant_name=MEIYU_791000615&roleId=105577614114095105&signature_method=MD5&timestamp=1686038799&uniqueId=123456&signature=992A2C97FD5804123BB3D90637323786

# 响应示例

{ "return_code": 0, "error_type": 0, "return_message": "", "data": { "resultCode": 0, "uniqueId": "123456" } }

# 签名原串

appId=791000615appMid=10484498areaId=6001couponList=[{"couponCode":"52","balance":0}]merchant_name=MEIYU_791000615roleId=105577614114095105signature_method=MD5timestamp=1686038799uniqueId=123456 +secretKey

# 错误码列表

错误码	错误描述	说明
0	成功	成功
-10310901	uniqueId为空或格式不正确	请校验请求参数
-10310902	appId为空或格式不正确	请校验请求参数
-10310903	areaId格式不正确	请校验请求参数
-10310904	groupId格式不正确	请校验请求参数
-10310905	appMid为空或格式不正确	请校验请求参数
-10310906	roleId为空或格式不正确	请校验请求参数
-10310907	couponList为空或格式不正确	请校验请求参数
-10310951	查询数据库失败	请重试
-10310954	查无此游戏	请查看gpop后台配置
-10310959	未配置通知密钥	请查看gpop后台配置
-10310955	查无此区	请查看gpop后台配置
-10310957	未配置通知地址	请查看gpop后台配置
-10310965	无请求抵扣券配置	请查看gpop后台配置
-10310952	待领取抵扣券余额不足	请校验请求参数或重新查询余额
-10310971	请稍后再试	请稍后再试

# 抵扣券消耗接口

# 接口url

正式环境：https://service-sin.shengqugames-corp.com/coupon/couponConsume

灰度联调环境：https://service-sin-gray.shengqugames-corp.com/coupon/couponConsume

# 接口说明

消耗抵扣券

# 接口加密及格式

hps协议

# 请求参数

字段名	类型	必填	说明
uniqueId	string	Y	请求标识
gameOrderNo	string	Y	游戏订单号
appId	string	Y	游戏ID
areaId	string	Y	区ID
groupId	string	N	服ID
appMid	string	Y	账号ID
roleId	string	Y	角色ID
productId	string	Y	商品ID
couponCode	string	Y	抵扣券代码
extend	string	N	扩展字段，原样透传

# 响应参数

参数名	类型	说明
resultCode	int	错误码
resultMsg	string	错误描述
uniqueId	string	请求标识

# 请求示例

https://service-sin-gray.shengqugames-corp.com/coupon/couponConsume?appId=791000615&appMid=10484498&areaId=6001&couponCode=52&gameOrderNo=ghome_6001_105577614114095105_182827860930561&merchant_name=MEIYU_791000615&productId=com.gmknights.ghome_1003&roleId=105577614114095105&signature_method=MD5&timestamp=1686038799&uniqueId=7241466366027366401&signature=D02F4BAC2AE68996FE85D337A3613688

# 响应示例

{ "return_code": 0, "error_type": 0, "return_message": "", "data": { "resultCode": 0, "uniqueId": "7241466366027366401" } }

# 签名原串

appId=791000615appMid=10484498areaId=6001couponCode=52gameOrderNo=ghome_6001_105577614114095105_182827860930561merchant_name=MEIYU_791000615productId=com.gmknights.ghome_1003roleId=105577614114095105signature_method=MD5timestamp=1686038799uniqueId=7241466366027366401 +secretKey

# 错误码列表

错误码	错误描述	说明
0	成功	成功
-10310901	uniqueId为空或格式不正确	请校验请求参数
-10310902	appId为空或格式不正确	请校验请求参数
-10310903	areaId格式不正确	请校验请求参数
-10310904	groupId格式不正确	请校验请求参数
-10310905	appMid为空或格式不正确	请校验请求参数
-10310906	roleId为空或格式不正确	请校验请求参数
-10310908	productId为空或格式不正确	请校验请求参数
-10310909	couponCode为空或格式不正确	请校验请求参数
-10310910	gameOrderNo为空或格式不正确	请校验请求参数
-10310951	查询数据库失败	请重试
-10310954	查无此游戏	请查看gpop后台配置
-10310959	未配置通知密钥	请查看gpop后台配置
-10310955	查无此区	请查看gpop后台配置
-10310957	未配置通知地址	请查看gpop后台配置
-10310956	查无此商品	请查看gpop后台配置
-10310957	未配置通知地址	请查看gpop后台配置
-10310965	无请求抵扣券配置	请查看gpop后台配置
-10310958	抵扣券与商品金额不一致	请查看gpop后台配置
-10310953	抵扣券余额不足	请校验请求参数或重新查询余额
-10310971	请稍后再试	请稍后再试

# 公共错误码列表

参数名	错误描述	说明
-10242405	服务不存在，请稍后再试	请稍后再试
-10242400	服务错误，请稍后再试	请稍后再试
-10242504	访问超时，请稍后再试	请稍后再试
-10242500	服务内部错误，请稍后再试	请稍后再试
-10242404	网络错误，请确保网络通畅	请稍后再试
-10242488	服务忙，请稍后再试	请稍后再试
-10250013	URL不支持	请联系产品支持人员
-10250016	未授权访问此URL	请联系产品支持人员

# hps协议及签名方法

# hps协议接入标准

请求字段名	类型	必填	说明
merchant_name	string	Y	接入用户名从接入平台获取
signature_method	string	Y	签名方法目前固定MD5
signature	string	Y	签名使用签名密钥按照签名算法计算, 签名密钥从接入平台获取
timestamp	string	Y	Unix时间戳 1970年1月1日开始所经过的秒数
xxx			业务参数，见接口具体定义

响应字段名	类型	必填	说明
return_code	int	Y	0表示成功
return_message	string	Y	返回代码描述信息
data	string	N	JSON格式, 见接口具体定义

签名算法： 
按照当前请求参数名的字母序进行升序排列（排序时区分大小写，除 signature 外，其它参数都参与签名），将所有参数-值组合以 key=value 的形式拼成一个新字符串，不同参数值之间没有任何分隔符，最后加上对应的签名密钥 secretKey 进行签名运算。如进行签名运算的串为：key1=value1key2=value2secretKey

1
2

← for 手游国外 for 手游国外WEB收银台功能 →