Documentation du module Mondial Relay & InPost pour Magento 2 et Adobe Commerce

Prérequis

Magento

Compatible Magento 2.4.0 à 2.4.7, OpenSource / Adobe Commerce / Mage-OS.

PHP

PHP >= 8.0
Extension SOAP (php-soap) pour la livraison en Point Relais® et l'impression des étiquettes
Extension SimpleXML (php-simplexml) pour l'impression des étiquettes API V2 (Dual Carrier)

Configuration

L'activation du mode de livraison Mondial Relay s'effectue depuis le menu :

Boutiques (Stores) > Configuration (Configuration) > Ventes (Sales) > Modes de livraison (Shipping Methods) > Mondial Relay / InPost

Version (Version) : version du module
Activé (Enabled) : activer les méthodes d'expédition Mondial Relay / InPost
Mode de collecte (Collection Mode) : détermine si les colis doivent être retirés en Point Relais (REL) ou à l'entrepôt (CCC)
URL API (API URL) : URL de l'API V1
Code Enseigne (API Company) : donnée à récupérer dans le compte connect : configuration des API
Clé privée (API key) : donnée à récupérer dans le compte connect : configuration des API
Code Marque (API Brand Code) : donnée à récupérer dans le compte connect : configuration des API
Test de connexion à l'API V1 (Test API V1 credentials) : tester les paramètres de connexion à l'API V1
API V2 (API V2) : activer l'API V2. L'API V2 permet de livrer à domicile partout en Europe avec le Dual Carrier. Il est nécessaire d'activer l'API V2 depuis votre compte.
- Mode (Mode) : Mode test (sandbox) ou production
- Brand Id API (Brand Id API) : donnée à récupérer dans le compte connect : configuration des API
- Login API (Login API) : donnée à récupérer dans le compte connect : configuration des API
- Mot de passe API (Password API) : donnée à récupérer dans le compte connect : configuration des API
- Test de connexion à l'API V2 (Test API V2 credentials) : tester les paramètres de connexion à l'API V2
Ordre de tri (Sort Order) : position de la méthode dans le tunnel de commande
Afficher la méthode si elle n'est pas applicable (Show Method if Not Applicable) : afficher la méthode Mondial Relay même si elle ne peut s'appliquer à l'adresse de livraison du client
Message d'erreur (Displayed Error Message) : Message affiché si la méthode ne peut s'appliquer à l'adresse de livraison du client

Etiquette (Shipping Label)

Taille étiquette (Label Size) : Format PDF de l'étiquette à générer (10x15, A4, A5)
Nom de l'expéditeur (Shipper name) : Nom de l'expéditeur affiché sur l'étiquette
Supprimer l'étiquette après (Delete label after) : Supprimer les étiquettes de la base de données X jour(s) après génération. Cette configuration permet de ne pas alourdir inutilement la base avec des données obsolètes.
Statut d'expédition (Shipping status) : Statut à associer à l'expédition une fois l'étiquette Mondial Relay générée
Poids de l'emballage par défaut (Default Packaging weight) : Ajouter un poids d'emballage par défaut dans le calcul du poids du colis

Retour (Return)

Type de retour (Return Type) : Retour à une adresse (LCC) ou dans un Point Relais®
Société (Company) : Destinataire du retour
Email (Email) : E-mail de la personne en charge du retour
Téléphone (Phone Number) : Téléphone de la personne en charge du retour
Code postal (Postcode) : Code postal des points de retrait à proposer pour le retour
Pays (Country) : Pays des points de retrait à proposer pour le retour

Type retour Point Relais®

Point Relais (Pickup location) : Point Relais® où récupérer le retour. La liste est actualisée en fonction du code postal et du pays (un enregistrement de la configuration est nécessaire)

Type retour LCC

Rue (Street) : Numéro et rue de l'adresse de retour
Ville (City) : Ville de l'adresse de retour

Limitation (Limit)

Debug (Debug) : Affichage des paramètres de limitation au chargement des points de retrait
Limite de poids (Weight Limit) : Activer la limite de poids pour la sélection des méthodes
Calcul du poids (Weight Calculation) :
- Par produit : limitation effectuée sur le poids du produit le plus élevé du panier. Permet d'expédier plusieurs Colis si la limite de poids autorisée pour tous les produits de la commande est dépassée.
- Par panier : limitation effectuée sur le poids total des produits du panier. Si la limite est dépassée, la méthode ne sera pas proposée.
Limite de développé (Size Limit) : Activer la limite du développé pour la sélection des méthodes (L + l + H en cm)
Calcul du développé (Size Calculation) :
- Par produit : limitation effectuée sur le développé du produit le plus élevé du panier. Permet d'expédier plusieurs Colis si la limite de développé autorisée pour tous les produits de la commande est dépassée.
- Par panier : limitation effectuée sur le développé total des produits du panier. Si la limite est dépassée, la méthode ne sera pas proposée.
Attribut produit longueur (Product Length Attribute) : Attribut produit longueur à utiliser dans le calcul du développé, champ texte avec nombre entier en centimètre.
Attribut produit largeur (Product Width Attribute) : Attribut produit largeur à utiliser dans le calcul du développé, champ texte avec nombre entier en centimètre.
Attribut produit hauteur (Product Height Attribute) : Attribut produit hauteur à utiliser dans le calcul du développé, champ texte avec nombre entier en centimètre.

Méthodes de livraison

Activez les méthodes de livraison Mondial Relay souhaitées :

Point Relais et Lockers (MED, 24L, APM)
Domicile (HOM)

Paramètres :

Activé (Enabled) : activer la méthode
Nom (Name) : nom de la méthode
Poids maximum (Maximum Weight) : poids maximum accepté pour affichage de la méthode (voir les options de limitation pour le calcul).
Développé maximum (Maximum Size) : développé maximum accepté pour affichage de la méthode (voir les options de limitation pour le calcul).
Prix (Price) : prix de la méthode (pays / montant / poids (de) / poids (à) / Gratuité). Pour un tarif unique, laissez vide les champs "poids (de)" et "poids (à)". Le montant de gratuité indiqué est calculé selon le sous-total TTC du panier avec remises.
Frais (Fee) : appliquer un frais supplémentaire selon un code postal. Le montant saisi est ajouté au prix de base.
- 20000 : le code postal doit être exactement 20000
- 20* : le code postal doit commencer par 20
Pays (Ship to Specific Countries) : pays activés pour la méthode
Assurance par défaut (Default Insurance) : Niveau d'assurance à appliquer par défaut lors de l'expedition (étiquette)
Tri (Sort Order) : position de la méthode

Uniquement en Points Relais® et Lockers :

Méthodes disponibles (Available methods) : méthodes à activer lors du choix des Points Relais®. Les méthodes sélectionnées déterminent le poids maximum autorisé pour l'affichage de la méthode (Points Relais L, XL ou Lockers).
Type de carte (Map Type) : Google Maps (licence) ou OpenStreetMap (gratuit)
- Google Map API Key (Google Map API Key) : clé d'API Google pour affichage de la carte. Générer une clé.
Ouvrir la liste des points de retrait au clic sur la méthode de livraison (Open pickup list on shipping method selection) : Ouvrir directement la liste des points de retrait au clic sur la méthode de livraison. Dans le cas contraire, affichage de la liste sur le bouton "Continuer"
Nombre de Points Relais (Number of pickup) : nombre de Point Relais® à présenter sur la carte
Adresse par défaut (Default address) : permet de proposer une adresse par défaut pour la liste des points de retrait si le client n'a saisi aucune adresse avant sélection de la méthode

Configuration du prix

Pour une tarification au forfait, la configuration sera par exemple :

Prix	Pays	Poids (de)	Poids (à)
5.90	France

Pour une tarification par poids, la configuration sera par exemple :

Prix	Pays	Poids (de)	Poids (à)
5.38	France		250
5.98	France	250	500
6.70	France	500	750
7.26	France	750	1000
8.06	France	1000

Important : Si le poids du panier dépasse le poids maximum défini dans les tarifs, la méthode sera toujours proposée mais au prix de 0. Il est recommandé de ne pas borner le tarif le plus élevé (laisser le champ vide).

Paramètres de test

API V1

URL API (API URL) : https://api.mondialrelay.com/Web_Services.asmx?WSDL
Code Enseigne (API Company) : BDTEST13
Clé privée (API key) : TestAPI1key
Code Marque (API Brand Code) : 11

API V2

Mode (Mode) : Sandbox
Brand Id API (Brand Id API) : BDTEST
Login API (Login API) : BDTEST@business-api.mondialrelay.com
Mot de passe API (Password API) : '2crtPDo0ZL7Q*3kLumB

Impression des étiquettes

Configuration

Pour l'édition de l'étiquette les paramètres natifs suivants doivent être configurés :

Magasins (Stores) > Configuration (Configuration) > Ventes (Sales) > Paramètres de livraison (Shipping settings) > Origine (Origin)

Remplir l'ensemble des champs (lieu où sont entreprosés les produits vendus).

Magasins (Stores) > Configuration (Configuration) > Général (General) > Général (General) > Informations magasin (Store information)

Nom de la boutique (Store name) : le nom commercial de la boutique
Numéro de téléphone de la boutique (Store phone number) : numéro de téléphone de la boutique

Grille des étiquettes Mondial Relay

Une grille de génération rapide des étiquettes est disponible depuis le menu :

Ventes (Sales) > Mondial Relay / InPost > Etiquettes (Shipping Labels)

Actions

Selon la disponibilité, 4 actions sont proposées :

Attente expédition

Créer l'expédition et l'étiquette : Ajoute une expédition unique et génère une étiquette.
Créer plusieurs expéditions et étiquettes basées sur le poids des produits: optionel, uniquement disponible avec le calcul du poids "par produit". Si le total du poids des produits est supérieur au poids maximum autorisé pour un colis, le système ajoute automatiquement plusieurs livraisons.

Attente étiquette

Créer l'étiquette : Génère une étiquette.
Imprimer le bon de livraison : Télécharge le PDF du bon de livraison (natif).

Prêt

Imprimer l'étiquette : Télécharge le PDF de l'étiquette.
Imprimer le bon de livraison : Télécharge le PDF du bon de livraison (natif).

Statut et poids

Le clic sur une ligne commande permet de modifier 3 informations :

Statut d'expédition : Permet d'associer un statut à l'expédition. Un statut est automatiquement associé à la création de l'étiquette. Ce statut est à définir dans la configuration.
Poids : Poids du colis en kgs ou lbs. Le poids du colis ne peut plus être modifié une fois l'expédition créée.
Poids emballage : Poids de l'emballage en kgs ou lbs.

Actions en masse

5 actions sont proposées :

Créer les expéditions et imprimer les étiquettes : Ajoute les expéditions, génère puis télécharge les étiquettes des commandes sélectionnées.
Imprimer les étiquettes : Télécharge un fichier PDF contenant les étiquettes des commandes sélectionnées.
Imprimer les bons de livraison : Télécharge un fichier PDF contenant les bons de livraison (natif).
Imprimer le bordereau de remise : Télécharge un fichier PDF des colis pour les commandes sélectionnées.
Mettre à jour le statut de livraison : Modifier le statut de livraison des commandes sélectionnées.

Exemple de bordereau de remise :

Création manuelle

Sur la vue de création d'expédition de la commande, sélectionnez la case "Créer l'étiquette de livraison" (si vous omettez de cocher la case, l'étiquette pourra être générée utlérieurement).

Dans la fenêtre suivante, sélectionnez les produits à ajouter au colis. Vous ne pouvez créer qu'un seul colis pour une même expédition. Le poids est automatiquement récupéré à partir de l'attribut "poids" des produits. Vous pouvez manuellement ajuster la valeur, pour prendre par exemple en compte le poids de l'emballage. Sélectionnez le niveau d'assurance (de 0 à 5). Les autres champs (longueur, largeur, profondeur) ne sont pas utilisés.

Note : le poids du colis peut être saisi en kilo-gramme (kgs) ou en Livre (lbs)

L'expédition est alors créée, le numéro de colis est automatiquement associé et transmis au client.

Création automatique

Sur la vue de création d'expédition de la commande, sélectionnez la case "Créer automatiquement l'étiquette" (si vous omettez de cocher la case, l'étiquette pourra être générée utlérieurement).

L'étiquette est alors automatiquement créé selon les données de la commande et les configurations par défaut.

Note : si une erreur survient à la génération de l'étiquette, l'expédition est tout de même créée. Vous pouvez corriger les erreurs puis créer de nouveau l'étiquette manuellement depuis la vue expédition.

Pour finir, vous pouvez imprimer l'étiquette depuis la grille des commandes, en sélectionnant les commandes concernées, puis en sélectionnant l'action "Imprimer les étiquettes".

Si la commande contient déjà une expédition, vous pouvez générer ou re-générer une étiquette depuis la vue expédition de la commande.

Etiquettes de retour

Le module permet au commerçant de générer une étiquette de retour pour un client, sans que celui-ci n'est besoin de payer la livraison.

Le client dépose le colis dans n'importe quel Point Relais®. Le colis est ensuite acheminé vers un Point Relais® choisi par le commerçant, ou directement à l'entrepôt du commerçant (LCC, voir conditions).

Adobe Commerce

La génération des étiquettes peut s'effectuer via le module RMA si celui-ci est activé (fonctionnalité native).

La génération de l'étiquette depuis le backoffice est possible à partir du moment où au moins un produit a été autorisé.

Le Point Relais® ou l'adresse (LCC) est défini dans la configuration :

Magasins (Stores) > Configuration (Configuration) > Ventes (Sales) > Modes de livraison (Shipping Methods) > Mondial Relay / InPost > Retour (Return)

Le client peut obtenir et imprimer l'étiquette depuis son compte client.

Magento OpenSource

La génération de l'étiquette de retour est possible à partir du moment où la commande a été expédiée (livraison générée). Sur la vue commande, un bouton Retour Mondial Relay apparaît :

Le formulaire permet de :

Saisir l'adresse de l'expéditeur (automatiquement remplie à partir des données de l'adresse de facturation du client)
Saisir l'adresse du retour, en Point Relais® ou à l'adresse du commerçant (LCC).

La liste des Points Relais® de retour proposée est modifiable depuis la configuration :

Magasins (Stores) > Configuration (Configuration) > Ventes (Sales) > Modes de livraison (Shipping Methods) > Mondial Relay / InPost > Retour (Return)

Code postal (Postcode) : Code postal des Points Relais® à proposer pour le retour
Pays (Country) : Pays des points de retrait à proposer pour le retour

Depuis la configuration, il est possible de sélectionner un Point Relais® ou une adresse de livraison (LCC) par défaut.

La validation du formulaire engendre la génération de l'étiquette. Il est nécessaire d'enregistrer le fichier PDF et de l'envoyer manuellement au client. Un lien de téléchargement à partager au client est également proposé.

API

Liste des points de terminaison REST

GET    /V1/guest-carts/:cartId/mondialrelay-pickup
PUT    /V1/guest-carts/:cartId/mondialrelay-pickup/:pickupId/:countryId/:code
DELETE /V1/guest-carts/:cartId/mondialrelay-pickup
GET    /V1/guest-carts/:cartId/mondialrelay-pickup/list/:countryId/:postcode
GET    /V1/guest-carts/:cartId/mondialrelay-pickup/list

GET    /V1/carts/mine/mondialrelay-pickup
PUT    /V1/carts/mine/mondialrelay-pickup/:pickupId/:countryId/:code
DELETE /V1/carts/mine/mondialrelay-pickup
GET    /V1/carts/mine/mondialrelay-pickup/list/:countryId/:postcode
GET    /V1/carts/mine/mondialrelay-pickup/list

GET    /V1/mondialrelayPickup/:pickupId/:countryId
GET    /V1/mondialrelayPickup
GET    /V1/mondialrelayPickup/:orderId

Les données d'un Point Relais® ("mondialrelay_code" et "mondialrelay_pickup_id") sont associées à l'adresse de livraison sur les endpoints natifs :

GET    /V1/orders/:id
GET    /V1/orders

Exemple :

"extension_attributes": {
  "shipping_assignments": [{
    "shipping": {
      "address": {
        "address_type": "shipping",
        "city": "LILLE",
        "company": "DIGITAL LOUNGE AND LABS",
        "country_id": "FR",
        "email": "65548402568cb@example.com",
        "entity_id": 468,
        "firstname": "John",
        "lastname": "Doe",
        "parent_id": 235,
        "postcode": "59000",
        "region": "Nord",
        "region_code": "59",
        "region_id": 247,
        "street": ["35 RUE DU FAUBOURG DES POSTES"],
        "telephone": "0610203040",
        "extension_attributes": {
          "mondialrelay_code": "MED",
          "mondialrelay_pickup_id": "023120"
        }
      }
    }
  }
}

Exemples

Récupérer une liste de Point Relais®

GET https://www.domain.tld/index.php/rest/V1/mondialrelayPickup?
    searchCriteria[filter_groups][0][filters][0][field]=country&
    searchCriteria[filter_groups][0][filters][0][value]=FR&
    searchCriteria[filter_groups][1][filters][0][field]=city&
    searchCriteria[filter_groups][1][filters][0][value]=Paris&
    searchCriteria[filter_groups][2][filters][0][field]=postcode&
    searchCriteria[filter_groups][2][filters][0][value]=75008

Récupérer les informations d'un Point Relais®

GET https://www.domain.tld/index.php/rest/V1/mondialrelayPickup/016485/FR

Récupérer les données du Point Relais® d'une commande

GET https://www.domain.tld/index.php/rest/V1/mondialrelayPickup/1