# 推送接口格式规范
# 什么时候需要回调服务
在集成勤策与内部系统时,我们往往需要搭建一个回调服务。这样可以及时获取到状态变化。比如,客户信息发生变化时,不需要定时去拉取客户信息对比,而是实时地获取到变化的客户信息结点,进行同步,超时时间为5秒。
# 回调地址URL
URL为回调服务地址,由第三方系统提供给勤策客户经理,维护进勤策系统,后续的业务请求都会向该URL推送消息。
第三方系统接收到勤策发起的HTTP请求时,对于处理失败的数据,勤策将在每天凌晨1点30分重新发起失败重试(自2021年12月24日起,失败重试时间由凌晨0点修改为凌晨1点30分),如果此后连续10天仍然失败,系统将不再重试。对于同步失败的数据第三方系统还可以通过查询失败信息接口getfail (opens new window)获取。
注意: 第三方系统开通回调服务的前提是已经开通了openApi接口访问能力。客户经理将回调服务开通后需要将企业推送授权签名密钥pushid、pushsecret和callbackid提供给企业。
# 支持Http Post请求接收业务数据
假设企业的接收消息的URL设置为 https://api.third.com。
当用户触发回调行为时,勤策会发送回调消息到填写的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,各注册企业在勤策中对应的唯一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条 |
# 确认推送失败数据
第三方系统在查询到处理失败数据后向勤策平台发起确认请求,勤策在收到确认信息后,认为本条信息已经同步成功,在下次请求查询推送失败数据时不再返回。
请求方式: 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 |