API开放平台

TIP

# 推送接口格式规范

# 什么时候需要回调服务

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

# 回调地址URL

URL为回调服务地址，由第三方系统提供给勤策客户经理，维护进勤策系统，后续的业务请求都会向该URL推送消息。
第三方系统接收到勤策发起的HTTP请求时，对于处理失败的数据，勤策将在每天凌晨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。
当用户触发回调行为时，勤策会发送回调消息到填写的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)

推送数据类型dataType参数说明：

dataType 参数说明
ai_sku AI识别结果AI识别推送数据
department 部门部门信息变更推送数据类型
employee 员工员工信息变更推送数据类型
custom_district 客户区域
custom_type 客户类型
property_cooperate 客户合作状态
custom_level 客户等级
property_kasys 客户KA系统
custom 客户
cm_linkman 客户联系人
cm_receive_info 客户收货方
cm_receive_address 客户收货地址
bas_cm_manager_change_event 客户经理
sm_outer_user 客户帐号
product 商品
visit 拜访
visit_plan 拜访计划
cuxiao_plan 促销方案促销方案推送数据
cuxiao_activity 促销活动
form_record 超级表单同步超级表单同步
cuxiao_check 促销检核结果
cuxiao_record 促销记录
cuxiao_record_check 促销记录检查
cuxiao_cm_remove 促销门店移除促销门店移除
cuxiao_activity_delete 促销删除活动申请单促销删除活动申请单
stdorder_order 商贸版订单
cuxiao_record_examine 促销审核内容
stdorder_sent 商贸版发货商贸版发货单
dms_purchase DMS直营订单DMS直营订单
dms_changeback DMS分销退货DMS分销退货
dms_salesorder DMS分销订单DMS分销订单
cuxiao_activity_regular_sale 万能促销活动申请单
std_mendian_used_voucher 优惠券已使用优惠券已使用
std_mendian_received_voucher 优惠券已领取优惠券已领取
dms_storehouse_kh_out_bas 客户其他出库单
dms_storehouse_in 其他入库单
cuxiao_close_apply 结案记录推送
dms_storehouse_out_bas 其他出库单
dms_sent DMS发货单
dms_sign DMS签收单
dms_inventory DMS盘点单
dms_cardistributeorder DMS车铺单
stdorder_carsale 商贸版车销单
rebate_card DMS抵扣券扣减流水抵扣券扣减流水推送接口
flow_record 流程表单数据推送
stdom_return MERP退货单MERP退货单
cuxiao_sign_b 乙方签署文件
std_asset_outer 外借资产
dms_sign_method 直营发货签收设置直营发货签收设置
receive 收款单
rebate_cus_account_amount_flow_reduce 费用池减少流水
rebate_cus_account_amount_flow_up 费用池增加流水
cuxiao_verify_display 付费陈列核销单
dms_storehouse_change DMS调拨单DMS调拨单
cuxiao_verify_delete_display 付费陈列核销单删除
cuxiao_verify_market 市场活动核销单
cuxiao_verify_delete_market 市场活动核销单删除
cuxiao_verify_entrance 进场费核销单
cuxiao_verify_delete_entrance 进场费核销单删除
cuxiao_verify_regular 万能促销核销单
cuxiao_verify_delete_regular 万能促销核销单删除
cuxiao_verify_fixamount 固定金额核销单
cuxiao_plan_regular_sale 万能促销TP方案万能促销TP方案
cuxiao_verify_delete_fixamount 固定金额核销单删除
salesLeads_follow 推送线索跟进记录
dms_receivable_history DMS收款单退款DMS收款单退款
cuxiao_verify_discount 进货折扣核销单
cuxiao_verify_delete_discount 进货折扣核销单删除
cuxiao_verify_direct 直接创建核销单
cuxiao_verify_delete_direct 直接创建核销单删除
cuxiao_verify_travel 差旅费核销单
cuxiao_verify_delete_travel 差旅费核销单删除
billing 开票申请数据推送
rebate_addPdPool 赠品池扣减流水
cuxiao_prepayment 预付款申请单
cuxiao_prepayment_delete 预付款申请单删除
father_son_clients 百饮父子客户信息推送

响应示例：

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

响应示例：

{
    "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
{
    "return_code": 0,
    "return_msg": "",
    "msg_id": "7898952955531954883"
}

参数说明：

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

← 行政区划接口 →