推送接口格式规范

此接口为外勤365平台在检测到到业务数据产生或变化时,通过发送HTTP请求,向第三方系统实时推送业务数据的接口说明。仅支持以POST方式提交请求,请求参数以表单Content-Type: application/x-www-form-urlencoded方式提交,超时时间为5秒

第三方系统接收到外勤365发起的HTTP请求时,将业务数据处理完成后响应{"return_code":0}表示数据处理成功,{"return_code":1}表述数据处理失败。对于处理失败的数据外勤365将在每天凌晨0点重新发起失败重试,如果此后连续10天仍然失败,系统将不再重试。对于同步失败的数据第三方系统还可以通过查询失败信息接口getfail获取。

请求数据体格式说明

msgId=7898952955531954883&dataType=custom&dataId=7087293505129744417&dataVersion=001&dataFormat=json&dataSource=biz&data=ENCODE(DATA)&timestamp=1569404987248&status=0&digest=4439af117f6d8d74ad0a3f59932e4f1e&tenantId=598865626837229452

推送接口说明

请求方式: POST(HTTPS
请求地址: 第三方服务接口URL
请求头: Content-Type: application/x-www-form-urlencoded
请求包体:

msgId=7898952955531954883&dataType=custom&dataId=7087293505129744417&dataVersion=001&dataFormat=json&dataSource=biz&data=%7B%22cm_code%22%3A%22CUS000020%22%2C%22id%22%3A%227087293505129744417%22%2C%22cm_name%22%3A%22%E8%8B%8F%E6%9E%9C%E8%B6%85%E5%B8%82%E5%A4%AB%E5%AD%90%E5%BA%99%E7%A4%BE%E5%8C%BA%E5%BA%97%22%7D&timestamp=1569404987248&status=0&digest=4439af117f6d8d74ad0a3f59932e4f1e&tenantId=598865626837229452

DATA数据体示例:

{"cm_code":"CUS000020","id":"7087293505129744417","cm_name":"苏果超市夫子庙社区店"}

参数说明:

参数名称 参数类型 是否必传 参数描述
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:车铺单
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": 1,
    "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