企业官网建设流程全解析

• 后端
• 即时通讯

本文基于 EasyWeChat 5.x 文档中的《小程序发货信息管理》章节，完整讲解微信小程序"订单发货管理"能力在 EasyWeChat 中的调用方式。你将掌握发货信息录入、合单录入、发货状态查询、确认收货提醒、消息跳转路径设置以及交易管理开通状态查询等 7 类接口的实际用法与参数结构，可直接照搬代码接入自己的小程序订单履约流程。

能力概览与前置准备

"发货信息管理"（微信官方能力，对应小程序"订单发货管理"）用于让小程序商家在发货后主动将物流信息上报给微信，从而支撑订单发货状态透出、确认收货提醒、交易保障等能力。EasyWeChat 5.x 文档（docs/src/5.x/mini-program/shipping.md）将这一能力封装为$app->shipping服务对象，共暴露以下接口：

在开始调用前，需要先初始化小程序应用实例。按 小程序实例化说明 的约定，本页所有示例中的$app均指通过Factory::miniProgram($config)创建的实例：

use EasyWeChat\Factory; $config = [ 'app_id' => 'wx3cf0f39249eb0exx', 'secret' => 'f1c242f4f28f735d4687abb469072axx', // 下面为可选项 // 指定 API 调用返回结果的类型：array(default)/collection/object/raw/自定义类名 'response_type' => 'array', 'log' => [ 'level' => 'debug', 'file' => __DIR__.'/wechat.log', ], ]; $app = Factory::miniProgram($config);

初始化完成后，即可通过$app->shipping->方法名(...)调用发货信息管理的全部接口。需要注意的是，这些接口底层依赖小程序access_token完成身份认证：从仓库源码看，小程序应用通过 src/MiniApp/Application.php 中的getAccessToken()与createClient()构建AccessTokenAwareClient，所有 API 请求都会自动携带并管理访问令牌，开发者无需手工传参；当令牌过期时，客户端还会依据errcode/error字段自动判定失败并触发重试（可参考 src/Kernel/HttpClient/AccessTokenAwareClient.php 的实现）。因此你只需关注业务参数本身。

发货信息录入接口

当用户下单支付成功后，商家完成发货时，应调用uploadShippingInfo上报该笔订单的物流信息。这是整个发货管理流程中最核心的接口。

$data = [ 'order_key' => [ 'order_number_type' => 1, 'mchid' => '', 'out_trade_no' => '' ], 'logistics_type' => 4, 'delivery_mode' => 1, 'shipping_list' => [ [ 'tracking_no' => '323244567777', 'express_company' => 'DHL', 'item_desc' => '微信红包抱枕*1个', 'contact' => [ 'consignor_contact' => '189****1234', 'receiver_contact' => '189****1234' ], ], ], 'upload_time' => '2022-12-15T13:29:35.120+08:00', 'payer' => [ 'openid' => 'oUpF8uMuAJO_M2pxb1Q9zNjWeS6o' ] ]; $app->shipping->uploadShippingInfo($data);

关键参数说明：

• order_key（订单标识）：用于定位是哪一笔交易。
  • order_number_type：订单号类型，示例中取1，代表以微信支付订单号作为标识，其余取值含义以微信官方文档为准；
  • mchid：商户号；
  • out_trade_no：商户订单号（当以商户订单号作为标识时使用）。
• logistics_type（物流类型）：示例中取4（即"其他"物流类型），实际业务中请根据微信官方枚举定义选择实体物流、虚拟物流或线上物流等类型。
• delivery_mode（发货方式）：示例中为1，用于区分商家自行寄件或快递公司揽收等发货模式。
• shipping_list（包裹明细）：可一次上报多个包裹，每个包裹包含：
  • tracking_no：运单号；
  • express_company：快递公司编码（示例为DHL，即国际快递 DHL）；
  • item_desc：商品描述，如"微信红包抱枕*1个"；
  • contact：联系方式，含consignor_contact（发货人联系方式）与receiver_contact（收货人联系方式）。
• upload_time（发货时间）：采用 ISO 8601 格式的带时区时间串，如2022-12-15T13:29:35.120+08:00，建议在服务端生成当前发货时间后原样传入。
• payer（支付用户）：openid为付款用户在小程序中的唯一标识，用于微信侧关联该笔交易与用户。

业务场景示例：用户在微信内完成支付后，订单进入"待发货"状态；仓库出库、快递揽收后，服务端生成运单号，调用本接口将out_trade_no（或微信支付transaction_id）、运单号、快递公司、发货/收货人联系方式一并上报，微信侧即可在订单详情中展示物流进度。

发货信息合单录入接口

当一笔支付交易被拆分成多个包裹（例如分仓发货、预售与现货分批发货），或需要跨订单合并上报时，使用uploadCombineShippingInfo：

$data = [ 'order_key' => [ 'order_number_type' => 1, 'mchid' => '', 'out_trade_no' => '' ], 'sub_orders' => [ 'order_key' => [ 'order_number_type' => 1, 'transaction_id' => '', 'mchid' => '', 'out_trade_no' => '' ], 'logistics_type' => 4, 'delivery_mode' => 1, 'shipping_list' => [ [ 'tracking_no' => '323244567777', 'express_company' => 'DHL', 'item_desc' => '微信红包抱枕*1个', 'contact' => [ 'consignor_contact' => '189****1234', 'receiver_contact' => '189****1234' ], ], ], ], 'upload_time' => '2022-12-15T13:29:35.120+08:00', 'payer' => [ 'openid' => 'oUpF8uMuAJO_M2pxb1Q9zNjWeS6o' ] ]; $app->shipping->uploadCombineShippingInfo($data);

与单笔录入相比，本接口的差异集中在：

• 顶层order_key用于标识父交易（即用户实际支付的那笔订单）；
• sub_orders中按子订单再次给出order_key（此处可以看到还支持transaction_id字段，即微信支付交易号），并各自携带独立的logistics_type、delivery_mode与shipping_list，实现"一笔支付、多单多包裹"的灵活上报；
• upload_time与payer的语义与单笔录入一致，位于顶层。

适用场景：用户在商城一次下单多件商品，系统拆分为两个包裹分别由不同仓库发出；此时先以支付订单为父单，再分别为每个子订单写入各自的运单信息，用户端即可看到完整的分包裹物流轨迹。

查询订单发货状态

商家或运营后台需要确认某笔订单是否已完成发货上报、查看当前发货状态时，调用getOrder：

$data = $app->shipping->getOrder([ 'transaction_id' => 'xxx' ]);

参数说明：

• transaction_id：微信支付交易号（微信支付成功后由微信下发的支付单号）。

接口返回该订单的发货状态信息（如是否已上报、上报时间、运单号等），可将其用于：发货后校验上报是否成功、订单管理后台的状态回显、以及对未发货订单进行补录提醒。

查询订单列表

需要批量拉取已录入发货信息的订单时，调用getOrderList：

$data = $app->shipping->getOrderList();

该接口支持分页拉取当前小程序已上报发货信息的订单列表，适合在管理后台做"发货记录"列表页：定时任务同步发货状态、导出对账、异常订单巡检等场景均可复用此接口。如需分页，请在$data中按微信官方接口要求补充分页参数（页面大小、起始位置等，具体以微信官方文档为准）。

确认收货提醒接口

当包裹被签收或商家希望主动提醒用户确认收货时，调用notifyConfirmReceive：

$data = [ 'transaction_id' => '42000020212023112332159214xx', 'received_time' => '' ]; $app->shipping->notifyConfirmReceive($data);

参数说明：

• transaction_id：微信支付交易号（示例为一串完整的支付单号）；
• received_time：收货时间，ISO 8601 格式（示例中为空字符串，表示按接口要求可选的场景下留空）。

业务价值：主动触发"确认收货"提醒可以缩短订单的确认收货周期，帮助商家更快完成交易结算。通常在物流轨迹显示"已签收"后的一段时间内调用本接口。

消息跳转路径设置接口

微信侧推送的订单相关消息（如发货通知、确认收货提醒）默认展示在订单卡片中，通过setMsgJumpPath可以指定用户点击消息后的落地页：

$data = [ 'path' => 'pages/goods/order_detail?id=xxxx', ]; $app->shipping->setMsgJumpPath($data);

参数说明：

• path：小程序页面路径（可携带 query 参数），示例为pages/goods/order_detail?id=xxxx，即订单详情页并带上订单 ID。

使用建议：将落地页设置为带订单 ID 参数的订单详情页，用户从发货消息进入后即可直接查看对应订单的物流与售后信息，提升转化与体验。

查询服务开通与交易结算管理确认状态

这两个查询接口用于在接入前或日常运营中校验小程序账号的状态：

// 查询小程序是否已开通发货信息管理服务 $app->shipping->isTradeManaged(); // 查询小程序是否已完成交易结算管理确认 $app->shipping->isTradeCompleted();

• isTradeManaged()：判断当前小程序是否已开通"发货信息管理"服务。若未开通，上报发货信息前需要先在微信公众平台完成开通，否则接口可能返回错误。
• isTradeCompleted()：判断小程序是否已完成"交易结算管理确认"。这是交易保障链路中的一环，确认状态会影响部分交易能力的可用性。

建议在启动发货上报任务前先调用这两个接口做前置校验，未开通/未确认时给出明确的引导提示，避免运行时才发现权限问题。

调用链路与源码佐证

虽然 5.x 文档中$app->shipping是一组高层的便捷方法，但其底层仍然复用 EasyWeChat 小程序模块统一的请求链路。从当前仓库 src/MiniApp/Application.php 可以看到该链路的几个关键事实：

1. 统一网关：所有请求默认以https://api.weixin.qq.com/为base_uri，发货信息管理相关接口同样走该网关；
2. AccessToken 自动注入：createClient()返回AccessTokenAwareClient，将getAccessToken()产出的令牌注入每个请求；令牌失效（如返回errcode非 0 或含error字段）时由failureJudge判定并配合AccessTokenExpiredRetryStrategy自动重试；
3. 响应类型可配置：response_type配置项决定接口返回array（默认）/collection/object/raw等形态，本文示例均按默认数组形态编写；
4. 可插拔客户端：若需在测试中模拟接口，可参考 src/Kernel/Traits/MockableHttpClient.php 替换 HTTP 客户端，方便编写单元测试。

因此在生产环境中，你无需关心access_token的获取、缓存与刷新细节，只需保证Factory::miniProgram($config)的app_id与secret正确，即可放心调用上述 8 个方法。

实践建议与注意事项

• 参数合法性：order_key中的mchid、out_trade_no/transaction_id必须与微信支付侧的真实交易数据一致，否则无法关联到订单；
• 时间格式：upload_time、received_time使用 ISO 8601 带时区格式（如2022-12-15T13:29:35.120+08:00），建议服务端统一生成，避免客户端时区差异导致上报失败；
• 多包裹场景优先合单：一笔支付对应多个运单时，使用uploadCombineShippingInfo一次性上报，避免重复录入导致订单状态错乱；
• 开通前置校验：正式上线前调用isTradeManaged()与isTradeCompleted()确认账号状态，未开通时先到微信公众平台完成相应设置；
• 发货状态回查：录入后可通过getOrder回查上报结果，结合getOrderList定期巡检，确保每笔已支付订单都完成了发货信息上报；
• 消息落地页：提前通过setMsgJumpPath配置好订单详情落地页，让用户从发货、收货提醒消息直达订单上下文。

以上即 EasyWeChat 5.x 小程序发货信息管理的全部接口用法。将示例中的业务参数替换为你的真实订单数据，即可快速完成小程序端"发货上报—状态查询—收货确认"的完整履约闭环。

• 后端
• 即时通讯