Search by

xin6841414 / express-bird

xin6841414

快递鸟的laravel扩展包.

Package info

github.com/xin6841414/express-bird

pkg:composer/xin6841414/express-bird

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 6

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.4.2 2026-08-21 06:43 UTC

Requires

Requires (Dev)

None

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT 129e2cc770a11d4e5031a09e65bfad0d3abc27e8

  • xin6841414 <xin6841414.woop@126.com>

expresskdniaokuaidiniao

Published on Packagist.org on 2026-08-21 06:44 UTC

This package is auto-updated.

Last update: 2026-08-21 06:44:08 UTC

README

快递鸟 快递查询接口封装，逐步完善中...

安装

$ 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. 在控制器中使用

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. 轨迹订阅

// 订阅物流轨迹，轨迹更新时快递鸟会主动推送至你配置的回调地址
$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. 获取电子面单文件（顺丰）

// 通过电子面单下单成功后，获取顺丰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. 电子面单追加子单（顺丰）

// 通过电子面单下单成功后，追加获取更多子单（单次最多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. 即时查询（地图版）

// 查询物流轨迹并返回地图信息，默认返回城市经纬度
$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. 轨迹订阅（地图版）

// 订阅物流轨迹，轨迹更新时快递鸟会主动推送至你配置的回调地址，并在地图上展示包裹位置
// 与 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. 接收轨迹推送（回调处理）

// 在控制器中接收快递鸟推送（回调地址需在快递鸟后台配置，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，物流开放平台）

// 京东快递（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）

// 中通快递（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" : "<html>...</html>",
#  "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）

// 菜鸟橙运（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" : "<html>...</html>",
#  "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