TIP

# 推送接口格式规范

# 什么时候需要回调服务

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

# 回调地址URL

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

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

接口代码参考示例 (opens new window)

假设企业的接收消息的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

参数说明：

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

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

← 业务接口格式规范行政区划接口 →