Steam礼物机器人对接协议

礼物机器人对接协议

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

联系我们

邮箱：Business@haidaoteam.com
QQ ：304926518
微信：steamkaifa

公共参数说明

礼物机器人对接使用标准的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": "" // 订单错误信息；订单失败时，会在此字段填写失败错误描述
  }
}

订单状态表

状态值	状态	备注
0	待处理	订单排队中，等待机器人处理
1	成功	订单发货成功；礼物已经发送成功，待用户接受礼物
2	失败	订单发货失败；失败原因参见订单message字段
11	待添加好友	订单处理中，机器人正在添加买家好友
12	待通过好友	订单好友请求已经发送给买家，等待买家同意好友请求
21	待发送礼物	订单好友已经通过，机器人正在添加Steam购物车发送礼物
22	待确认支付结果	订单Steam购物车已提交，正在确认订单支付结果

发货机器人回调

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失败的回调的重试