礼物机器人对接协议

此协议解释权归属海盗海科技所有

联系我们

邮箱：Business@haidaoteam.com

QQ ：800181501

公共参数说明

礼物机器人对接使用标准的HTTP协议（正式环境使用HTTPS），请求和响应数据包都使用json格式；

返回的响应包基础格式为:

{

"code": 0, // 错误码，0表示成功，非0表示异常

"body": {}, // 具体返回数据

"message": "Succeed" // 错误描述

}

添加Steam钱包

POST http://gbot.5uskin.com/api/giftbot/wallet

接口参数包体:

{

"account": "axxxxx", // Steam帐号

"password": "xxxxxx", // Steam密码

"twoFactorCode": "", // 两步验证密钥；如果有绑定两步验证的话，未绑定则留空

}

接口响应:

{

"code": 0,

"body": {

"account": "axxxxx"

},

"message": "Succeed"

}

查询钱包列表

GET http://gbot.5uskin.com/api/giftbot/wallet

接口返回数据结构

{

"code": 0,

"body": {

"wallets": [

{

"account": "axxxxx", // Steam帐号

"steamid": "705xxxxxxxxxx", // Steam钱包帐号steamid

"balance": 500, // 钱包当前余额

"currency": "USD", // 钱包商店区货币单位

"online": true, // 钱包在线状态

"message": "" // 钱包最近一次错误信息

}

]

},

"message": "Succeed"

}

获取单个钱包详情

GET http://gbot.5uskin.com/api/giftbot/wallet/{axxxxx}

axxxxx: 要查询的钱包帐号

接口返回数据结构

{

"code": 0,

"body": {

"account": "axxxxx", // Steam帐号

"steamid": "705xxxxxxxxxx", // Steam钱包帐号steamid

"balance": 500, // 钱包当前余额

"currency": "USD", // 钱包商店区货币单位

"online": true, // 钱包在线状态

"message": "" // 钱包最近一次错误信息

},

"message": "Succeed"

}

移除指定钱包

DELETE http://gbot.5uskin.com/api/giftbot/wallet/{account}

account: 要移除的钱包帐号

接口返回数据结构

{

"code": 0,

"body": {

"account": "axxxxx" // Steam帐号

},

"message": "Succeed"

}

指定钱包发送礼物

POST http://gbot.5uskin.com/api/giftbot/gift

接口参数包体:

{

"uid": "xxxxxxx", // 该笔发货请求的唯一订单uid

"walletAccount": "axxxxx", // 指定发货用的钱包帐号

"buyerMessage": "https://steamcommunity.com/profiles/765611xxxxxxxxxx", // 接收礼物的目标Steam用户主页地址

"buyerSteamid": "765611xxxxxxxxxx", // 接收礼物的目标Steam用户Steamid； 目标主页地址或者目标Steamid至少填一个

"games": [ // 要赠送的游戏列表

{

"appid": 585950, // 游戏appid

"subid": 151396, // 游戏subid

"bundle": false // 游戏是否是捆绑包；如果是捆绑包，则subid的值传入该捆绑包bundle id

}

],

"steamPrice": 3 // 游戏包Steam定价；机器人付款前会根据该定价与实际需要付款的金额比较，如果实际付款额大于该值，则取消发货

}

接口响应包:

{

"code": 0,

"body": {

"uid": "xxxxxxxxxxx" // 订单uid

},

"message": "Succeed"

}

查询发货订单详情

GET http://gbot.5uskin.com/api/giftbot/gift/{uid}

uid: 发货订单uid

接口响应包:

{

"code": 0,

"body": {

"uid": "xxxxxx",

"walletAccount": "axxxxx", // 发货用的钱包帐号

"buyerMessage": "https://steamcommunity.com/profiles/765611xxxxxxxxxx", // 接收礼物的目标Steam用户主页地址

"buyerSteamid": "765611xxxxxxxxxx", // 接收礼物的目标Steam用户Steamid； 目标主页地址或者目标Steamid至少填一个

"games": [ // 要赠送的游戏列表

{

"appid": 585950, // 游戏appid

"subid": 151396, // 游戏subid

"bundle": false // 游戏是否是捆绑包；如果是捆绑包，则subid的值传入该捆绑包bundle id

}

],

"steamPrice": 3,

"transid": "123xxxxxxxxx", // Steam平台订单号

"payment": 3, // Steam平台实际支付金额

"state": 1, // 订单当前处理进度状态；详细状态表见下面详情

"message": "" // 订单错误信息；订单失败时，会在此字段填写失败错误描述

}

}

订单状态表

发货机器人回调

POST http://api.example.com/api/giftbot/callback

发货订单状态更新回调

发货状态更新回调包体:

{

"type": "order", // 回调类型，order，指代发货订单

"action": "state", // 消息类型，state，指代订单状态更新

"body": {

"uid": "xxxxxx",

"walletAccount": "axxxxx", // 发货用的钱包帐号

"buyerMessage": "https://steamcommunity.com/profiles/765611xxxxxxxxxx", // 接收礼物的目标Steam用户主页地址

"buyerSteamid": "765611xxxxxxxxxx", // 接收礼物的目标Steam用户Steamid； 目标主页地址或者目标Steamid至少填一个

"games": [ // 要赠送的游戏列表

{

"appid": 585950, // 游戏appid

"subid": 151396, // 游戏subid

"bundle": false // 游戏是否是捆绑包；如果是捆绑包，则subid的值传入该捆绑包bundle id

}

],

"steamPrice": 3,

"transid": "123xxxxxxxxx", // Steam平台订单号

"payment": 3, // Steam平台实际支付金额

"state": 1, // 订单当前处理进度状态；详细状态表见下面详情

"message": "" // 订单错误信息；订单失败时，会在此字段填写失败错误描述

}

}

回调响应格式

{

"code": 0, // code为0 表示接收回调正常，非0表示接受异常

"body": {},

"message": "ok"

}

每次报价单state变化时，机器人就会向以上地址发送一次回调；

调用方收到回调后，应该返回如上格式响应包，code为0 表示接收回调正常，非0表示接受异常；

如果回调响应异常，则机器人会再间隔1分钟、10分钟、1小时分别重发一次；

如果1小时后仍然返回异常，则机器人不再继续重发；

钱包余额更新回调

回调包体:

{

"type": "wallet", // 回调类型，wallet，指代钱包

"action": "balance", // 消息类型，balance，钱包余额更新

"body": {

"account": "axxxxx", // 钱包Steam帐号

"steamid": "705xxxxxxxxxx", // Steam钱包帐号steamid

"balance": 500, // 钱包当前余额

"currency": "USD", // 钱包商店区货币单位,

"updatedAt": "2019-03-04T00:00:00.000Z" // 更新时间

}

}

由于钱包余额信息需要保持实时性，当有新的余额变化时，之前失败的回调则不会再重发；

例如：10:01:10 时刻钱包wallet1余额更新成了500，机器人会进行一次回调，当该次回调失败了，机器人理论上在10:02:10会进行一次重发回调，回调通知余额更新为500了；

而在10:01:45时刻，钱包余额又变成了455，则机器人会直接回调一次455的通知，并取消之前500失败的回调的重试