核心用法
快递100物流信息服务提供双模式快递查询：已配置KUAIDI100_KEY/KUAIDI100_CUSTOMER时，调用官方实时查询API获取物流轨迹、状态、预计送达时间；未配置时，通过Playwright自动打开官网输入单号查询。寄快递场景引导用户使用快递100官网、APP或微信小程序下单，快递员上门取件。
查快递流程：确认快递公司编码（小写）→ 构造签名（param+key+customer的MD5大写）→ POST请求poll.kuaidi100.com/poll/query.do → 解析state状态码与data轨迹数组。支持顺丰/中通等必填手机号、目的地时效预测等高级功能。
备用方案：无API凭证时执行scripts/query_express_playwright.py，自动操控浏览器完成官网查询。
显著优点
- 官方数据源：直接对接快递100企业级API，覆盖国内主流快递公司，数据实时准确
- 灵活降级：API与浏览器自动化双模式，有无密钥均可使用
- 功能完整：支持轨迹排序、多语言、快递员信息、时效预测等企业级特性
- 安全设计：密钥通过环境变量注入，不写入代码或日志
潜在局限
- API成本：企业版需充值，key过期后失效（错误码601）
- 查询频率限制：同一单号至少间隔半小时，高频查询可能锁单
- 签名复杂度：需自行计算MD5/SHA256/SM3签名，易因格式问题导致503错误
- Playwright依赖：无API模式需安装playwright及chromium，首次配置较重
适合人群
电商运营、客服团队、物流管理、个人高频查件用户；需具备基础API对接能力或接受浏览器自动化方案。
常规风险
- 签名泄露：key与customer需严格保管，泄露可能导致接口被盗刷
- 频率封控：未遵守半小时间隔可能触发锁单
- 隐私合规：单号、手机号、地址仅用于单次查询，需确保不落日志