# 推送接口格式规范

# 什么时候需要回调服务

在集成勤策(原外勤365)与内部系统时,我们往往需要搭建一个回调服务。这样可以及时获取到状态变化。比如,客户信息发生变化时,不需要定时去拉取客户信息对比,而是实时地获取到变化的客户信息结点,进行同步,超时时间为5秒

# 回调地址URL

URL为回调服务地址,由第三方系统提供给勤策(原外勤365)客户经理,维护进勤策(原外勤365)系统,后续的业务请求都会向该URL推送消息。
第三方系统接收到勤策(原外勤365)发起的HTTP请求时,对于处理失败的数据,勤策(原外勤365)将在每天凌晨1点30分重新发起失败重试(自2021年12月24日起,失败重试时间由凌晨0点修改为凌晨1点30分),如果此后连续10天仍然失败,系统将不再重试。对于同步失败的数据第三方系统还可以通过查询失败信息接口getfail (opens new window)获取。 注意: 第三方系统开通回调服务的前提是已经开通了openApi接口访问能力。客户经理将回调服务开通后需要将企业推送授权签名密钥pushsecret提供给企业。

# 签名密钥pushsecret

pushsecret用于计算签名。第三方系统提供的URL是公开可访问的,这就意味着拿到这个URL,就可以往该链接推送消息。那么URL服务需要解决两个问题:
1)如何分辨出是否为勤策(原外勤365)来源
2)如何分辨出推送消息的内容是否被篡改
通过数字签名就可以解决上述的问题。具体为:约定pushsecret作为密钥,仅第三方系统和勤策(原外勤365)知道,在传输中不可见,用于参与签名计算。勤策(原外勤365)在推送消息时,将消息内容与约定pushsecret作为密钥计算出签名。第三方系统接收到推送消息时,也按相同算法计算出签名。如果为同一签名,则可信任来源为勤策(原外勤365),并且内容是完整的。
如果非勤策(原外勤365)来源,由于攻击者没有正确的pushsecret,无法算出正确的签名
如果消息内容被篡改,由于第三方系统会将接收的消息内容与pushsecret重算一次签名,该值与参数的签名不一致,则会拒绝该请求。

# 支持Http Post请求接收业务数据

假设企业的接收消息的URL设置为 https://api.third.com。
当用户触发回调行为时,勤策(原外勤365)会发送回调消息到填写的URL,推送内容如下:
请求方式: POST
请求地址: https://api.third.com
请求头: Content-Type: application/x-www-form-urlencoded

推送参数列表:
msgId=7898952955531954883
dataType=custom
dataId=7087293505129744417
dataVersion=001
dataFormat=json
dataSource=biz
data={"cm_code":"CUS000020","id":"7087293505129744417","cm_name":"苏果超市夫子庙社区店"}
timestamp=1569404987248
status=0
digest=4439af117f6d8d74ad0a3f59932e4f1e
tenantId=598865626837229452

参数说明:

参数名称 参数类型 是否必传 参数描述
msgId String 消息ID
dataType String 推送业务数据类型,对应各功能值如下:
employee:员工
department:部门
custom_district:销售区域
custom_type: 客户类型
custom: 客户信息
visit: 拜访记录
cuxiao_activity: 促销活动
cuxiao_record: 促销记录
cuxiao_record_check: 促销记录检查
stdorder_order: 标准订单
stdorder_sent: 标准发货单
stdom_return: 标准退货单
stdorder_carsale: 标准车销单
dms_purchase: 直营采购订单
dms_salesorder: 分销销售订单
dms_sent: 发货单
dms_sign: 签收单
dms_inventory: 盘点单
dms_cardistributeorder: 车铺单
rebate_card: 抵扣券
cuxiao_record_examine: 促销上报记录审核
dataId String 数据ID
dataVersion String 接口数据版本,如:001
dataFormat String 数据格式:json
dataSource String 数据来源。biz:业务功能产生,api:开放接口产生
data String 请求数据体, 说明:格式为JSON格式数据
timestamp long 请求时间戳,如:1503276678552
status String 数据同步状态。0:数据首次同步,2:数据失败同步
statusTime String 上次同步失败时间。格式:yyyy-MM-dd HH:mm:ss。失败重推时才有这个参数
tenantId String 企业ID,各注册企业在勤策(原外勤365)中对应的唯一ID。多企业共用一个接收地址时用来区分是哪个企业
digest String 数据签名,md5(data|pushsecret|timestamp)

响应示例:

{
    "return_code": 0,
    "return_msg": ""
}

参数说明:

参数 说明
return_code 响应编码。0:成功,1:失败
return_msg 对返回码的文本描述内容,后续可能会有变动,因此不可作为是否调用成功的判据

# 查询推送数据

第三方系统通过调用此接口根据数据ID查询最新的推送数据。

请求方式: POST(HTTPS
请求地址: https://openapi.waiqin365.com/swap/getbydataid/{dataType}/{pushid}/{ timestamp }/{ digest }/{ msg_id }
请求示例:

{
    "ids":"4980267531048822880,9004126148607423649"
}

参数说明:

参数 说明
ids 数据ID,多个数据用“,”分割

响应示例:

{
    "return_code": 0,
    "return_msg": "",
    "results": [
        {
            "id": "消息ID",
            "dataType": "<<数据类型>",
            "dataId": "<<数据ID>",
            "dataVersion": "<<数据版本>",
            "dataFormat": "json",
            "createTime": "2016-07-14 18:30:23",
            "data": "<<请求数据体>"
        }
    ]
}
                  

参数说明:

参数 说明
return_code 响应编码。0:成功,1:失败
return_msg 响应消息内容
results 查询结果记录数据列表,数据体和同步接口数据体格式一致

# 查询推送失败数据

接口说明:通过此接口可以查询最近100条推送失败的数据。如果请求参数为空,须传值空字符串 ""

请求方式: POST(HTTPS
请求地址: https://openapi.waiqin365.com/swap/getfail/{dataType}/{pushid }/{ timestamp }/{ digest }/{ msg_id }
请求示例:

{
    "callback_id": "9078101037649455212"
} 

参数说明:

参数 必填 说明
callback_id 通道id。一次只能传一个id,与openId一一对应。如有需要请向客户经理申请分配

参数说明:

dataType 参数说明
employee 员工
department 部门
custom_district 销售区域
custom_type 客户类型
custom 客户信息
visit 拜访记录
cuxiao_activity 促销活动
cuxiao_record 促销记录
cuxiao_record_check 促销记录检查
stdorder_order 标准订单
stdorder_sent 标准发货单
stdom_return 标准退货单
stdorder_carsale 标准车销单
dms_purchase 直营采购订单
dms_salesorder 分销销售订单
dms_sent 发货单
dms_sign 签收单
dms_inventory 盘点单
dms_cardistributeorder 车铺单

响应示例:

{
    "return_code": 0,
    "return_msg": "",
    "results": [
        {
            "id": "消息ID",
            "dataType": "<<数据类型>>",
            "dataId": "<<数据ID>>",
            "dataVersion": "<<数据版本>>",
            "dataFormat": "json",
            "createTime": "2016-07-14 18:30:23",
            "data": "<<请求数据体>>"
        }
    ]
}
                  

参数说明:

参数 说明
return_code 响应编码。0:成功,1:失败
return_msg 响应消息内容
results 查询结果记录数据列表,数据体和同步接口数据体格式一致,每次查询返回条数100条

# 确认推送失败数据

第三方系统在查询到处理失败数据后向勤策(原外勤365)平台发起确认请求,勤策(原外勤365)在收到确认信息后,认为本条信息已经同步成功,在下次请求查询推送失败数据时不再返回。

请求方式: POST(HTTPS
请求地址: https://openapi.waiqin365.com/swap/failconfirm/{dataType}/{pushid }/{ timestamp }/{ digest }/{ msg_id }
请求示例:

{
    "ids": "2000235510200010125,2000235510200010126,12000235510200010127",
    "callback_id": "5838472209989193398"
}

参数说明:

参数 必填 说明
ids 失败记录处理完成确认消息ID,多个值以","分隔
callback_id 通道id。一次只能传一个id,与openId一一对应。如有需要请向客户经理申请分配
dataType 参数说明
employee 员工
department 部门
custom_district 销售区域
custom_type 客户类型
custom 客户信息
visit 拜访记录
cuxiao_activity 促销活动
cuxiao_record 促销记录
cuxiao_record_check 促销记录检查
stdorder_order 标准订单
stdorder_sent 标准发货单
stdom_return 标准退货单
stdorder_carsale 标准车销单
dms_purchase 直营采购订单
dms_salesorder 分销销售订单
dms_sent 发货单
dms_sign 签收单
dms_inventory 盘点单
dms_cardistributeorder 车铺单
{
    "return_code": 0,
    "return_msg": "",
    "msg_id": "7898952955531954883"
}

参数说明:

参数 说明
return_code 响应编码。0:成功,1:失败
return_msg 响应消息内容
msg_id 消息ID