Mondial Relay Laravel Package

Product Decisions This Supports

• Feature: relay-point delivery at checkout. The package provides the backend for Mondial Relay parcel-shop search (SoapParcelShopClient) and shipment/label creation (RestShipmentClient via MondialRelayClient) — the two capabilities needed to offer “deliver to a pickup point” to French, Belgian, and broader EU customers.
• Feature: map-first and “near me” pickup selection. v4.2.0 adds coordinate-based search (ParcelShopSearchRequest::around($countryCode, $latitude, $longitude), or latitude/longitude arguments with an optional post code). This unlocks map pin-drops, geolocation-based store locators, and mobile checkout flows that previously required a post code — a meaningful UX and conversion lever, not just a backend detail.
• Feature: pickup-point detail quality. ParcelShop::schedule() exposes day-by-day opening hours (on($isoDay), isOpenOn(), isAlwaysOpen(), isEmpty()) instead of raw "0930-1300 1400-1900" strings, plus new $locker and $directions fields. That supports “open now” badges, locker filtering, and usable wayfinding copy in the picker — reduces drop-off at the selection step and “where exactly is it / is it open?” support contacts.
• Roadmap: France/EU expansion. If Mondial Relay is on the roadmap as a carrier option, this release changes the build-vs-buy calculus: v4.1.0 fixed previously fatal defects (label creation always rejected, relay-point search always failed with STAT 97, distances returned in metres as kilometres), and v4.2.0 extends the search surface. The package is now a viable integration rather than a base to fork and repair.
• Build vs buy. Building directly against Mondial Relay means handling SOAP signed-parameter ordering, brand-code padding, XSD element order, numeric STAT code keys, Level-based severity parsing, credential leakage in HTTP error bodies, and now opening-hours/business-hours modelling and geospatial query validation. This release absorbs that carrier-specific complexity, so the PM decision shifts further toward buying/integrating rather than owning a bespoke connector.
• Operational support and customer messaging. PSR-3 logging plus ConfigurationException / TransportException / ApiException let the team distinguish misconfiguration from carrier outages from Mondial Relay business rejections — useful for translated customer-facing errors and for support triage. v4.2.0 adds an earlier, cheaper failure mode: bad search input (no post code and no coordinates, a single coordinate, out-of-range coordinates) now raises \InvalidArgumentException client-side instead of a carrier round-trip, so bad requests surface in your own logs with your own stack traces rather than as ambiguous carrier rejections.
• Release risk decision. v4.2.0 introduces no documented breaking changes to the public API. The login → apiLogin, password → apiPassword, customerId → brandCode, secretKey → privateKey rename from v4.1.0 is only breaking for named arguments; positional calls are unaffected. One behavioural nuance worth flagging: callers that currently catch ApiException for malformed search parameters must also handle \InvalidArgumentException, since that validation moved in front of the API call.

When to Consider This Package

• Consider it when: you are on Laravel/PHP, need Mondial Relay Connect (REST) shipment/label creation plus WSI4 relay-point search (SOAP), and want a maintained wrapper with typed exceptions, PSR-3 logging, and sandbox-verified end-to-end behaviour.
• Consider it when: your checkout or store locator needs location-aware pickup search — coordinate search without a post code, opening-hours-aware display, locker identification, or wayfinding directions. These are v4.2.0 capabilities and are the strongest reason to adopt this release specifically rather than v4.1.0.
• Consider it when: you want to avoid owning the carrier’s protocol quirks — signed parameter ordering, XSD element ordering, status/Level parsing, credential redaction in exceptions, and now opening-hours parsing and coordinate validation.
• Look elsewhere when: you need a multi-carrier abstraction layer. This is a Mondial Relay-specific client, not a carrier-agnostic shipping platform.
• Look elsewhere when: you need webhooks, live tracking events, returns workflows, or label reprinting beyond the documented create/search operations — those are not covered here.
• Look elsewhere when: you require a strict no-breaking-change public API. v4.1.0 included breaking named-argument renames; pinning to a version and auditing call sites remains mandatory. v4.2.0 itself is additive, but its new input validation shifts an error path from ApiException to \InvalidArgumentException.
• Version floor: adopt v4.2.0 or later if coordinate search, opening hours, locker flags, or directions are in scope. Otherwise v4.1.0 or later is the minimum. Earlier versions had fundamental defects (label creation always failed with “10061 Problème de formatage du XML”; relay-point search always failed with STAT 97; successful responses rejected; errors ignored). Treat pre-4.1 releases as unsuitable for production.
• Dependency consideration: the relay-point search path is SOAP-based; confirm your runtime and extension set support it before committing to a rollout. Coordinate search does not remove the SOAP dependency.

How to Pitch It (Stakeholders)

To executives: Mondial Relay is a major lever for French and EU e-commerce conversion, especially pickup-point delivery. Earlier versions of this integration were not production-viable — label creation and relay-point search both failed outright. v4.1.0 was the reliability release; v4.2.0 builds on it with customer-visible capability: pickup points can now be found by map location or device position rather than requiring a post code, and the picker can show real opening hours, locker availability, and directions. That translates into a better selection experience and fewer “is it open / where is it” support contacts. The commercial ask is modest: adopt v4.2.0+, pin the version, and budget a short engineering pass for the named-argument rename carried over from v4.1.0.

To engineering: This is a low-level, carrier-specific client — useful, but not a multi-carrier abstraction. PSR-3 logging never records credentials, request bodies, or response bodies. Failures are typed (ConfigurationException, TransportException, ApiException) so callers can branch without parsing message strings; v4.2.0 adds pre-flight \InvalidArgumentException for invalid search parameters, so search call sites should catch it alongside ApiException and treat it as a caller bug, not a carrier incident. ApiException::getErrors() returns array<int|string, string> because PHP coerces numeric Mondial Relay codes to integer keys — account for that in consumers. ParcelShop::schedule() is the structured path; openingHours still holds raw strings for anyone who needs them, so migrate incrementally. $locker and $directions are additive optional properties — handle nulls. Positional constructor/create() calls remain source-compatible; named arguments are not (v4.1.0 change). Any existing wrapper or test using named arguments should be updated and covered by an integration test against the sandbox before release.

To product/support: Customer-facing errors can be translated by exception type rather than Mondial Relay’s raw message, and invalid search inputs are now rejected before they reach the carrier, giving cleaner telemetry on where the funnel breaks. Relay-point names and addresses are cleaned of the apostrophe-to-space artefact and padding, and pickup details now include structured opening hours, locker flags, and directions. That reduces support tickets for “missing street name”, “wrong distance”, “is this shop open?”, and “where do I collect?” complaints, and makes an “open now” filter feasible without bespoke parsing.