PHPackages                             xin6841414/express-bird - 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. [Utility & Helpers](/categories/utility)
4. /
5. xin6841414/express-bird

ActiveLibrary[Utility & Helpers](/categories/utility)

xin6841414/express-bird
=======================

快递鸟的laravel扩展包.

v1.3.0(1mo ago)05MITPHPPHP >=5.6

Since Jul 10Pushed 5d agoCompare

[ Source](https://github.com/xin6841414/express-bird)[ Packagist](https://packagist.org/packages/xin6841414/express-bird)[ RSS](/packages/xin6841414-express-bird/feed)WikiDiscussions main Synced 1w ago

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

快递鸟 for Laravel
===============

[](#快递鸟--for-laravel)

[快递鸟](http://www.kdniao.com/) 快递查询接口封装，逐步完善中...

安装
--

[](#安装)

```
$ composer require xin6841414/express_bird
```

配置
--

[](#配置)

1. 在 config/app.php 注册 ServiceProvider (Laravel 5.5 + 无需手动注册)：

    ```
    'providers' => [
        // ...
        Xin6841414\ExpressBird\ExpressBirdServiceProvider::class,
    ],
    ```
2. 创建配置文件：

    ```
    $ php artisan vendor:publish --provider="Xin6841414\ExpressBird\ExpressBirdServiceProvider"
    ```
3. 修改应用根目录下的 config/express\_bird.php 中对应的参数即可。

使用
--

[](#使用)

### 1. 在控制器中使用

[](#1-在控制器中使用)

```
namespace App\Http\Controllers;

use Xin6841414\ExpressBird\ExpressBird;  //注入时用
use Xin6841414\ExpressBird\Facades\ExpressBird;  //门面用

class TestController extends Controller
{

     public function index(ExpressBird $expressBird)
     {

         $result1 = $expressBird->realTimeQuery('777424831256386', 'STO');
         $result2 = app('express_bird')->realTimeQuery('777424831256386', 'STO');
         $result3 = ExpressBird::realTimeQuery('777424831256386', 'STO');
#         //$result:  {
#  "EBusinessID" : "1363938",
#  "ShipperCode" : "STO",
#  "LogisticCode" : "777424831256386",
#  "Location" : "青岛市",
#  "State" : "3",
#  "StateEx" : "302",
#  "Traces" : [ {
#    "Action" : "302",
#    "AcceptStation" : "已签收，签收人凭取货码签收。，可关注“申通快递”官方微信公众号获取实时物流信息",
#    "AcceptTime" : "2026-07-09 11:36:42",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "412",
#    "AcceptStation" : "快件已暂存至菜鸟驿站，如有疑问请联系1386xxx589，如有取件码问题或找不到包裹等问题，请联系：快递员【18661653919】，投诉电话【053285294663】，营业时间【08:00-20:30】，可关注“申通快递”官方微信公众号获取实时物流信息",
#    "AcceptTime" : "2026-07-08 16:23:04",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "202",
#    "AcceptStation" : " 【青岛市】山东青岛李沧区东部公司 的快递员(张三/13800138000)正在为您派送，【物流问题无需找商家或平台，请致电（053285294663）或专属渠道95543更快解决】，可关注“申通快递”官方微信公众号获取实时物流信息",
#    "AcceptTime" : "2026-07-08 16:03:31",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "202",
#    "AcceptStation" : " 【青岛市】山东青岛李沧区东部公司 的快递员(张三/13800138000)正在为您派送，【物流问题无需找商家或平台，请致电（053285294663）或专属渠道95543更快解决】，可关注“申通快递”官方微信公众号获取实时物流信息",
#    "AcceptTime" : "2026-07-08 14:23:23",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "2",
#    "AcceptStation" : "【青岛市】快件已到达 山东青岛李沧区东部公司 ，【物流问题无需找商家或平台，请致电（053285294663）或专属渠道95543更快解决】",
#    "AcceptTime" : "2026-07-08 14:22:32",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "2",
#    "AcceptStation" : "【青岛市】快件已发往 山东青岛李沧区东部公司，【物流问题无需找商家或平台，请致电专属渠道95543更快解决】",
#    "AcceptTime" : "2026-07-08 09:08:03",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "2",
#    "AcceptStation" : "【青岛市】快件已到达 山东青岛转运中心 ",
#    "AcceptTime" : "2026-07-08 08:51:14",
#    "Location" : "青岛市"
#  }, {
#    "Action" : "2",
#    "AcceptStation" : "【郑州市】快件已发往 山东青岛转运中心",
#    "AcceptTime" : "2026-07-07 20:54:27",
#    "Location" : "郑州市"
#  }, {
#    "Action" : "2",
#    "AcceptStation" : "【郑州市】快件已到达 河南郑州转运中心 ",
#    "AcceptTime" : "2026-07-07 20:51:55",
#    "Location" : "郑州市"
#  }, {
#    "Action" : "2",
#    "AcceptStation" : "【商丘市】快件已发往 河南郑州转运中心，若出现揽收后物流长时间未更新，请及时联系我们（【03702302699】或官方客服95543）核实，专属客服帮你跟进解决",
#    "AcceptTime" : "2026-07-07 15:33:56",
#    "Location" : "商丘市"
#  }, {
#    "Action" : "1",
#    "AcceptStation" : "【商丘市】河南夏邑县公司(03xxxx99)的出港扫描台(16xxxx798) 已揽收，若出现揽收后物流长时间未更新，请及时联系我们（【037xxxxx99】或官方客服95543）核实，专属客服帮你跟进解决",
#    "AcceptTime" : "2026-07-07 15:05:33",
#    "Location" : "商丘市"
#  } ],
#  "DeliveryManTel" : "13800138000",
#  "Success" : true
#}

     }

}

```

其他接口陆续完善中...
============

[](#其他接口陆续完善中)

### 2. 轨迹订阅

[](#2-轨迹订阅)

```
// 订阅物流轨迹，轨迹更新时快递鸟会主动推送至你配置的回调地址
$result = $expressBird->trackSubscribe('JDVA00003618100', 'JD');
// 顺丰/中通/跨越等需传入 CustomerName（手机号后四位）
$result = $expressBird->trackSubscribe('SF00003618100', 'SF', '1234');
// 带自定义回传字段和回调地址
$result = $expressBird->trackSubscribe('JT3150882936518', 'JTSD', '', 0, '', 'my_callback_data', 'https://your.domain.com/callback');
// 通过 extra 传入取件码等额外参数
$result = $expressBird->trackSubscribe('JT3150882936518', 'JTSD', '', 0, '', '', '', 0, [
    'IsNeedPickUpCode' => true,
    'Receiver' => ['Mobile' => '184****4905', 'VirtualMobile' => ''],
]);
# $result: {
#  "EBusinessID" : "1363938",
#  "UpdateTime" : "2026-07-14 15:30:00",
#  "Success" : true,
#  "ShipperCode" : "JD",
#  "LogisticCode" : "JDVA00003618100"
# }
```

### 3. 获取电子面单文件（顺丰）

[](#3-获取电子面单文件顺丰)

```
// 通过电子面单下单成功后，获取顺丰PDF面单文件进行打印
$result = $expressBird->getSFEOrderFile('202607141052483949', 'SF5114045401527');
// 指定模板类型
$result = $expressBird->getSFEOrderFile('202607141052483949', 'SF5114045401527', 'SF', 1);
// 获取子母件面单文件
$result = $expressBird->getSFEOrderFile('202607141052483949', 'SF5114045401527', 'SF', 1, [
    ['LogisticCode' => 'SF5114045401527', 'WaybillType' => 1],
    ['LogisticCode' => 'SF5114045401528', 'WaybillType' => 2],
]);
// 顺丰冷链需传入 LogisticsRouteCode
$result = $expressBird->getSFEOrderFile('202607141052483949', 'SF5114045401527', 'SF', 1, [], [
    'LogisticsRouteCode' => 'COLD',
]);
# $result: {
#  "Order" : {
#    "OrderCode" : "202607141052483949",
#    "ShipperCode" : "SF",
#    "LogisticCode" : "SF5114045401527",
#    "TemplateType" : "0",
#    "Remark" : "",
#    "TemplateCount" : 1,
#    "TemplateData" : [
#      {
#        "LogisticCode" : "SF5114045401527",
#        "TemplateUrl" : "https://oss.kdniao.com/...",
#        "WaybillType" : "1"
#      }
#    ]
#  },
#  "EBusinessID" : "1363938",
#  "ResultCode" : "100",
#  "Success" : true
# }
```

### 4. 电子面单追加子单（顺丰）

[](#4-电子面单追加子单顺丰)

```
// 通过电子面单下单成功后，追加获取更多子单（单次最多20单，总上限1200个）
$result = $expressBird->appendEorderForSF('202607141052483949', 5);
// 通过 extra 传入额外参数
$result = $expressBird->appendEorderForSF('202607141052483949', 3, 'SF', [
    'Remark' => '追加子单',
]);
# $result: {
#  "Order" : {
#    "LogisticCode" : "SF7444441172963",
#    "ShipperCode" : "SF",
#    "OrderCode" : "202607141052483949",
#    "KDNOrderCode" : "KDNE2607141050036887"
#  },
#  "SubOrders" : [ "SF7444511406882", "SF7444511406891", "SF7444511406907", "SF7444511406916", "SF7444511406925" ],
#  "SubCount" : 5,
#  "EBusinessID" : "1279441",
#  "ResultCode" : "100",
#  "Reason" : "成功",
#  "Success" : true
# }
```

### 5. 即时查询（地图版）

[](#5-即时查询地图版)

```
// 查询物流轨迹并返回地图信息，默认返回城市经纬度
$result = $expressBird->realTimeQueryWithMap('SF5114045401527', 'SF', '1234');
// 顺丰/中通/跨越等需传入 CustomerName（手机号后四位）
$result = $expressBird->realTimeQueryWithMap('SF5114045401527', 'SF', '1234', 0, '', 1, 1);
// 通过 extra 传入收寄件人地址以提升地图精度
$result = $expressBird->realTimeQueryWithMap('777424831256386', 'STO', '', 0, '', 1, 1, false, '', '', [
    'Receiver' => [
        'ProvinceName' => '山东省',
        'CityName' => '青岛市',
        'ExpAreaName' => '李沧区',
        'Address' => 'xx路xx号',
    ],
    'Sender' => [
        'ProvinceName' => '河南省',
        'CityName' => '商丘市',
        'ExpAreaName' => '夏邑县',
        'Address' => 'xx路xx号',
    ],
]);
// 需要取件码时传入收件人手机号和虚拟号
$result = $expressBird->realTimeQueryWithMap('JT3150882936518', 'JTSD', '', 0, '', 1, 2, true, '18400004905', '12345678');
# $result: {
#  "EBusinessID" : "1363938",
#  "ShipperCode" : "STO",
#  "LogisticCode" : "777424831256386",
#  "Success" : true,
#  "State" : "3",
#  "StateEx" : "302",
#  "Location" : "青岛市",
#  "Traces" : [
#    {
#      "AcceptTime" : "2026-07-09 11:36:42",
#      "AcceptStation" : "已签收",
#      "Location" : "青岛市",
#      "Action" : "302"
#    }
#  ],
#  "SenderCityLatAndLng" : "34.75,113.65",
#  "ReceiverCityLatAndLng" : "36.07,120.38",
#  "Coordinates" : [
#    { "LatAndLng" : "34.75,113.65" },
#    { "LatAndLng" : "36.07,120.38" }
#  ],
#  "EstimatedDeliveryTime" : "2026-07-15 18:00:00",
#  "RouteMapUrl" : "https://api.kdniao.com/api/Map?..."
# }
```

### 6. 轨迹订阅（地图版）

[](#6-轨迹订阅地图版)

```
// 订阅物流轨迹，轨迹更新时快递鸟会主动推送至你配置的回调地址，并在地图上展示包裹位置
// 与 trackSubscribe 区别在于支持返回城市经纬度和轨迹地图URL
$result = $expressBird->trackSubscribeWithMap('JT3150882936518', 'JTSD');
// 顺丰/中通/跨越等需传入 CustomerName（手机号后四位）
$result = $expressBird->trackSubscribeWithMap('SF00003618100', 'SF', '1234');
// 通过 extra 传入收寄件人地址以提升地图精度，并指定返回轨迹地图
$result = $expressBird->trackSubscribeWithMap('JT3150882936518', 'JTSD', '', 0, '', '', '', 0, 1, 1, false, '', '', [
    'Receiver' => [
        'ProvinceName' => '山东省',
        'CityName' => '菏泽市',
        'ExpAreaName' => '郓城县',
        'Address' => 'xx路xx号',
    ],
    'Sender' => [
        'ProvinceName' => '山西省',
        'CityName' => '晋中市',
        'ExpAreaName' => '晋中市',
        'Address' => 'xx路xx号',
    ],
]);
// 需要取件码时传入收件人手机号和虚拟号
$result = $expressBird->trackSubscribeWithMap('JT3150882936518', 'JTSD', '', 0, '', '', '', 0, 1, 2, true, '18400004905', '');
# $result: {
#  "EBusinessID" : "1363938",
#  "UpdateTime" : "2026-07-14 15:30:00",
#  "Success" : true,
#  "ShipperCode" : "JTSD",
#  "LogisticCode" : "JT3150882936518",
#  "EstimatedDeliveryTime" : "2026-07-15 18:00:00",
#  "SenderCityLatAndLng" : "34.75,113.65",
#  "ReceiverCityLatAndLng" : "36.07,120.38",
#  "RouteMapUrl" : "https://api.kdniao.com/api/Map?...",
#  "Location" : "菏泽市",
#  "PickUpInfo" : {
#    "Success" : true,
#    "Reason" : "成功"
#  }
# }
```

### 7. 接收轨迹推送（回调处理）

[](#7-接收轨迹推送回调处理)

```
// 在控制器中接收快递鸟推送（回调地址需在快递鸟后台配置，RequestType 固定为 102）
// 快递鸟 POST 的数据为 application/x-www-form-urlencoded，直接透传 request()->all() 即可
public function trackPush(\Illuminate\Http\Request $request)
{
    $result = $expressBird->receiveTrackPush($request->all());
    // 必须在 5 秒内返回响应，字段区分大小写
    return response()->json($result);
}
```

**内置接收路由（开箱即用）**本扩展已自带轨迹推送回调路由，安装后无需再自己写控制器/路由，直接在快递鸟后台填写回调地址即可。

- 路由路径由配置 `track_push.route.path` 控制（默认 `express-bird/track-push`），可通过修改 `config/express_bird.php` 或环境变量调整： ```
    KDNIAO_TRACK_ROUTE_ENABLED=true                     # 是否启用内置路由（设为 false 可在业务项目中自行定义路由）
    KDNIAO_TRACK_ROUTE_PATH=express-bird/track-push     # 回调地址路径（不含域名）
    ```
- **完整回调地址 = 应用域名 + 该路径**，例如 `https://your-domain.com/express-bird/track-push`，将其配置到快递鸟后台的「推送地址」。
- 该路由刻意不挂载 `web` 中间件组（无 CSRF、无 Session），以适配外部服务回调。
- 若设为 `KDNIAO_TRACK_ROUTE_ENABLED=false`，可改为在自己的业务项目里定义路由，再调用 `ExpressBird::receiveTrackPush($request->all())` 即可。

```
# 查看已注册的推送回调路由（确认路径生效）
php artisan route:list | grep track-push
```

receiveTrackPush 内部依次完成：

1. 签名校验（算法与请求签名一致：DataSign = UrlEncode(Base64(MD5(RequestData + ApiKey)))），校验失败返回 `Success=false`；
2. 触发 `TrackPushed` 事件，由监听器完成数据库写入等自定义逻辑；
3. 返回快递鸟要求的响应格式 `['EBusinessID', 'UpdateTime', 'Success', 'Reason']`。

`TrackPushed` 事件暴露的属性：

- `$pushTime` 推送时间，例：2026-07-14 15:30:00
- `$eBusinessId` 用户ID（快递鸟 EBusinessID）
- `$count` 本次推送的快递单号个数
- `$data` 轨迹集合数组，每个元素含 `LogisticCode`、`ShipperCode`、`State`、`StateEx`、`Traces`（轨迹节点数组，含 `AcceptTime`、`AcceptStation`、`Location`、`Action`）等

**开箱即用（事件与监听器已自动绑定）**安装本扩展后，`ExpressBirdServiceProvider` 会在 `boot()` 中根据配置自动把 `TrackPushed` 事件绑定到监听器，无需手动在 `EventServiceProvider` 注册。 内置默认监听器 `Xin6841414\ExpressBird\Listeners\SaveTrackPushed` 会按 `logistic_code + shipper_code` 将最新轨迹 `updateOrInsert` 到数据表（表名见配置 `track_push.table`），**单条写入失败仅记录日志、不影响对快递鸟的响应**。

> **建表迁移（推荐）**：本扩展内置迁移文件，发布后即可一键建表：
>
> ```
> # 将迁移文件发布到应用 database/migrations 目录
> php artisan vendor:publish --tag=express-bird-migrations
> # 执行迁移建表（表名取自配置 track_push.table，默认 express_tracks）
> php artisan migrate
> ```
>
>
>
> 迁移建表时会读取 `config('express_bird.track_push.table')`：若你已自定义表名，发布后执行 `php artisan migrate` 即按该表名建表；如需改表名，编辑发布后的迁移文件，或在配置中修改后重新发布即可。

**替换为自定义监听器（推荐）**复制 `vendor/xin6841414/express-bird/src/Listeners/SaveTrackPushed.php` 到 `app/Listeners/MyTrackPushed.php` 自定义业务逻辑，再修改配置文件 `config/express_bird.php`：

```
'track_push' => [
    'listener' => \App\Listeners\MyTrackPushed::class,   // 改为你的监听器
    'table'    => env('KDNIAO_TRACK_TABLE', 'express_tracks'),
],
```

> 修改配置前请先 `php artisan vendor:publish --provider="Xin6841414\ExpressBird\ExpressBirdServiceProvider"` 将配置发布到应用目录再编辑。 为满足快递鸟「5 秒内响应」要求，建议自定义监听器实现 `ShouldQueue` 标记为队列任务，或先快速落库原始推送再异步处理业务。

### 8. 京东电子面单下单（京东快递/快运2025，物流开放平台）

[](#8-京东电子面单下单京东快递快运2025物流开放平台)

```
// 京东快递（JD）下单，OrderCode 为业务侧订单编号（京东文档必传，需由调用方生成并保证唯一）
// CustomerName 为京东客户编码，CustomerMap 为京东授权参数
// Param1 客户编码(快递类) / 事业部编码(快运类)；Param2 事业部编码(快运类)；Param3 AppKey；Param4 AppSecret；Param5 AccessToken
$result = $expressBird->eOrderForJD(
    '202608141450123456',                          // OrderCode 订单编号（京东必传）
    '020K6***02',                                  // 京东客户编码（京东JD 必填）
    [
        'Param1' => '020K6***02',                  // 京东客户编码 customerCode（快递类）
        'Param2' => 'EBU4418*****0002',            // 京东事业部编码 businessUnitCode（快运类必传）
        'Param3' => 'B4EF1D69ED**********5E60A4A00FA9', // 京东 AppKey
        'Param4' => 'fec4a78e48***************0f44d3d', // 京东 AppSecret
        'Param5' => '93e387e***********************8nlmz', // 京东 AccessToken
    ],
    ['Name' => '收件人', 'Mobile' => '13000000627', 'ProvinceName' => '北京市', 'CityName' => '北京市', 'ExpAreaName' => '朝阳区', 'Address' => 'xx路xx号'],
    ['Name' => '寄件人', 'Mobile' => '1770006842', 'ProvinceName' => '广东省', 'CityName' => '深圳市', 'ExpAreaName' => '南山区', 'Address' => '宾xx号'],
    [['GoodsName' => '鞋子', 'GoodsQuantity' => 1]],
    1,   // PayType 1-现付 2-到付 3-月结
    1,   // ExpType 1-京东标快 2-京东特快 17-电商标快 等
    1,   // 包裹数量
    'JD' // ShipperCode，默认 JD（京东快递），JDKY（京东快运）
);

// 京东快运（JDKY）下单，需传入事业部编码（Param2）
$result = $expressBird->eOrderForJD(
    '202608141450123457',                          // OrderCode 订单编号（京东必传）
    '020K6***02',
    [
        'Param1' => '020K6***02',
        'Param2' => 'EBU4418*****0002',            // 快运类必传：事业部编码
        'Param3' => 'B4EF1D69ED**********5E60A4A00FA9',
        'Param4' => 'fec4a78e48***************0f44d3d',
        'Param5' => '93e387e***********************8nlmz',
    ],
    $receiver, $sender, $commodity, 3, 9, 2, 'JDKY'
);

// 生鲜标快（ExpType=4）需通过 extra.AddService 传温层 warmLayer；可在 extra 传入 LogisticsRouteCode 等
$result = $expressBird->eOrderForJD(
    '202608141450123458',                          // OrderCode 订单编号（京东必传）
    '020K6***02', $customerMap, $receiver, $sender, $commodity, 1, 4, 1, 'JD',
    [
        'LogisticsRouteCode' => 'OPEN',            // 下单平台：OPEN-京东开发平台（默认） COLD-冷链
        'AddService' => [
            ['Name' => 'mainProductAttrs', 'Value' => "{'warmLayer':'usual'}"], // 生鲜常温温层
        ],
    ]
);
# $result: {
#  "EBusinessID" : "1363938",
#  "Order" : {
#    "LogisticCode" : "JDVA00003618100",
#    "ShipperCode" : "JD",
#    "OrderCode" : "202608141450123456",
#    "KDNOrderCode" : "KDNE2608141450036887"
#  },
#  "ResultCode" : "100",
#  "Reason" : "成功",
#  "Success" : true
# }
```

> 说明：本接口基于标准电子面单（RequestType 1007，地址 `url_e_order`）。京东认证参数 `CustomerName`（客户编码）与 `CustomerMap`（Param1-Param5）为京东侧授权信息，请向京东销售/京东开放平台获取；使用同一 `OrderCode` 下单生成的运单号不变，如需修改信息重新下单需更换 `OrderCode`。下单成功后可用第 3 节 `getSFEOrderFile` 获取并打印面单。

### 9. 中通电子面单下单（中通快递 ZTO）

[](#9-中通电子面单下单中通快递-zto)

```
// 中通快递（ZTO）下单，CustomerName 为中通客户编码和密钥，CustomerPwd 为中通客户密码
// 账号需申请【普通电子面单】，电商渠道的电子面单账号不可用；中通快递不支持子母件，Quantity 填 1
$result = $expressBird->eOrderForZTO(
    '202608141450123456',                          // OrderCode 订单编号（中通必传，需唯一）
    'ZTO211600000007324',                          // 中通客户编码和密钥（CustomerName）
    'AY9NIYO2',                                    // 中通客户密码（CustomerPwd）
    ['Name' => '收件人', 'Mobile' => '15018442396', 'ProvinceName' => '安徽省', 'CityName' => '合肥市', 'ExpAreaName' => '包河区', 'Address' => '上海路18号华人健康'],
    ['Name' => '寄件人', 'Mobile' => '15018442396', 'ProvinceName' => '上海', 'CityName' => '上海市', 'ExpAreaName' => '浦东新区', 'Address' => '华夏东路微捷路1号丽居园'],
    [['GoodsName' => '文件'], ['GoodsName' => '电子产品']],
    3,   // PayType 1-现付 2-到付 3-月结
    1,   // ExpType 1-标准快递(旧平台) 21-中通好快 22-中通标快 23-标准快递，新用户建议用 21/22/23
    1,   // 包裹数量（中通不支持子母件，填 1）
    'ZTO'
);

// 中通标快（ExpType=22 尊享件）需传网点编码 SendSite（extra 传入）；非默认模板需传 TemplateSize
$result = $expressBird->eOrderForZTO(
    '202608141450123457', 'ZTO211600000007324', 'AY9NIYO2',
    $receiver, $sender, $commodity,
    3, 22, 1, 'ZTO',
    [
        'SendSite' => '021W001',                   // 网点编码（ExpType 21/22/23 必填）
        'IsReturnPrintTemplate' => '1',            // 是否返回面单模板
        'TemplateSize' => '1301',                  // 标快/尊享件模板尺寸限 1301
        'Remark' => '小心轻放',
    ]
);

// 代收货款（AddService COD）：金额通过 extra.AddService 传入，需在 config 允许
$result = $expressBird->eOrderForZTO(
    '202608141450123458', 'ZTO211600000007324', 'AY9NIYO2',
    $receiver, $sender, $commodity,
    2, 1, 1, 'ZTO',
    [
        'AddService' => [
            ['Name' => 'COD', 'Value' => '100.00'], // 代收货款 100 元
        ],
    ]
);
# $result: {
#  "Order" : {
#    "OrderCode" : "202608141450123456",
#    "ShipperCode" : "ZTO",
#    "LogisticCode" : "7533*******1234",
#    "KDNOrderCode" : "KDNE2608141450036887"
#  },
#  "PrintTemplate" : "...",
#  "ResultCode" : "100",
#  "Reason" : "成功",
#  "Success" : true
# }
```

> 说明：本接口基于标准电子面单（RequestType 1007，地址 `url_e_order`）。中通认证参数 `CustomerName`（客户编码和密钥）与 `CustomerPwd`（客户密码）需向合作网点申请普通电子面单账号；`ExpType` 为 21/22/23 时 `SendSite`（网点编码）必填，通过 `extra.SendSite` 传入；中通不支持子母件，`Quantity` 填 1。下单成功后可用第 3 节 `getSFEOrderFile` 获取并打印面单。

### 10. 菜鸟橙运电子面单下单（CNCY）

[](#10-菜鸟橙运电子面单下单cncy)

```
// 菜鸟橙运（CNCY）下单，CustomerName 为菜鸟橙运分配的货主编号（必传），TransType 为配送类型
// 账号需向合作网点申请；Quantity 1-300，大于 1 按子母件返回
$result = $expressBird->eOrderForCNCY(
    '202608141450123456',                          // OrderCode 订单编号（菜鸟橙运必传，需唯一）
    '2216100000000',                               // 菜鸟橙运分配的货主编号（CustomerName，必传）
    ['Name' => '张三', 'Mobile' => '15018442396', 'ProvinceName' => '安徽省', 'CityName' => '合肥市', 'ExpAreaName' => '包河区', 'Address' => '上海路18号华人健康'],
    ['Name' => '寄件人', 'Mobile' => '15018442396', 'ProvinceName' => '上海', 'CityName' => '上海市', 'ExpAreaName' => '浦东新区', 'Address' => '华夏东路微捷路1号丽居园'],
    [['GoodsName' => '文件'], ['GoodsName' => '电子产品']],
    3,   // PayType 1-现付 2-到付 3-月结
    1,   // ExpType 1-工作日 2-节假日 101-当日达 102-次晨达 103-次日达 104-预约达
    1,   // TransType 1-普通配送 2-冷链配送 3-环保配
    1,   // 包裹数量（1-300，大于1按子母件返回）
    'CNCY'
);

// 冷链配送（TransType=2）：通过 transType 参数指定
$result = $expressBird->eOrderForCNCY(
    '202608141450123457', '2216100000000',
    $receiver, $sender, $commodity,
    3, 103, 2, 1, 'CNCY'
);

// 代收货款（AddService COD）：金额通过 extra.AddService 传入，需在 config 允许
$result = $expressBird->eOrderForCNCY(
    '202608141450123458', '2216100000000',
    $receiver, $sender, $commodity,
    2, 1, 1, 1, 'CNCY',
    [
        'AddService' => [
            ['Name' => 'COD', 'Value' => '100.00'], // 代收货款 100 元
        ],
        'IsReturnPrintTemplate' => '1',            // 是否返回面单模板
        'Remark' => '小心轻放',
    ]
);
# $result: {
#  "Order" : {
#    "OrderCode" : "202608141450123456",
#    "ShipperCode" : "CNCY",
#    "LogisticCode" : "7533*******1234",
#    "KDNOrderCode" : "KDNE2608141450036887"
#  },
#  "PrintTemplate" : "...",
#  "EBusinessID" : "1363938",
#  "UniquerRequestNumber" : "c02f74c5-db15-4b17-ba86-7f329a6896a0",
#  "ResultCode" : "100",
#  "Reason" : "成功",
#  "Success" : true
# }
```

> 说明：本接口基于标准电子面单（RequestType 1007，地址 `url_e_order`）。菜鸟橙运认证参数 `CustomerName`（货主编号）需向合作网点申请；`TransType` 配送类型通过参数传入（1-普通配送，2-冷链配送，3-环保配，默认 1）；`ExpType` 为时效标（1-工作日，2-节假日，101-当日达，102-次晨达，103-次日达，104-预约达）；`Quantity` 1-300，大于 1 按子母件返回母运单号和子运单号。下单成功后可用第 3 节 `getSFEOrderFile` 获取并打印面单。

对接进度
----

[](#对接进度)

- 下单类接口
    - 预约取件 oOrder
    - 预约取件取消 cancelOrder
    - 电子面单
        - 顺丰 eOrderSF
        - 邮政（含电商标快） eOrderEMS
        - 京东快递/快运2025（物流开放平台） eOrderForJD
        - 中通冷链
        - 京东生鲜医药（物流开放平台）
        - 京东快递（JOS）
        - 中通快递 eOrderForZTO
        - 云集医药冷链
        - 丰云配
        - 菜鸟橙运 eOrderForCNCY
        - 菜鸟速递
        - 菜鸟速运
    - 电子面单取消 eOrderCancel
    - 获取电子面单文件【顺丰】 getSFEOrderFile
    - 获取电子面单追加子单【顺丰】 appendEorderForSF
- 轨迹类接口
    - 在途监控
        - 即时查询 realTimeQuery 注：40个自然日内同一（物流编码+单号）不限查询次数，计费1单； 查询无轨迹不计费
        - 轨迹订阅 trackSubscribe
    - 快递查询 expressQuery
    - 接收轨迹推送（回调处理） receiveTrackPush
    - 物流查询地图版
        - 即时查询（地图版） realTimeQueryWithMap
        - 轨迹订阅（地图版） trackSubscribeWithMap
        - 地图url编辑

鸣谢
--

[](#鸣谢)

[overtrue/easy-sms](https://github.com/overtrue/easy-sms)

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance96

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

43d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20766942?v=4)[xin6841414](/maintainers/xin6841414)[@xin6841414](https://github.com/xin6841414)

---

Top Contributors

[![xin6841414](https://avatars.githubusercontent.com/u/20766942?v=4)](https://github.com/xin6841414 "xin6841414 (5 commits)")

---

Tags

expresskdniaokuaidiniao

### Embed Badge

![Health badge](/badges/xin6841414-express-bird/health.svg)

```
[![Health](https://phpackages.com/badges/xin6841414-express-bird/health.svg)](https://phpackages.com/packages/xin6841414-express-bird)
```

###  Alternatives

[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k832.6k56](/packages/neuron-core-neuron-ai)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

762297.9k53](/packages/civicrm-civicrm-core)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.3M49](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

353.6k](/packages/eslazarev-wildberries-sdk)[oat-sa/tao-core

TAO core extension

64147.9k151](/packages/oat-sa-tao-core)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

265.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)