快递100-快递信息查询订阅推送/跟踪API接口案例代码

举报
Kuaidi100API 发表于 2021/05/19 14:56:42 2021/05/19
【摘要】 一、订阅接口 1.1 订阅请求地址https://poll.kuaidi100.com/poll 1.2 订阅请求类型post 1.3 订阅输入参数请求参数（header）名称类型默认值Content-Typestringapplication/x-www-form-urlencoded请求参数（body）名称类型是否必需示例值描述schemaString是json返回的数据格式Θpara...

一、订阅接口

1.1 订阅请求地址

https://poll.kuaidi100.com/poll

1.2 订阅请求类型

post

1.3 订阅输入参数

请求参数（header）

名称 类型 默认值
Content-Type string application/x-www-form-urlencoded

请求参数（body）

名称 类型 是否必需 示例值 描述
schema String 是 json 返回的数据格式
Θparam param 是 由其他字段拼接
└ company String 是 ems 订阅的快递公司的编码，一律用小写字母
└ number String 是 1136281381675 订阅的快递单号，单号的最大长度是32个字符 下载编码表格
└ from String 否 广东省深圳市南山区 出发地城市，省-市-区，非必填，填了有助于提升签收状态的判断的准确率，请尽量提供
└ to String 否 北京市朝阳区 目的地城市，省-市-区，非必填，填了有助于提升签收状态的判断的准确率，且到达目的地后会加大监控频率，请尽量提供
└ key String 是 授权码，请申请企业版获取
Θparameters parameters 是 附加参数信息
└- callbackurl String 是 回调接口的地址
└- salt String 否 XXXXXXXXXX 签名用随机字符串
└- resultv2 String 否 1 添加此字段表示打开行政区域解析功能
└- autoCom String 否 1 添加此字段且将此值设为1，则表示开始智能判断单号所属公司的功能，开启后，company字段可为空,即只传运单号（number字段），我方收到后会根据单号判断出其所属的快递公司（即company字段）。建议只有在无法知道单号对应的快递公司（即company的值）的情况下才开启此功能
└- interCom String 否 1 添加此字段表示开启国际版，开启后，若订阅的单号（即number字段）属于国际单号，会返回出发国与目的国两个国家的跟踪信息，本功能暂时只支持邮政体系（国际类的邮政小包、EMS）内的快递公司，若单号我方识别为非国际单，即使添加本字段，也不会返回destResult元素组
└- departureCountry String 否 CN 出发国家编码
└- departureCom String 否 ems 出发的快递公司的编码
└- destinationCountry String 否 JP 目的国家编码
└- destinationCom String 否 japanposten 目的的快递公司的编码
└- phone String 否 13488888888 收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰单号必填，其他快递公司选填。如座机号码有分机号，分机号无需上传。）

1.4 订阅请求参数示例

    schema = json
    param = {
        "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"
        }
    }

1.5 订阅返回信息代码含义

result: true表示成功，false表示失败

信息代码 信息内容描述 原因及建议处理方式
200 提交成功 订阅提交成功
500 服务器错误 快递100的服务器出理间隙或临时性异常，有时如果因为不按规范提交请求，比如快递公司参数写错等，也会报此错误
501 重复订阅 此单已经订阅成功且目前还在跟踪过程中。若要提交多次订阅，请在收到单号的status=abort或shutdown后隔半小时再提交订阅
502 提交内容含有敏感关键字，被安全防护拦截 回调地址、提交内容包含敏感词，请联系快递100工作人员
600 您不是合法的订阅者（即授权Key出错） 账号无可用单量，需要充值
601 POLL: KEY 已过期 账号无可用单量，需要充值
700 不支持的快递公司 拒绝订阅的快递公司，检查快递公司编码是否有误
701 订阅方的订阅数据存在错误（如不支持的快递公司、单号为空、单号超长等）或错误的回调地址 请检查快递公司编码、对照技术文档检查参数、在后台调试工具测试回调地址
702 POLL:识别不到该单号对应的快递公司 快递公司编码错误或者无可用单量，需要充值

1.6 订阅返回示例（JSON格式）

{
    "result": true,
    "returnCode": "200",
    "message": "提交成功"
}

二、推送接口

2.1 推送请求地址

由贵司在订阅请求中通过callbackurl字段提供

2.2 推送请求类型

post

2.3 推送输入参数

请求参数（header）

名称 类型 默认值
Content-Type string application/x-www-form-urlencoded

请求参数（body）

名称 类型 示例值 描述
sign String 订阅参数salt值不为空时，推送数据将包含该加密签名，加密方式：md5(param+salt)
Θparam 由其他字段拼接
└ 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天无变化
└ autoCheck String 1 快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码，1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
└ comOld String yuantong 贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段
└ comNew String ems 我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段
Θ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字段后才会出现

2.4 推送输入参数示例

param = {
    "status": "polling",
    "billstatus": "got",
    "message": "",
    "autoCheck": "1",
    "comOld": "yuantong",
    "comNew": "ems",
    "lastResult": {
        "message": "ok",
        "state": "0",
        "status": "200",
        "condition": "F00",
        "ischeck": "0",
        "com": "yuantong",
        "nu": "V030344422",
        "data": [
        {
                "context": "上海分拨中心/装件入车扫描 ",
                "time": "2012-08-28 16:33:19",
                "ftime": "2012-08-28 16:33:19",
                "status": "在途",
                "areaCode": "310000000000",
                "areaName": "上海市"
            },
            {
                "context": "上海分拨中心/下车扫描 ",
                "time": "2012-08-27 23:22:42",
                "ftime": "2012-08-27 23:22:42",
                "status": "在途",
                "areaCode": "310000000000",
                "areaName": "上海市"
            }
        ]
    },
    "destResult": {
        "message": "ok",
        "state": "0",
        "status": "200",
        "condition": "F00",
        "ischeck": "0"     ,
        "com": "speedpost",
        "nu": "EX015142583SG",
        "data": [
        {
                "context": "[01000]Final delivery Delivered to: SLOVESNOV",
                "time": "2016-05-24 14:00:00",
                "ftime": "2016-05-24 14:00:00",
                "status": "签收",
                "areaCode": null,
                "areaName": null
            }
        ]
    }
}

2.5 运单签收状态服务说明

状态值 名称 含义
0 在途 快件处于运输过程中
1 揽收 快件已由快递公司揽收
2 疑难 快递100无法解析的状态，或者是需要人工介入的状态， 比方说收件人电话错误。
3 签收 正常签收
4 退签 货物退回发货人并签收
5 派件 货物正在进行派件
6 退回 货物正处于返回发货人的途中
7 转投 货物转给其他快递公司邮寄
10 待清关 货物等待清关
11 清关中 货物正在清关流程中
12 已清关 货物已完成清关流程
13 清关异常 货物在清关过程中出现异常
14 拒签 收件人明确拒收

2.6 推送响应报文及错误码解释

字段名称 字段含义
result true表示成功，false表示失败。如果提交回调接口的地址失败，30分钟后重新回调，3次仍旧失败的，自动放弃
returnCode 200: 提交成功 500: 服务器错误 其他错误请自行定义
message 返回的提示

2.7 推送返回示例

当我方调用贵方的回调接口（callbackurl）时，贵方需要先将我方提交的数据保存至贵方的数据库，接着向我方返回是否成功接收的响应报文及代码，即贵公司直接在回调接口的地址的response中填写如下内容：

{
    "result":true,
    "returnCode":"200",
    "message":"成功"
}

注意：对于status= abort（message中包含“3天查询无记录”或者“60天无变化”）的快递单，也需要返回成功接收的响应报文及代码。

三、快递公司编码

下载表格

四、demo下载

JAVA示例代码    PHP示例代码    PYTHON示例代码    .NET示例代码

一、快递信息推送API产品介绍

快递100信息推送服务提供运单查询、追踪的功能，用于企业对寄出的物品进行物流追踪。

信息推送服务是企业提交快递单号，快递100接收到后便对这些运单进行跟踪，当运单状态发生变化的时候，快递100便通过调用回调接口将运单的跟踪信息推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。对于某个单号，当贵方正确提交订阅了后，我们一般会在15分钟左右后进行第一次监控，如果监控到单号本身有了跟踪信息，即进行第一次推送，否则等待下一次监控。此后我们一般每4小时进行一次监控，并会根据单号的状态等因素作调整。

二、快递信息推送API应用场景

  1. 让顾客登录您的网站、APP、小程序后，直接在“我的订单”页面内就能看到订单的物流状态。

  2. 能开发自动的、批量查单功能，自动筛选出“已签收”、“疑难件”等状态的单号，减轻跟单人员的压力。

  3. 改变订单的状态与交易流程，例如只要运单号变为“已签收”，就能让订单变更为可以确认退换货等。

  4. 核销销售人员，根据“已签收”的运单数，就能算出销售人员的业绩。

  5. 评估与选择快递公司，可获得快递实际在途时间，评估快递公司的时效，优化快递选择；

  6. 助结算运费，找出“已签收”的单及签收时间，便能轻松应对货到付款的结算与对账。

三、系统结构与流程

img

四、快递信息推送API费用结算

1. 收费方式

快递信息推送接口属于查询类接口，企业注册快递100账号后可以在企业管理后台查看查询类接口套餐查看查询类接口套餐并购买。

2. 收费价格

查询类接口预充值收费套餐：充值即可开通使用，无需合同流程。

价格/元 单量 赠送/单 单价/元
2000 20000 5000 0.08
1000 10000 2000 约0.083
500 5000 500 约0.09

查询类接口按单收费，一个自然月内同一个运单多次查询只收一次费用。

3. 开具发票

快递100支持开具增值税发票，用户购买完成后可在企业管理后台-费用中心-支付记录-请求开票。默认开具电子增值税普通发票，1000元以上可支持开具增值税专用发票。

官方源文档：

https://api.kuaidi100.com/document/5f0ffa7f2977d50a94e1023b.html
https://api.kuaidi100.com/document/5eb9f79186b0df4188313a0d.html
https://api.kuaidi100.com/document/5f0ffa8f2977d50a94e1023c.html

【版权声明】本文为华为云社区用户原创内容，转载时必须标注文章的来源（华为云社区）、文章链接、文章作者等基本信息， 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容，欢迎发送邮件进行举报，并提供相关证据，一经查实，本社区将立刻删除涉嫌侵权内容，举报邮箱： cloudbbs@huaweicloud.com
API 智慧物流
  • 点赞
  • 收藏
  • 关注作者

评论（0）

0/1000
抱歉，系统识别当前为高风险访问，暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称，即可参与社区互动！

*长度不超过10个汉字或20个英文字符，设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符，设置后3个月内不可修改。

确认 取消

加入云驻计划，成为创作者

  • 华为云周边好礼
  • 免费体验产品
  • 特殊身份标识
  • 线下官方门票
  • 内部专家零距离
  • 与10000+优质创作者共同成长
立即加入