在电商业务中,物流查询体验直接影响用户满意度。本文将详细介绍如何快速集成快递100物流查询API,包括其新升级的智能时效预估能力,帮助开发者打造更专业的电商应用。

一、为什么选择快递100 API?

快递100 作为国内领先的物流数据服务商,其API接口是电商应用的理想选择,主要优势包括:

● 全面覆盖:支持国内外3000+快递公司,包括顺丰、中通、圆通、申通等主流快递商

● 高稳定性:日均查询量突破4亿,吞吐量近100万/秒,轻松应对电商大促高峰

● 功能丰富:提供实时查询、订阅推送、电子面单、智能时效预估等全链路服务

● 开发者友好:接口高度标准化,提供多语言SDK,最快15分钟内即可完成对接

二、准备工作:获取API密钥

1. 注册企业账号

访问快递100API开放平台官方网站注册企业账号。

2. 获取API密钥

在管理后台,查看自己的授权Key 和 Secret,这是调用API的核心凭证,请妥善保存。

3. 了解计费方式

查询类接口的计费规则很友好:40天内同一运单号多次查询不重复扣费,非常适合电商高频查询场景。

三、集成实时查询API

实时查询是电商应用中最常用的功能,让用户能主动查看包裹当前位置。

1. 接口基本信息

● 请求地址:https://poll.kuaidi100.com/poll/query.do

● 请求方式:HTTP POST/GET

● 返回格式:JSON

2. 核心参数说明

参数名是否必填说明
customer是授权码
sign是数字签名
param是JSON字符串,包含查询参数

3. 签名生成算法

签名是API调用的安全保障,生成方式如下:

 

// 签名计算公式
sign = MD5(param + key + customer)
// 加密后字符串转32位大写

4. 完整请求示例

 

// 构建请求参数
String key = "您的key";
String customer = "您的授权码";
String param = "{"com":"yuantong","num":"YT255699866665411","phone":"..."}";
String sign = MD5Util.md5(param + key + customer).toUpperCase();
 
// 构建请求
Map<String, String> params = new HashMap<>();
params.put("customer", customer);
params.put("sign", sign);
params.put("param", param);
 
// 发送请求
String result = HttpClientUtil.post("https://poll.kuaidi100.com/poll/query.do", params);

5. 响应结果处理

成功响应示例:

 

{
    "message": "ok",
    "nu": "YT25569986666541",
    "ischeck": "0",
    "com": "yuantong",
    "status": "200",
    "data": [
        {
            "time": "2025-06-13 15:56:19",
            "context": "您的快件离开【安徽省六安市叶集实验区】,已发往【安徽省六安市】",
            "ftime": "2025-06-13 15:56:19",
            "areaCode": "CN341522000000",
            "areaName": "安徽,六安市,霍邱县",
            "status": "在途",
            "location": "六安市,霍邱县",
            "areaCenter": "116.277912,32.353038",
            "areaPinYin": "huo qiu xian",
            "statusCode": "0"
        },
        {
            "time": "2025-06-13 15:53:52",
            "context": "您的快件在【安徽省六安市叶集实验区】已揽收",
            "ftime": "2025-06-13 15:53:52",
            "areaCode": "CN341522000000",
            "areaName": "安徽,六安市,霍邱县",
            "status": "揽收",
            "location": "六安市,霍邱县",
            "areaCenter": "116.277912,32.353038",
            "areaPinYin": "huo qiu xian",
            "statusCode": "1"
        }
    ],
    "state": "0",
    "condition": "00",
    "routeInfo": {
        "from": {
            "number": "CN430112000000",
            "name": "湖南,长沙市,望城区"
        },
        "cur": {
            "number": "CN341522000000",
            "name": "安徽,六安市,霍邱县"
        },
        "to": {
            "number": "CN320583104000",
            "name": "江苏,苏州市,昆山市,花桥镇"
        }
    },
    "isLoop": false,
    "arrivalTime": "2025-06-14 13",
    "totalTime": "0天21小时",
    "remainTime": "0天20小时",
    "predictedRoute": [
        {
            "arriveTime": "2025-06-13 15:53:52",
            "leaveTime": "2025-06-13 15:56:19",
            "province": "安徽",
            "city": "六安市",
            "district": "叶集区",
            "name": "安徽省六安市叶集实验区",
            "state": "已经过节点",
            "type": "网点"
        },
        {
            "arriveTime": "2025-06-13 19:05:19",
            "leaveTime": "2025-06-13 19:59:19",
            "province": "安徽",
            "city": "六安市",
            "district": "金安区",
            "name": "安徽省六安市",
            "state": "预估途径节点",
            "type": "网点"
        },
        {
            "arriveTime": "2025-06-13 23:09:19",
            "leaveTime": "2025-06-13 23:16:19",
            "province": "安徽",
            "city": "合肥市",
            "district": "肥东县",
            "name": "合肥转运中心",
            "state": "预估途径节点",
            "type": "转运中心"
        },
        {
            "arriveTime": "2025-06-14 06:58:19",
            "leaveTime": "2025-06-14 07:17:19",
            "province": "江苏",
            "city": "无锡市",
            "district": "新吴区",
            "name": "苏州转运中心",
            "state": "预估途径节点",
            "type": "转运中心"
        },
        {
            "arriveTime": "2025-06-14 12:29:19",
            "leaveTime": "2025-06-14 13:46:19",
            "province": "江苏",
            "city": "苏州市",
            "district": "昆山市",
            "name": "江苏省昆山市城区",
            "state": "预估途径节点",
            "type": "网点"
        }
    ]
}

重要提示:请控制每一单查询频率至少在半小时以上,否则会造成锁单。

四、重磅功能:智能时效预估免费升级

现在使用快递100物流查询接口,可免费升级为额外返回智能时效预估的能力,这是目前行业最前沿的物流预测功能。

1. 什么是智能时效预估?

智能时效预估是快递100基于AI+Data构建的中国首个快递物流网络数智图谱推出的核心能力。用户在调用物流查询API时,除了获取物流轨迹,还可获得:

● 预计送达时间

● 预测准确率

● 途经网点与转运中心路线预测

2. 核心价值:从"查轨迹"到"预见未来"

● 透视数据可信度:probability 字段直接告知该次预估的准确率概率高达90%

● 体验更透明:终端用户获得的不止有物流轨迹信息,还能获得快递预计到达时间

● 接入零门槛:无需额外调整调用逻辑,完美兼容历史接入方案

3. 两种预估模式覆盖全场景

● 全程时效预估(发货前):在商品详情页直接展示预计送达时间,催化消费者决策

● 在途时效预估(发货后):当包裹已发出,系统会实时更新预计送达时间,离收货地越近,预测越准

4. 如何启用智能时效预估?

调用快递100物流查询接口时,在请求参数的 resultv2 字段选择8,即可额外获得智能时效预估数据。

五、小程序集成实战

1. 小程序端实现

在小程序页面中展示物流信息和时效预估:

 

<!-- logistics.wxml -->
<view class="logistics-container">
  <view class="logistics-header">
    <text class="company">快递公司:{{companyName}}</text>
    <text class="number">运单号:{{expressNumber}}</text>
  </view>
  
  <!-- 时效预估信息 -->
  <view class="time-estimate" wx:if="{{estimatedTime}}">
    <text class="estimate-text">预计送达:{{estimatedTime}}</text>
    <text class="probability" wx:if="{{probability}}">准确率:{{probability}}%</text>
  </view>
  
  <view class="progress-bar">
    <view class="progress-item {{item.status}}" wx:for="{{logisticsList}}" wx:key="time">
      <view class="dot"></view>
      <view class="content">
        <text class="context">{{item.context}}</text>
        <text class="time">{{item.ftime}}</text>
      </view>
    </view>
  </view>
</view>

2. 服务端API封装

建议在小程序服务端封装快递100接口,避免前端直接暴露API密钥:

 

// Node.js后端接口示例
const express = require('express');
const router = express.Router();
const md5 = require('md5');
 
router.post('/logistics/query', async (req, res) => {
  try {
    const { com, num } = req.body;
    
    const key = process.env.KUAIDI100_KEY;
    const customer = process.env.KUAIDI100_CUSTOMER;
    const param = JSON.stringify({ 
      com, 
      num,
      resultv2: 8 // 启用智能时效预估
    });
    
    // 生成签名
    const sign = md5(param + key + customer).toUpperCase();
    
    // 调用快递100接口
    const response = await fetch('https://poll.kuaidi100.com/poll/query.do', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        customer,
        sign,
        param
      })
    });
    
    const result = await response.json();
    
    // 返回包含智能时效预估的结果
    res.json({
      logisticsList: result.data,
      estimatedTime: result.estimatedTime, // 预计送达时间
      probability: result.probability // 预测准确率
    });
  } catch (error) {
    res.status(500).json({ error: '查询失败' });
  }
});

六、物流跟踪:订阅推送API

对于需要持续追踪快递的场景,订阅推送比实时查询更高效。

1. 工作流程

● 开发者调用订阅接口,设置回调地址

● 当物流状态更新时,快递100会主动向该地址推送最新信息

● 一般会在15分钟左右进行第一次监控

2. 优势

● 及时性:状态变化立即推送,无需等待用户查询

● 节省资源:减少不必要的API调用

● 自动化:可基于推送消息自动更新订单状态

 

七、常见问题与解决方案

1. 签名验证失败

问题:返回503错误,签名认证失败

解决:检查签名生成算法,确保按 param + key + customer 顺序MD5加密,并转为32位大写

2. 单号不存在

问题:返回500错误,查询无结果

解决:

● 确认单号和快递公司正确

● 刚下单的包裹可能还未录入系统,建议延迟查询

● 检查单号是否存在空格等特殊字符

3. 智能时效预估数据不显示

问题:未返回预估时间和准确率

解决:

● 检查请求参数是否设置 resultv2: 8

九、总结

通过快递100 API,开发者可以快速为电商小程序和App集成专业级物流查询功能,特别是新升级的智能时效预估能力,让您的应用从"查询轨迹"升级到"预见未来"。

 

现在就开始集成,为您的电商应用赋予更智能的物流查询能力吧!

希望本文对您有所帮助,欢迎在评论区交流讨论!


快递100API
4 声望2 粉丝

快递100旗下B端品牌【百递云·API开放平台】,合作超过3000+全球快递公司,提供快递单号物流轨迹查询接口服务、电子面单与云打印服务、智能时效预估、地址解析、物流拦截等快递物流全链路数智化集成解决方案。