Wechat Mini Program Delivery Return Bundle Laravel Package

Getting Started

This package is a Laravel bundle for handling WeChat Mini Program "delivery return" (发货信息录入/退货) workflows — i.e., reporting shipment and return logistics information back to WeChat's Mini Program API. Start by requiring it via Composer and checking for a published config file:

composer require tourze/wechat-mini-program-delivery-return-bundle
php artisan vendor:publish --tag=wechat-mini-program-delivery-return-config

Then look first at:

1. config/wechat-mini-program-delivery-return.php (if published) — for app ID / secret / API credentials.
2. The bundle's Service classes under src/ — these wrap the WeChat endpoints for uploading shipping and return-logistics info.
3. Any Symfony Messenger / event classes in the bundle, since Tourze bundles typically expose operations as message handlers rather than facades.

Minimal first use case: after a customer places an order in your Mini Program and you ship it, call the bundle's shipping-info service with the order ID, logistics company code, and tracking number, so WeChat can display delivery status in the user's order list and satisfy its "发货信息管理" compliance requirement.

Implementation Patterns

• Service injection over facades. Tourze bundles generally register their services in the container; inject the delivery-return service into your own order/fulfillment service rather than resolving it statically. That keeps it testable and lets you swap in a fake in tests.
• Hook it to your fulfillment transition. The natural integration point is wherever your Order moves to shipped or returned. Dispatch the WeChat upload from a domain event listener (OrderShipped, ReturnApproved) so the API call is decoupled from the request cycle and can be retried by a queue worker.
• Queue the API call. WeChat's APIs are rate-limited and can be slow or briefly unavailable. Wrap the call in a job with exponential backoff; a failed upload shouldn't roll back your local shipping state.
• Idempotency by order + tracking number. Persist a record of what you've reported (order ID, logistics company, tracking no., response) so a retried job doesn't create duplicate or conflicting reports.
• Configuration per environment. Keep the Mini Program app ID/secret in config/ backed by env vars; use separate WeChat sandbox or test accounts for staging so you don't pollute production order data.
• Logging around the boundary. Log the outgoing payload and the raw WeChat response at debug in development and info/warning in production — WeChat error codes are terse and you'll want the response body when diagnosing.

Gotchas and Tips

• Version 0.1.0 vs 0.0.2 is a pre-1.0 jump. The release notes only link the changelog diff, so treat 0.1.0 as potentially containing breaking API changes. Pin the version in composer.json, read the GitHub compare diff before upgrading, and check whether service class names, method signatures, or config keys changed.
• No documented changelog content. Because the release note is just a compare link, don't assume "minor version bump = safe." Review the diff or the commit history directly.
• Tourze bundles are often thin wrappers. They may assume you're using the broader Tourze WeChat ecosystem (HTTP client, token storage, message bus). Verify whether token/cache handling is provided or whether you must supply an access-token provider yourself.
• WeChat credential scope. The Mini Program access token is distinct from the Official Account token; make sure the configured credentials are for the right app type, or you'll get cryptic 40013/40125 errors.
• Error handling is easy to under-do. WeChat returns HTTP 200 with an errcode in the body. Check the business error code, not just the HTTP status.
• Extension points. If the bundle publishes events or uses Symfony Messenger handlers, prefer listening to those over subclassing its services — subclasses will break on the next minor release. If it lacks a hook you need, wrap the service in your own class rather than editing vendor code.
• Test double it. In feature tests, bind a fake implementation of the delivery-return service so your test suite never hits WeChat; assert on what would have been reported.