快递查询 API 对接指南（Python示例）

在电商和物流行业快速发展的背景下，实时获取快递信息已成为系统开发中的常见需求。本文介绍如何通过快递查询API快速实现物流信息集成，以提升系统的自动化水平与用户体验。
一、接口概览

请求方式：GET

返回格式：JSON

响应示例：

js{
  "code": 1,
  "msg": "操作成功",
  "data": {
    "company": "中通快递",
    "com": "zto",
    "no": "78792812069699",
    "status_desc": "已签收",
    "list": [
      {
        "datetime": "2024-05-04 15:58:17",
        "remark": "【东莞市】已签收..."
      },
      ...
    ]
  }
}

二、Python 调用示例

1. 安装依赖
   

1. 核心调用函数

jsimport os
import sys
import requests

def query_express(com: str, no: str) -> dict:
    """
    查询快递物流信息。
    :param com: 快递公司编码，如 zto、ems
    :param no: 快递单号
    :return: JSON 响应数据
    """
    app_code = os.getenv("TANSHU_APPCODE")
    if not app_code:
        print("请设置环境变量 TANSHU_APPCODE", file=sys.stderr)
        sys.exit(1)

    url = "https://www.tanshuapi.com/market/detail-68"
    headers = {
        "Authorization": f"APPCODE {app_code}"
    }
    params = {
        "com": com,
        "no": no
    }

    try:
        resp = requests.get(url, headers=headers, params=params, timeout=5)
        resp.raise_for_status()
    except requests.RequestException as e:
        print(f"请求失败: {e}", file=sys.stderr)
        return {}

    return resp.json()

if __name__ == "__main__":
    result = query_express(com="zto", no="78792812069699")
    if not result:
        sys.exit(1)

    code = result.get("code")
    if code != 1:
        print(f"查询失败：{result.get('msg')}")
    else:
        data = result.get("data", {})
        print(f"快递公司：{data.get('company')}")
        print(f"当前状态：{data.get('status_desc')}")
        print("物流轨迹：")
        for item in data.get("list", []):
            print(f"{item['datetime']} - {item['remark']}")

三、常见问题处理

1. 未知快递公司时怎么办？
   使用「单号识别快递公司」接口：

   jsdef identify_company(no: str) -> dict:
    url = "https://www.tanshuapi.com/market/detail-68"
    headers = {
        "Authorization": f"APPCODE {os.getenv('TANSHU_APPCODE')}"
    }
    params = {"no": no}
   
    try:
        resp = requests.get(url, headers=headers, params=params, timeout=5)
        resp.raise_for_status()
        return resp.json()
    except requests.RequestException as e:
        print(f"识别失败：{e}", file=sys.stderr)
        return {}
   

2. 接口返回 403 错误？
   检查 TANSHU_APPCODE 是否正确配置
   确保账号已开通对应接口权限

四、总结
通过本文介绍的方法，你可以快速在 Python 中集成快递查询功能，满足电商、物流、客服等系统的实际需求。探数API 提供了稳定、高效、覆盖广泛的快递查询服务，开发者只需关注业务逻辑即可完成对接。