# 推送接口格式规范

# 什么时候需要回调服务

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

# 回调地址URL

URL为回调服务地址,由第三方系统提供给外勤365客户经理,维护进外勤365系统,后续的业务请求都会向该URL推送消息。
第三方系统接收到外勤365发起的HTTP请求时,对于处理失败的数据外勤365将在每天凌晨0点重新发起失败重试,如果此后连续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:抵扣券
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 }
请求包体: 空字符串 ""

参数说明:

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"
}

参数说明:

参数 说明
ids 失败记录处理完成确认消息ID,逗号分隔
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