全部
电子面单
物流轨迹
物流发货
在线测试

快递信息推送服务

一,订阅接口


接口地址: http://api.vv-tool.com/tool/accounts/kd-subscribe-express-push


接口介绍: 订阅快递信息推送服务


请求方式: POST


返回格式: JSON


接口收费: 联系客服


频率限制: 10 次/秒


请求头参数

参数 类型 必选 示例
Authorization string 授权 access_token Bearer 1798c6aadec33d1bc2f5b707f1049aefexxxx

请使用新的生成 token 接口 点击查看详情

请求参数

参数 类型 必选 描述
company String 订阅的快递公司的编码,一律用小写字母
number String 订阅的快递单号,单号的最大长度是 32 个字符 下载编码表格
from String 出发地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,请尽量提供
to String 目的地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,且到达目的地后会加大监控频率,请尽量提供
key String 授权码,请申请企业版获取
parameters parameters 附加参数信息
--callbackurl String 回调接口的地址
--salt String 签名用随机字符串
--resultv2 String 添加此字段表示开通行政区域解析功能。0:关闭(默认),1:开通行政区域解析功能以及物流轨迹增加物流状态值,2:开通行政解析功能以及物流轨迹增加物流状态值并且返回出发、目的及当前城市信息 4:开通行政解析功能以及物流轨迹增加物流高级状态名称并且返回出发、目的及当前城市信息 6:开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息
--autoCom String 添加此字段且将此值设为 1,则表示开启智能判断单号所属公司的功能,开启后,需确保 company 字段为空,即只传运单号(number 字段),我方收到后会根据单号判断出其所属的快递公司(即 company 字段)。建议只有在无法知道单号对应的快递公司(即 company 的值)的情况下才开启此功能。
--interCom String 添加此字段表示开启国际版,开启后,若订阅的单号(即 number 字段)属于国际单号,会返回出发国与目的国两个国家的跟踪信息,本功能暂时只支持邮政体系(国际类的邮政小包、EMS)内的快递公司,若单号我方识别为非国际单,即使添加本字段,也不会返回 destResult 元素组
--departureCountry String 出发国家编码
--departureCom String 出发的快递公司的编码
--destinationCountry String 目的国家编码
--destinationCom String 目的的快递公司的编码
--phone String 收、寄件人的电话号码(手机和固定电话均可,只能填写一个,顺丰速运和丰网速运必填,其他快递公司选填。如座机号码有分机号,分机号无需上传。)

请求示例

{
"company": "ems",
    "number": "1136281381675",
    "from": "广东省深圳市南山区",
    "to": "北京市朝阳区",
    "key": "XXX ",
    "parameters": {
        "callbackurl": "您的回调接口的地址,如http://www.您的域名.com/kuaidi?callbackid=...",
        "salt": "XXXXXXXXXX",
        "resultv2": "1",
        "autoCom": "1",
        "interCom": "1",
        "departureCountry": "CN",
        "departureCom": "ems",
        "destinationCountry": "JP",
        "destinationCom": "japanposten",
        "phone": "13800138000"
    }
}

请求代码示例

cURL请求代码示例

PHP请求代码示例


JAVA请求代码示例


响应参数

名称 类型 描述
code int 返回状态码
msg string 返回码描述
msec int 接口执行时间
time int 接口返回时间
data object 数据信息
--result bool true:成功
false:失败
--withholding_money int 该接口扣费金额(点券)

返回数据

{
  "code": 0,
  "mag": "",
  "msec": "",
  "time": 1656564848,
  "data": {
    "result": true
}
}

二、推送接口


接口介绍: 推送快递信息推送服务

推送参数

参数 类型 示例值 描述
status String polling 监控状态:polling:监控中,shutdown:结束,abort:中止,updateall:重新推送。其中当快递单为已签收时 status=shutdown,当 message 为“3 天查询无记录”或“60 天无变化时”status= abort ,对于 status=abort 的状态,需要增加额外的处理逻辑
billstatus String got 包括 got、sending、check 三个状态,由于意义不大,已弃用,请忽略
message String 监控状态相关消息,如:3 天查询无记录,60 天无变化
lastResult lastResult 最新查询结果,若在订阅报文中通过 interCom 字段开通了国际版,则此 lastResult 表示出发国的查询结果,全量,倒序(即时间最新的在最前)
--message String 消息体,请忽略
--state String 0 快递单当前状态,包括 0 在途,1 揽收,2 疑难,3 签收,4 退签,5 派件,6 退回,7 转单,10 待清关,11 清关中,12 已清关,13 清关异常,14 收件人拒签等 13 个状态
--status String 200 通讯状态,请忽略
--condition String F00 快递单明细状态标记,暂未实现,请忽略
--ischeck String 0 是否签收标记
--com String yuantong 快递公司编码,一律用小写字母
--nu String V030344422 单号
--data Object 数组,包含多个对象,每个对象字段如展开所示
----context String 上海分拨中心/装件入车扫描 内容
----time String 2012-08-28 16:33:19 时间,原始格式
----ftime String 2012-08-28 16:33:19 格式化后时间
----status String 在途 本数据元对应的签收状态。在订阅接口中提交 resultv2 = 1 字段后才会出现
----areaCode String 310000000000 本数据元对应的行政区域的编码,在订阅接口中提交 resultv2 = 1 字段后才会出现
----areaName String 上海市 本数据元对应的行政区域的名称,在订阅接口中提交 resultv2 = 1 字段后才会出现
destResult destResult 表示最新的目的国家的查询结果,只有在订阅报文中通过 interCom=1 字段开通了国际版才会显示此数据元,全量,倒序(即时间最新的在最前)
--message String 消息体,请忽略
--state String 0 快递单当前状态,包括 0 在途,1 揽收,2 疑难,3 签收,4 退签,5 派件,6 退回等 8 个状态
--status String 200 通讯状态,请忽略
--condition String F00 快递单明细状态标记,暂未实现,请忽略
--ischeck String 0 是否签收标记
--com String yuantong 快递公司编码,一律用小写字母
--nu String V030344422 单号
--data data 数组,包含多个对象,每个对象字段如展开所示
--context String 上海分拨中心/装件入车扫描 内容
--time String 2012-08-28 16:33:19 时间,原始格式
--ftime String 2012-08-28 16:33:19 格式化后时间
--status String 在途 本数据元对应的签收状态,在订阅接口中提交 resultv2 = 1 字段后才会出现
--areaCode String 310000000000 本数据元对应的行政区域的编码,在订阅接口中提交 resultv2 = 1 字段后才会出现
--areaName String 上海市 本数据元对应的行政区域的名称,在订阅接口中提交 resultv2 = 1 字段后才会出现

响应代码

代码 代码描述 解决方案
0 成功
100 请求参数错误 检查您的请求参数是否正确
101 请求超时,请重试 检查您的网络情况或者联系客服解决
103 旺旺账号不存在 检查您输入的旺旺号是否正确
200 系统错误,请联系客服 检查您的接口地址填写是否正确,其他问题联系客服解决
203 暂不支持当前接口
204 请求异常:无该接口权限,请前往官网开通正式接口。 前往官网开通该接口权限
204 请求异常:API 调用次数不足,请前往网站兑换次数。 前往官网充值该接口调用次数
302 未授权店铺 根据返回链接进行扫码授权