Download the PHP package kode/express-api without Composer

kode/express-api

通用快递API集成包，支持多种快递公司接口，提供统一的调用方式，便于快速集成到各种PHP项目中。

功能特性

• 支持多种快递公司API，覆盖「国内快递 + 国内货运（零担/整车/快运）+ 国际物流（跨境 / 货运）」完整物流链：
  • 国内快递：EMS、顺丰SF、韵达、中通、申通、菜鸟网络、京东快递/京东物流
  • 国内货运：德邦物流、安能物流、天地华宇（零担 / 整车 / 快运，支持网点查询、运费报价）
  • 国际物流：4PX递四方、顺丰国际、DHL国际、云途物流、EMS国际、燕文物流 （支持海运 / 空运下单、海关申报、清关查询、运费报价）
  • 聚合查询：快递100、快递鸟、聚合数据、17TRACK（运单轨迹 + 运单号自动识别，作为承运商自动识别的权威回退）
• 当前版本：v2.9.0
• 物流链自动关联（v2.3.0+）：仅凭运单号即可 recognize() 自动识别承运商；给定发货意图（起止国 / 重量 / 运输方式）即可 buildChain() 自动拼装「揽收 → 干线 → 跨境 → 清关 → 末端」全链路，无需逐段指定承运商。规则未命中时，可经 AggregateResolver 聚合 17TRACK 等权威源做确定性回退识别
• 统一的接口调用方式，简化开发流程
• 灵活的面单布局管理，支持可视化编辑
• 完善的错误处理和响应标准化（按快递商注册响应策略）
• 传输层韧性增强：指数退避重试（瞬时故障自动重试，4xx 不重试）、连接超时、最近请求诊断
• 跨快递商聚合能力：batchQueryTracking() 批量轨迹（单条失败隔离）
• 支持PSR-12代码规范
• 支持PHP 8.3+
• 支持多语言字段配置
• 丰富的测试用例，测试覆盖率高

安装

使用Composer安装：

配置说明

获取API密钥

要使用各快递公司API，您需要在相应开放平台注册并获取API密钥：

1. EMS：

   • 访问EMS开放平台
   • 注册开发者账号并完成企业认证
   • 在API控制台选择需要的服务接口
   • 获取API密钥（AppKey和AppSecret）

2. 顺丰SF：

   • 访问顺丰开放平台
   • 注册开发者账号并申请API权限
   • 获取API密钥

3. 韵达：

   • 访问韵达开放平台
   • 注册开发者账号并完成认证
   • 获取API密钥

4. 中通：

   • 访问中通开放平台
   • 注册开发者账号并完成认证
   • 获取API密钥

5. 申通：

   • 访问申通开放平台
   • 注册开发者账号并完成认证
   • 获取API密钥
6. 菜鸟网络：
   • 访问菜鸟开放平台
   • 注册开发者账号并完成认证
   • 获取AppKey、AppSecret和PartnerId

环境配置

生产环境

在生产环境中使用真实的EMS API端点：

沙箱环境

在开发和测试阶段，建议使用沙箱环境：

配置参数详解

app_key

• 类型: string
• 必填: 是
• 说明: 应用Key，从各快递公司开放平台获取

app_secret

• 类型: string
• 必填: 是
• 说明: 应用密钥，从各快递公司开放平台获取

partner_id

• 类型: string
• 必填: 否（仅菜鸟网络必需）
• 说明: 合作伙伴ID，从菜鸟开放平台获取

sandbox

• 类型: boolean
• 默认值: false
• 说明: 是否使用沙箱环境
  • true: 使用沙箱环境，用于开发测试
  • false: 使用生产环境，用于正式业务

timeout

• 类型: integer
• 默认值: 30
• 说明: HTTP请求超时时间（秒）

version

• 类型: string
• 默认值: 'v1'
• 说明: API版本号

认证机制

EMS API使用OAuth 2.0客户端凭证模式进行认证：

1. 使用app_key和app_secret获取访问令牌
2. 在后续API请求中使用该令牌进行认证

网络要求

生产环境端点

• EMS: https://api.ems.com.cn (端口: 443)
• 顺丰SF: https://sfapi.sf-express.com (端口: 443)
• 韵达: https://api-yunda.kdniao.com (端口: 443)
• 中通: https://api-zto.kdniao.com (端口: 443)
• 申通: https://api-sto.kdniao.com (端口: 443)
• 菜鸟网络: https://api-cainiao.openapi.alibaba.com (端口: 443)

沙箱环境端点

• EMS: https://api-sandbox.ems.com.cn (端口: 443)
• 顺丰SF: https://sfapi-sandbox.sf-express.com (端口: 443)
• 韵达: https://api-sandbox-yunda.kdniao.com (端口: 443)
• 中通: https://api-sandbox-zto.kdniao.com (端口: 443)
• 申通: https://api-sandbox-sto.kdniao.com (端口: 443)
• 菜鸟网络: https://api-sandbox-cainiao.openapi.alibaba.com (端口: 443)

确保您的服务器能够访问这些地址。

快速开始

初始化API客户端

API方法

1. 发货通知

2. 批量发货

3. 取件通知

4. 订单查询

5. 批量查询订单

6. 取消订单

7. 轨迹查询

8. 批量轨迹查询

9. 拦截件

10. 改件信息

11. 面单打印

12. 批量面单打印

国际物流（跨境 / 货运）快速开始

国际物流客户端与国内快递共用同一套工厂入口，差异仅在配置字段与「运输方式 / 海关申报」等国际要素。

国内货运（零担 / 整车 / 快运）快速开始

国内货运客户端与国内快递 / 国际物流共用同一套工厂入口，差异仅在配置字段与「服务类型（零担 / 整车 / 快运）」等货运要素。

物流链自动关联（v2.3.0，核心能力）

你不用自己去指定物流链的物流：给出运单号，SDK 自动识别归属承运商； 给出发货意图（起止国家 / 重量 / 运输方式），SDK 自动挑选每个环节的承运商并拼装整条链路。

1) 运单号自动识别承运商 —— ExpressApiClient::recognize()

底层由 CourierRecognizer 完成，内置各服务商运单号特征规则（前缀 / 长度 / 字符集）； 规则未命中时，可经 AggregateResolver 聚合 17TRACK / 快递100 / 快递鸟等已接入的权威源做确定性回退：

AggregateResolver 会把各家返回的外部承运商代码（如 17TRACK 的 ups、快递100 的 shunfeng） 经内置别名表映射为本 SDK 的内部承运商代码（如 sf），单个聚合源失败不阻断整体。 也可直接用 CourierRecognizer::registerPattern() 注册 / 覆盖规则。

2) 按发货意图自动拼装物流链 —— ExpressApiClient::buildChain()

不传 prefer 时，编排器按「已签约配置」自动挑选每个环节的最优承运商； 某环节未签约则自动回退同类目其他承运商，仍缺失则标记 unavailable 而不中断整链。

3) 按运单号自动识别并推断完整链路 —— ExpressApiClient::chainFromTracking()

三类入口均不触网：recognize() 与 buildChain()/chainFromTracking() 仅做本地识别与编排， 真正查询需调用 $chain->track($trackingNo)（单段失败相互隔离）。

自动发现能力菜单（物流链总览）

getApiMenu() 会基于各客户端实际方法，按 order / query / label / freight / customs 分类自动生成能力目录， 无需手工维护，便于前端动态渲染菜单或生成文档：

韧性与可观测性（v2.2.0）

失败重试（指数退避）

传输层在遇到瞬时故障（连接错误、超时、HTTP 5xx）时会按指数退避自动重试； 客户端错误（HTTP 4xx）视为终态，不重试。默认关闭重试，可在进程启动时全局开启：

重试为全局静态配置，作用于全部 30 家快递商。SSL 强制校验默认开启，可用 HttpClient::setVerifySsl(false) 关闭（仅测试/内网自签场景）。

响应归一化策略

所有响应经由 ResponseHandler 按快递商（provider）注册的策略统一判定成功/失败并解包业务数据， 避免散落在各客户端的重复判断。EMS / 顺丰已预置精确策略；其余快递商回退到保守默认策略 （仅在 error 字段、success === false、或 code ∈ [400,599] 时判定失败，不擅自改包结构）。

如需为某家快递商定制策略：

跨快递商批量轨迹查询

ExpressApiClient::batchQueryTracking() 接收「快递商 + 运单号」条目列表，逐单调用对应客户端， 单条失败相互隔离（不中断其余查询），最终汇总 results / success / failed：

版本号入口

请求诊断

无需引入日志依赖，可随时读取最近一次请求的诊断元信息（含耗时、HTTP 状态码、重试次数）：

面单布局功能设计

功能概述

面单布局功能用于生成和管理快递面单的打印布局配置，支持不同快递公司的面单模板。

面单模板结构

布局管理器

获取和使用字段值

核心类设计

LayoutManager

负责面单布局的管理，包括创建、读取、更新、删除模板。

Template

表示一个面单模板，包含尺寸信息和字段定义。

使用面单可视化编辑器

1. 启动PHP内置服务器：

2. 访问 http://localhost:8000/ 进入面单可视化编辑器

3. 使用编辑器功能：
   • 拖拽调整元素位置
   • 调整元素大小
   • 修改元素属性（字体、颜色、边框等）
   • 添加文本、条形码、二维码元素
   • 选择面单规格
   • 预览和导出配置

面单模板配置示例

多语言支持

AdvancedLayoutManager 支持创建和管理多语言字段，使得面单模板可以在不同语言环境下使用。

MultilingualField 类

MultilingualField 类继承自 Field 类，提供了多语言标签的支持。

构造函数

配置参数

• labels: 关联数组，键为语言代码，值为对应语言的标签
• 所有其他 Field 类的配置参数同样适用

方法

• addLabel(string $language, string $label): self - 添加语言标签
• getLabelByLanguage(string $language): ?string - 根据语言获取标签
• getLabels(): array - 获取所有语言标签
• setLanguage(string $language): self - 设置当前语言
• getLanguage(): string - 获取当前语言
• setLabel(string $label): self - 设置默认标签
• getLabel(): string - 获取当前语言的标签

使用示例

在模板中使用多语言字段

在创建模板时，可以通过在字段配置中添加 labels 参数来创建多语言字段：

错误处理

所有 API 调用失败都会抛出 Kode\ExpressApi\Common\Exception\ExpressApiException，其 getDetails() 可获取原始响应体，便于排查。响应是否成功、如何解包由 ResponseHandler 的按快递商策略统一决定 （详见上文「响应归一化策略」）。约定上的标准响应结构如下：

瞬时网络故障（连接错误 / 超时 / 5xx）会按 HttpClient::setRetry() 自动重试； 4xx 客户端错误不会重试，直接抛出 ExpressApiException。

开发指南

集成新的快递公司

1. 创建新的配置类（继承AbstractConfig）
2. 创建认证类（实现AuthInterface）
3. 创建客户端类（实现ClientInterface）
4. 更新ExpressApiClient.php，添加新的快递公司支持
5. 如该快递商响应结构与通用约定不同，调用 ResponseHandler::registerPolicy() 注册专属的错误判定 / 数据解包策略（可选，未注册则回退保守默认策略）

代码规范

本项目遵循PSR-12代码规范。

代码检查

使用PHP_CodeSniffer检查代码规范：

自动修复

自动修复代码规范问题：

运行测试

运行所有测试用例：

测试覆盖率

生成测试覆盖率报告：

测试要求

1. 测试覆盖率: 所有代码都必须有相应的测试用例，测试覆盖率应达到90%以上
2. 测试类型: 包含单元测试和集成测试
3. 测试环境: 测试应在沙箱环境中进行，避免影响生产数据

支持的快递公司

SDK 覆盖一条完整的物流链：国内快递 → 国际运输（海运 / 空运）→ 海关清关 → 末端派送。

国内快递（快递）

国际物流（跨境 / 货运）

国际物流客户端统一继承 International\AbstractInternationalClient，提供：

• sendShipment() 下单（含海关申报要素）
• createSeaFreight() / createAirFreight() 海运 / 空运便捷入口
• getQuotation() 运费报价
• declareCustoms() 海关申报
• queryCustoms() 清关查询
• queryOrder() / queryTracking() / cancelOrder() / printLabel() 标准能力

注：各服务商真实接口路径与字段以签约后的开放平台文档为准，SDK 已提供标准鉴权与传输骨架，接入时按文档核对即可。

国内货运（零担 / 整车 / 快运）

国内货运客户端统一继承 DomesticFreight\AbstractDomesticFreightClient，提供：

• sendShipment() 下单（零担 / 整车 / 快运，含发货人 / 收货人 / 货物 / 起止地）
• createLtl() / createFtl() 零担 / 整车便捷入口
• getQuotation() 运费报价
• queryNetwork() 网点查询
• queryOrder() / queryTracking() / cancelOrder() / printLabel() 标准能力

注：各服务商真实接口路径与字段以签约后的开放平台文档为准，SDK 已提供标准鉴权与传输骨架，接入时按文档核对即可。

聚合查询（运单轨迹 + 运单号自动识别）

聚合查询服务商只提供轨迹查询与运单号自动识别，并不承接下单 / 打单 / 拦截等实操业务； 调用其实操方法会抛出明确的「不支持」异常。它们更重要的角色是 CourierRecognizer 的权威回退解析器： 当运单号规则无法命中时，可将其接入为动态解析器，确定性地识别归属承运商。

• 已支持：京东快递/京东物流、快递100、快递鸟、聚合数据、17TRACK（见上表）

各快递公司特定配置参数

邮政EMS (ems)

参数说明：

• app_key: EMS分配的应用Key
• app_secret: EMS分配的应用密钥
• sandbox: 是否使用沙箱环境（测试环境）

顺丰速运 (sf)

参数说明：

• app_key: 顺丰分配的应用Key
• app_secret: 顺丰分配的应用密钥
• sandbox: 是否使用沙箱环境（测试环境）

韵达快递 (yunda)

参数说明：

• app_key: 韵达分配的应用Key
• app_secret: 韵达分配的应用密钥
• sandbox: 是否使用沙箱环境（测试环境）

中通快递 (zto)

参数说明：

• app_key: 中通分配的应用Key
• app_secret: 中通分配的应用密钥
• sandbox: 是否使用沙箱环境（测试环境）

申通快递 (sto)

参数说明：

• app_key: 申通分配的应用Key
• app_secret: 申通分配的应用密钥
• sandbox: 是否使用沙箱环境（测试环境）

菜鸟网络 (cainiao)

参数说明：

• app_key: 菜鸟网络分配的应用Key
• app_secret: 菜鸟网络分配的应用密钥
• partner_id: 菜鸟网络分配的合作伙伴ID
• sandbox: 是否使用沙箱环境（测试环境）

技术依赖

• PHP 8.3+
• PHPUnit 12（测试框架）

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

联系我们

如有问题或建议，请通过以下方式联系：

• 邮箱：[email protected]
• GitHub：https://github.com/kode/express-api