快递100 API接口如何快速集成使用？

快递100是中国领先的快递物流数据服务商，其API接口功能强大，覆盖了市面上绝大多数的快递公司，开发者可以通过这些API轻松地将快递查询、物流轨迹、电子面单打印等功能集成到自己的网站、App或小程序中。

快递100 API的核心功能

快递100的API主要提供以下几类服务：

1. 即时查询

   • 功能：根据快递单号,实时查询最新的物流轨迹信息。
   • 适用场景：电商平台订单详情页、App内订单跟踪、小程序查询等。
   • 特点：数据更新频率高,响应速度快。

2. 订阅查询

   • 功能：用户提交单号后，系统会持续监控该单号的物流状态，一旦有新的物流信息更新，就会通过你设定的回调地址（URL）主动推送给你。
   • 适用场景：需要实时物流状态通知的场景，如物流状态变更时给用户发短信/App推送、自动化仓库管理系统等。
   • 特点：主动推送，无需用户反复查询,节省服务器资源。

3. 电子面单

   • 功能：支持打印各大快递公司的电子面单（也称“快递面单”），用户只需要填写收寄件人信息，即可生成标准格式的面单,通过热敏打印机直接打印出来。
   • 适用场景：电商卖家、企业发件、需要批量打印面单的仓库。
   • 特点：标准化、自动化，提高发货效率,减少手写错误。

4. 数据接口

   
   （图片来源网络，侵删）
   • 功能：提供更底层的物流数据，如快递公司列表、支持查询的快递编码、物流轨迹节点数据结构等。
   • 适用场景：用于构建自己的物流管理系统,或对数据进行二次处理。

如何开始使用（申请流程）

1. 注册账号：

   • 访问快递100开放平台官网。
   • 使用手机号或微信扫码注册成为开发者。

2. 创建应用：

   • 登录后，进入“管理中心” -> “应用管理”。
   • 点击“创建应用”，填写应用名称、选择应用类型（如网站、App、小程序等），并设置一个回调域名（如果你需要使用订阅查询功能，这个域名必须是公网可访问的）。

3. 获取API Key：

   • 应用创建成功后，系统会自动生成一个customer（客户ID）和一个key（API密钥）。
   • key 是你调用所有API接口的凭证，请务必妥善保管，不要泄露。

4. 选择计费套餐：

   • 快递100的API服务通常是按量计费的。
   • 你需要根据自己预估的调用量，在“管理中心” -> “套餐管理”中选择合适的套餐，套餐包含每月免费的查询次数，超出后按需付费,新用户通常会有一定的免费试用额度。

主要API接口详解与示例

即时查询接口

这是最常用、最基础的接口。

• 接口地址：http://poll.kuaidi100.com/poll/query.do
• 请求方式：POST (推荐,因为数据量较大)
• 请求参数：
  • customer: 你的应用ID
  • sign: 签名（用于验证请求的合法性）
  • param: 请求参数的JSON字符串（需要进行Base64编码）

param 参数详解 (JSON格式)：

{
  "com": "快递公司编码",  //  "yuantong", "shentong"
  "num": "快递单号",      // 要查询的快递单号
  "from": "出发地",      // 可选，格式如 "广东省深圳市"，有助于提高准确率
  "to": "目的地",        // 可选，格式如 "北京市朝阳区"
  "resultv2": "1"       // 可选，建议为"1"，表示返回更详细的轨迹信息
}

签名生成方法： sign = MD5(customer + key + param的JSON字符串) 注意：这里的param是编码前的原始JSON字符串。

代码示例 (Python)：

import base64
import hashlib
import json
import requests
# 你的应用信息
CUSTOMER = '你的应用ID'
KEY = '你的API密钥'
def query_kuaidi100(com, num):
    # 1. 构造请求参数
    param_dict = {
        'com': com,
        'num': num,
        'from': '',
        'to': '',
        'resultv2': '1'
    }
    param_json_str = json.dumps(param_dict, separators=(',', ':'), ensure_ascii=False)
    param_base64 = base64.b64encode(param_json_str.encode('utf-8')).decode('utf-8')
    # 2. 生成签名
    sign_str = CUSTOMER + KEY + param_json_str
    sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
    # 3. 构造最终请求体
    payload = {
        'customer': CUSTOMER,
        'sign': sign,
        'param': param_base64
    }
    # 4. 发送POST请求
    url = 'http://poll.kuaidi100.com/poll/query.do'
    response = requests.post(url, data=payload)
    result = response.json()
    return result
# --- 调用示例 ---
# 查询一个圆通快递
result_data = query_kuaidi100('yuantong', 'YT1234567890')
if result_data['status'] == '200':
    print("查询成功！")
    # 打印物流轨迹
    for item in result_data['data']:
        print(f"{item['time']} - {item['context']}")
else:
    print(f"查询失败: {result_data['message']}")

订阅查询接口

这个接口分两步：第一步推送,第二步轮询。

• 第一步：推送

  • 接口地址：http://www.kuaidi100.com/poll
  • 请求方式：POST
  • 流程：你的服务器提供一个公网可访问的URL（在创建应用时设置），当用户在你的应用里提交一个单号请求订阅后，快递100会向这个URL推送一个初始的物流信息，你需要解析这个推送，并记录logistic_id。

• 第二步：轮询

  • 接口地址：http://poll.kuaidi100.com/poll/query.do (与即时查询接口相同)
  • 请求方式：POST
  • 区别：在param参数中，不传com和num，而是传logistic_id（即上一步推送中收到的ID）。

// 订阅查询的 param 示例
{
  "logistic_id": "推送过来的ID",
  "schema": "json"
}

计费模式

快递100的API主要采用按量付费的模式。

• 查询接口：每次成功调用（返回200状态）计为一次。
• 电子面单接口：每成功打印一张面单计为一次。
• 免费额度：新注册用户通常会获得一定的免费查询次数（例如每月500次）,用完后需要购买套餐。

具体价格和套餐详情请登录快递100开放平台查看“套餐管理”页面。

重要注意事项

1. 签名安全：key是核心凭证，泄露会导致你的API调用额度被盗用，甚至产生费用，请务必将其存储在服务器端安全的地方,不要暴露在前端代码中。
2. 回调地址：使用订阅查询时，回调域名必须是公网可访问的,并且不能是IP地址。
3. 错误处理：调用API时，务必检查返回结果中的status字段。200表示成功，其他代码（如400, 500, 800等）都代表不同类型的错误，需要根据message进行相应的处理。
4. 快递公司编码：调用接口前，需要知道快递公司的正确编码（如yuantong, shentong），可以在快递100开放平台的“数据接口” -> “快递公司列表”中获取完整的编码表。
5. 遵守协议：请仔细阅读并遵守快递100的开发者服务协议,特别是关于数据使用和不得用于非法爬虫等条款。

希望这份详细的介绍能帮助你快速上手快递100的API！