Conformance with the Mondial Relay documentation

What the add-on does, against the documents of Mondial Relay, and what could not be checked. The documents (saved as text during development) are:

Short name	Document	Used for
DC	WEB SERVICE DUAL CARRIER, format V-2.7.1, June 2024	API 2: shipments and labels (ShipmentCreationRequest)
WS	WEB SERVICE, V-5.14, January 2025	API 1: Point Relais search, tracking, security key, status codes
WIDGET	WIDGET V4.1, December 2019	The Point Relais picker
PRES	Presentation of WebServices V-1.1, April 2025	Rules for calls, tracking frequency, what each API is for
Schemas	Web_Services.wsdl, Mondial-Relay-Shipment-API-.Request.1.0.xsd, ...Response.1.0.xsd and two sample XML files, saved in tests/fixtures/official	Element order, limits, validation of every request in the unit tests

How it was tested. Every request the add-on builds is validated against the request XSD (libxml) and the WSDL types in tests/unit.php and again by the mock server (tests/mock-server/server.php), which also checks the documented field patterns and the Security hash. The answers of the mock are built from the sample responses. No call was made to the Mondial Relay sandbox or to the live service, because no credentials were available. Everything below that says “verified” means “verified against the documents and the schemas”; everything about the live behaviour of the services is flagged. See notes/PROGRESS.md for what was tested on which store.

Verified against the documents

Topic	Document says	What the add-on does
Two APIs	PRES section 1: API 1 (SOAP) searches Point Relais and Lockers and tracks; API 2 (“dual carrier”, REST) creates shipments and labels; they have different security parameters issued in Connect	Two credential blocks on the Connection page: API 2 login, password, customer id; API 1 brand and private key
API 2 addresses	DC “Service, XSD location and credentials”: test https://connect-api-sandbox.mondialrelay.com/api/shipment, production https://connect-api.mondialrelay.com/api/shipment; one method for outbound and return labels; headers Accept: application/xml, Content-Type: text/xml; UTF-8 without BOM	Test mode and Live mode use those addresses and headers; one POST per label
API 1 address	WS “General description”: https://api.mondialrelay.com/Web_Services.asmx	Used for search and tracking in both modes
Security key	WS “Generating the security key”: concatenate all input parameters in the order of the documentation (empty optional parameters add nothing), append the private key, MD5, upper case	Api::security(); the unit test checks it against the document’s worked example (see the inconsistency below). Order for the search: Enseigne, Pays, NumPointRelais, Ville, CP, Latitude, Longitude, Taille, Poids, Action, DelaiEnvoi, RayonRecherche, TypeActivite, NombreResultats; for tracking: Enseigne, Expedition, Langue
Public API 1 test account	WS “General description”: brand BDTEST13, private key TestAPI1key	Shown in the Connection page help and used by the mock
Request element order	Request XSD sequence: Context (Login, Password, CustomerId, Culture, VersionAPI), OutputOptions, ShipmentsList/Shipment (OrderNo, CustomerNo, ParcelCount, DeliveryMode, CollectionMode, Parcels, DeliveryInstruction, Sender, Recipient)	Client\Connect::request() follows the XSD; the unit tests validate it
Modes	DC: CCC merchant collection, REL Point Relais collection, LCC merchant delivery, HOM home delivery, 24R Point Relais delivery, 24L Point Relais XL delivery, XOH D+1; “The use of the CCC / LCC modes will determine if the shipment is an outbound or a return parcel”; PRES: for a return the sender is the end customer and the recipient the return address	Outbound CCC + 24R / 24L / HOM; return REL (location Auto) + LCC with sender and recipient swapped
Point Relais location	DC: DeliveryMode location mandatory for 24R, 24L, XOH	The chosen point is sent, never invented; an order without a point is refused
Point must be in the delivery country	WS status 92: “The Point Relais country code and the consignee’s country code are different”	The picker allows only the delivery country; the server compares again; the label is refused before sending otherwise
Weight	DC: grams, “Minimum 10grs”	Parcel::grams(), at least 10
Phone numbers	DC “Regular expression for phone numbers” per country; PhoneNo “Mandatory for home delivery/collection”; error 10085	Normalised to +<dialing code><number>, checked against the table of the document; home delivery without a valid number is refused before sending
Netherlands	DC: house number filled at the end of the street field	Done for NL addresses
Errors	DC “Error handling”: business errors and warnings in StatusList; technical errors as exceptions; errors prevent the request, warnings do not	Warnings are logged; errors are rejections; HTTP/transport errors are technical
Tracking codes	WS “Status codes”: 80 recorded parcel, 81 parcel in process at Mondial Relay, 82 delivered parcel, 83 anomaly; 94 unknown parcel	Mapped to created, in transit, delivered, problem; 94 keeps the state
Rules for calls	WS “Regularity of calls” and PRES: no batch mode, calls spread over the day; tracking is “not intended for daily tracking updates”, at most 4 to 6 queries per shipment and day; “A completed shipment (delivered, returned, etc.) should no longer be queried”	Open shipments about every 5 hours (at most 5 scheduled queries a day), problem shipments every 12 hours, delivered never; the queue is processed continuously, not in a night batch
No cancel, no lookup	DC describes a single operation (create); there is no cancel and no search by reference	“Cancel” is local only. Because a lost answer cannot be resolved through the API: the request is saved first, OrderNo is deterministic, no automatic retry after a timeout, and the merchant adopts the 8-digit shipment number found in Connect. The adoption is verified with WSI2_TracingColisDetaille (status 94 = unknown parcel)
API 1 shipment creation	WS: WSI2_CreationExpedition / WSI2_CreationEtiquette “no longer usable for a new onboarding”; “Accounts created from 23/12/2024 will be blocked”; V-5.11 stopped the methods	Not used. Labels use API 2
Labels not resized	WS “Label print”, PRES section 4: labels generated by the API must not be altered or resized	Stored as received; the setting names the 10x15, A4 or A5 size
End of COD	WS V-5.9, DC V-2.7.1 “End of COD”	No COD field; labels for the payment method the merchant marks as cash on delivery are refused
Multi-parcel	DC: “24L, LD1, LDS” are multi-parcel; others single-parcel	Always one parcel
Home delivery	WS: “The home deliveries are not eligible with this WS but are eligible with the WS dual carrier”; delivery modes “are not available for all contracts”	HOM is offered through API 2; whether your contract includes it decides

Flagged: inconsistencies in the documents

Topic	What the documents say	What the add-on does
Security key example	The worked example in WS V-5.14 prints the string BDTEST1312345678FRTestAPI1key but its hash 33DA5F122DAA40241087CC7845BEA4B1 is the MD5 of the same string with the old test key PrivateK (the key changed in V-5.12). It is also an example of WSI3_GetEtiquettes, a method no longer in use	The unit test uses PrivateK for the hash of the example and TestAPI1key as the current public test key
Request XSD against the PDF	ShipmentValue is required in the XSD but absent from the PDF example; its Currency enumeration is the placeholder value. The PDF example puts Weight before Length, the XSD sequence is Content, Length, Width, Depth, Weight. The example has empty PhoneNo / MobileNo elements, which break the XSD pattern \+\d{3,20}. The example element Deptht in the options text is a typo	ShipmentValue is not sent (only the ASS insurance option needs it); the XSD order is followed; empty elements are omitted
Response XSD against the PDF	The response XSD has no ShipmentNumber attribute, the PDF example response has it	The attribute is read. An answer without a valid number is parked as “result unknown”
Field names	The PDF names Lgdr1, Horaire_ Lundi, Tracing_Libelle, Tracing_Lieu; the WSDL names LgAdr1, Horaires_Lundi, Libelle, Emplacement	The WSDL names are used
Name lengths	The PDF table says Firstname 32 / Lastname 32 / 40 together and Streetname 40; the XSD says 30 each; errors 10062 and 10063 say Title + first + last name and HouseNo + street name must not exceed 30	The strictest value is used: 30 characters together
Case	The patterns are upper case only (^[0-9A-Z_\-'.,/ ]{0,30}$) while the examples use mixed case (“John”, “Livres”)	Case is kept. UNVERIFIED whether the live service is case-insensitive
Location code	The examples show FR-66974 for the point the widget calls 066974 (the same Agence Mondial Relay in Hem); the XSD comment shows FR00001	Sends <country>-<point number without leading zeros>. UNVERIFIED on the live service

Flagged: not verifiable against the documents

Topic	Status
API 2 sandbox and test credentials	The document shows placeholders only ([email protected], password xxxxx, CustomerId BDTEST). Real values are issued in Connect (Administration > Configuration des API, API version V2.0). UNVERIFIED against the live sandbox: no sandbox call was made. All API 2 behaviour is verified against the XSD, the PDF and a local mock only
Character set	Accents are transliterated (French, Spanish, German and Dutch letters: é to e, the oe ligature to oe, ß to ss) because the patterns are ASCII; other characters become spaces; then the text is cut by characters at the documented lengths (Firstname + Lastname 30, HouseNo + Streetname 30, City 30, AddressAdd1 to 3 30, PostCode 10, Content 40, OrderNo 15, CustomerNo 9). Behaviour of the live service with accents is UNVERIFIED
Public tracking page	https://www.mondialrelay.fr/suivi-de-colis/?numeroExpedition=<n>&codePostal=<zip> is not in the documents: UNVERIFIED that it opens the parcel
Opening hours format	Horaires_<day> is an array of 4 strings (opening and closing time of slot 1 and 2). The WSDL only says ArrayOfString; HHMM is assumed, HH:MM is accepted and 0000 means none. UNVERIFIED
Tracking language	Langue is sent as FR; the supported languages are UNVERIFIED. Culture of API 2 is fixed to fr-FR as in every example
Where Connect shows OrderNo	The sample label shows OrderNo as MR.Expedition.ReferenceExterne and CustomerNo as MR.Expedition.ReferenceClient; which Connect search field finds them is UNVERIFIED
Widget	The document asks the page to load jQuery 2.2.4 and an unversioned Leaflet. The add-on uses the store’s jQuery and Leaflet 1.9.4 from unpkg; compatibility is UNVERIFIED. Offline tests use a stand-in widget with the same plugin name and callback; whether the real widget was run in a browser is stated in notes/PROGRESS.md
Distance	WS states meters; the add-on stores it and does not show it
Rate limits	No numeric limit is documented for API 2 or for the search; only the rules for calls above

Not offered or not covered

• XOH (D+1 delivery): “a specific action is mandatory by EDI in addition to the creation of the shipment and label by this API”. Not offered.
• Cash on delivery: ended; refused.
• Cancel, lookup by reference: not available in the API.
• Multi-parcel (24L, LD1, LDS): the add-on always sends one parcel.
• Options ASS (insurance value) and LNG, shipmentValue, DeliveryInstruction: not sent.
• IPL output, printer models, label-free QR code returns: not offered.
• Poland (dimensions mandatory up to 64 x 39 x 38 cm, +48 phone), Italy (IT/IT), Poland (PL/PL), UK (UK/XX) flows: PRES: “These documentations do not include IT/IT, PL/PL, UK/XX flows”. Not covered.
• Lockers by size (SMA, APM, MED searches): the add-on searches with 24R and 24L only; lockers appear in the 24R results as Mondial Relay returns them.
• API 1 methods WSI2_RechercheCP, WSI2_STAT_Label, WSI3_GetEtiquettes, shipment creation.

Privacy

• Point Relais deliveries send no e-mail address and no phone number unless the setting “Send e-mail address and mobile number to Mondial Relay” (default off) is on.
• Home delivery always sends the customer’s phone number, because the document makes it mandatory (error 10085); the e-mail address only with the setting.
• The sender address, e-mail and phone are the merchant’s own.
• The picker loads scripts and map tiles from third-party servers (widget.mondialrelay.com, unpkg.com, OpenStreetMap) only when the customer opens it.

Open items that need a real Mondial Relay account

• API 2 test and live credentials and one label from the sandbox: check the location code format, the case handling, the accents, that ShipmentValue can be omitted, that ShipmentNumber is returned and what the unknown-result codes look like.
• The public tracking page link, the opening-hours string format, the supported tracking languages and where Connect shows the references.
• Written permission to use Mondial Relay’s logo. No logo is used.