接口回调

介绍 卡游售卖机开放平台 接口回调的使用方法。

本章节介绍 卡游售卖机开放平台 接口回调的使用方法。

1.接口概述

卡游售卖机开放平台 开放了消息发送接口，对接的第三方业务系统可以使用这些接口进行双向通信。

2. 消息的类型

卡游售卖机开放平台 的消息可以分为以下几个类型：

  • 主数据消息
  • 业务消息
  • 运营平台事件消息

3. 消息格式定义

3.1 消息URL的通用参数

所有的消息回调时，URL上附以下两个通用QUERY参数，接收方可以用来进行数据的校验，以判断此消息数据是否可以信任。

参数名称类型描述
nonce字符随机字符串，16位
signature字符通过特定算法生成的signature，具体算法见签名算法

3.2 消息的调用方式

所有的消息调用，默认采用POST方式进行调用。

除非特殊接口或特定协议(如OAUTH重定向等)会在具体消息的消息中备注单独指明。

3.3 消息的BODY参数

所有对外的消息接口，所推送的消息格式统一如下所示

参数类型说明
eventTypestring事件类型, 表示各消息的类型
tenIdinteger租户ID (如果是运营平台类型回调事件则不包含tenId)
tenCodestring租户CODE, 相当于集团CODE(如果是运营平台类型回调事件则不包含tenCode)
timestampinteger时间戳，精确到秒
msgIdstring消息ID, 各消息唯一，客户端可根据此ID去重
contentobjectData 消息内容，各消息的内容具体见各消息说明

示例参考：

{
  "eventType": "emp_create",
  "tenId": 1001,
  "tenCode":"nike",
  "timestamp":1585714350,
  "msgId": "53102fb9bf1044ed8b0ba36d",
  "content": {
      // 具体的业务数据
  }
}

3.4 接收方处理消息后的返回

凡接收方接收请求后返回的HttpStatus=200，即代表成功；非200或10秒超时代表异常。

作为接收方应答的消息BODY，统一返回"success"字符串。

备注：现消息回调未提供失败重试机制，在后期迭代过程中会实现可配置的失败重试机制。

4. 数据的验签

4.1 验签的步骤分成以下几步：

  • 获取API-CB-SECRET
    • API-CB-SECRET的获取方式： apiCbSecret统一由 卡游售卖机开放平台 颁发，注意，此apiCbSecret与APIID接口调用的secret是不一致的。
    • 通过SECRET校验SIGNATURE
  • Signature生成规则：
    • 将消息的BODY转成JSON字符串
    • 从请求URL的QueryString中获取nonce字符串
    • 生成加密前字符串：请求体JSON字符串 + API-CB-SECRET + NONCE字符串
    • 将以上生成的字符串进行MD5哈希, 与URL的QueryString中的signature进行比较，如果一致，则签名正确。

4.2 示例

回调时消息URL

https://www.runsasoft.com?nonce=NDJK80QfPfBm21sJ&signature=17c48266bef1c0676944d8b10702c080

回调时消息BODY：

 {"eventType":"comp_create","tenId":1001,"tenCode":"dev","timestamp":1585714350,"msgId":"53102fb9bf1044ed8b0ba36d","content":{"id":"C0001","name":"青鸽有限公司","info":"青鸽","status":1,"platform":{"id":"S1001","name":"青鸽平台","type":1}}}

获取的API-CB-SECRET:

r4j0b91EZtpffjNs51xTbit@c9&SCFk1Thjtzy5kQNNfj0SAPXESdcnip%N9xizAi4EbTN9MRn0WxEBs1eZRbkf3Y8*s0w#bQ7Kcw1sBEs!FmGYRyAdWy!GAybX7fe2b

签名前生成的字符串为(消息BODY的JSON字符串 + API-CB-SECRET + NONCE):

{"eventType":"comp_create","tenId":1001,"tenCode":"dev","timestamp":1585714350,"msgId":"53102fb9bf1044ed8b0ba36d","content":{"id":"C0001","name":"青鸽有限公司","info":"青鸽","status":1,"platform":{"id":"S1001","name":"青鸽平台","type":1}}}r4j0b91EZtpffjNs51xTbit@c9&SCFk1Thjtzy5kQNNfj0SAPXESdcnip%N9xizAi4EbTN9MRn0WxEBs1eZRbkf3Y8*s0w#bQ7Kcw1sBEs!FmGYRyAdWy!GAybX7fe2bNDJK80QfPfBm21sJ

MD5哈希后字符串为:

17c48266bef1c0676944d8b10702c080

再与URL中signature进行比对，两者一致。