PHPackages                             chinphy/express-tracking - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. chinphy/express-tracking

ActiveLibrary

chinphy/express-tracking
========================

Unified express/courier tracking SDK for JD Logistics, SF Express, ZTO and China Post EMS with normalized output and optional raw trace retention.

v1.0.0(2d ago)00MITPHPPHP ^8.0

Since Aug 16Pushed 2d agoCompare

[ Source](https://github.com/chinphy/express-tracking)[ Packagist](https://packagist.org/packages/chinphy/express-tracking)[ RSS](/packages/chinphy-express-tracking/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (2)Used By (0)

express-tracking
================

[](#express-tracking)

统一快递轨迹查询 SDK（PHP 8.0+，Composer 包）。一个接口查询 **京东（JD/JOS 双通道）、顺丰（SF）、中通（ZTO）、中国邮政（EMS）、申通（STO）、菜鸟橙运（CNCY）、快递鸟（KDN）** 等开放平台/聚合平台的物流轨迹，输出**统一格式**结果，并支持**按需保留各家原始轨迹数据**（全局开关 + 单次传参覆盖）。

> 中国邮政/EMS 无公开自助 API，本包对接的是邮政**新一代寄递平台签约大客户接口**（`mailTrackGjcx`），需与邮政商务签约获取 `companyId`（客户标识）+ `queryKey`（轨迹查询密钥）。快递鸟（KDN）为聚合通道，可查快递鸟支持的多家快递。

特性
--

[](#特性)

- ✅ 标准 Composer 包：PSR-4 自动加载，`composer require` 即用
- ✅ 八条通道完整实现：京东 LOP 新版（`queryCommonTracking`）、京东 JOS 老平台（`Waybill2CTraceApi`）、顺丰（`EXP_RECE_SEARCH_ROUTES`）、中通（`zto.merchant.waybill.track.query`）、EMS（新一代寄递平台 `mailTrackGjcx`）、申通（`STO_TRACE_QUERY_COMMON`）、菜鸟橙运（`cn.ap.ld.query`）、快递鸟（KDN `RequestType=2002` 聚合）
- ✅ 统一输出：`TrackingResult`（统一状态、轨迹列表、查询时间），各家原始状态码透传
- ✅ 状态归一化：已揽收 / 运输中 / 派送中 / 已签收 / 异常 / 退回 / 未知
- ✅ 原始数据开关：构造时全局配置 + 单次查询传参覆盖
- ✅ 可区分异常：认证失败 / 运单不存在 / 网络失败 / 响应解析失败
- ✅ PSR-18 HTTP 客户端注入（Guzzle、Symfony HttpClient 等任意实现）
- ✅ 沙箱/测试环境切换（顺丰 sfapi-sbox、中通 japi-test、京东 uat-api.jdl.com、EMS 测试地址）
- ✅ Fixture 单元测试（无凭据可跑）+ 可选集成测试

安装
--

[](#安装)

```
composer require chinphy/express-tracking
composer require guzzlehttp/guzzle   # 任选一个 PSR-18 实现
```

快速开始
----

[](#快速开始)

```