medusa-plugin-mondial-relay-v2

v0.0.1

Published

4 months ago

Medusa.js v2 plugin for Mondial Relay: relay point search (API 1 SOAP), shipment creation & tracking (API 2 REST), fulfillment provider.

0High
0Medium
0Low

monptitdev.fr

medusa plugin medusa-plugin medusa-v2 mondial-relay fulfillment shipping point-relais livraison

Medusa Plugin Mondial Relay v2

A comprehensive Medusa.js v2 plugin for integrating Mondial Relay shipping services into your e-commerce platform. This plugin provides both API 1 (SOAP) for relay point search and API 2 (REST) for shipment creation and tracking.

Features

🚚 Mondial Relay API 1 (SOAP)

Relay Point Search: Find nearby relay points by postal code, city, or GPS coordinates
Real-time Data: Live integration with Mondial Relay's official API
Multiple Search Methods: Support for postal code, city name, and GPS coordinates
Point Details: Complete relay point information including opening hours, distance, and type

📦 Mondial Relay API 2 (REST)

Shipment Creation: Create shipments with real tracking numbers
Label Generation: Generate shipping labels in PDF format
Tracking: Real-time shipment tracking
Order Integration: Seamless integration with Medusa orders and metadata

🎯 Fulfillment Provider

Automatic Fulfillment: Process orders through Mondial Relay
Dimension Calculation: Intelligent parcel dimension calculation from order items
Weight Management: Automatic weight calculation and validation
Metadata Storage: Store tracking information in order metadata

🖥️ Admin Interface

Shipment Management: View and manage all Mondial Relay shipments
Label Downloads: Download shipping labels directly from admin
Tracking Interface: Real-time tracking information
Order Integration: Direct access to order details and metadata

Installation

Prerequisites

Medusa.js v2.4.0 or higher
Node.js 20 or higher
PostgreSQL database
Mondial Relay API credentials

Install the Plugin

# Clone the repository
git clone <repository-url>
cd medusa-plugin-mondial-relay-v2

# Install dependencies
npm install

# Build the plugin
npm run build

# Publish with yalc (for local development)
yalc publish

Add to Medusa Backend

# In your Medusa backend directory
yalc add medusa-plugin-mondial-relay-v2
npm install

Configure in medusa-config.ts

import { loadEnv, defineConfig } from '@medusajs/framework/utils'

loadEnv(process.env.NODE_ENV || 'development', process.cwd())

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS!,
      adminCors: process.env.ADMIN_CORS!,
      authCors: process.env.AUTH_CORS!,
      jwtSecret: process.env.JWT_SECRET || "supersecret",
      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
    }
  },
  modules: [
    {
      resolve: "./src/modules/{your-modules}",
    },
  ],
  plugins: [
    {
      resolve: "medusa-plugin-mondial-relay-v2",
      options: {
        // Plugin options are configured via environment variables
      }
    }
  ],
  admin: {
    vite: () => {
      return {
        optimizeDeps: {
          include: ["@medusajs/icons", "@medusajs/admin-sdk"]
        }
      }
    }
  }
})

Configuration

Environment Variables

Create a .env file in your Medusa backend with the following variables:

# Mondial Relay API 1 (SOAP) Configuration
MONDIAL_RELAY_API1_URL=https://api.mondialrelay.com/Web_Services.asmx
MONDIAL_RELAY_ENSEIGNE=YOUR_ENSEIGNE
MONDIAL_RELAY_PRIVATE_KEY=YOUR_PRIVATE_KEY

# Mondial Relay API 2 (REST) Configuration
MONDIAL_RELAY_API_BASE_URL=https://connect-api-sandbox.mondialrelay.com
[email protected]
MONDIAL_RELAY_PASSWORD=YOUR_PASSWORD
MONDIAL_RELAY_CUSTOMER_ID=YOUR_CUSTOMER_ID

# Business Address (Sender Information)
BUSINESS_TITLE=Mr
BUSINESS_FIRSTNAME=Your First Name
BUSINESS_LASTNAME=Your Last Name
BUSINESS_STREET=Your Street Address
BUSINESS_HOUSE_NO=Your House Number
BUSINESS_COUNTRY_CODE=FR
BUSINESS_POSTCODE=Your Postal Code
BUSINESS_CITY=Your City
BUSINESS_PHONE=Your Phone Number
BUSINESS_MOBILE=Your Mobile Number
[email protected]

Production vs Sandbox

Sandbox: Use https://connect-api-sandbox.mondialrelay.com for testing
Production: Use https://connect-api.mondialrelay.com for live operations

API Endpoints

Store API (Public)

Get Shipping Rates

GET /store/mondial-relay/rates?cart_id={cart_id}

Response:

{
  "rates": [
    {
      "id": "mondial-relay-24R",
      "name": "Mondial Relay Point Relais Standard",
      "price": 417,
      "deliveryMode": "24R",
      "estimatedDays": 2,
      "description": "Livraison en point relais standard"
    }
  ]
}

Search Relay Points

GET /store/mondial-relay/relay-points?zipCode={zipCode}&city={city}
GET /store/mondial-relay/relay-points?latitude={lat}&longitude={lng}

Response:

{
  "relayPoints": [
    {
      "id": "FR-071039",
      "name": "RELAIS COLIS",
      "address": "8 RUE DOUDEAUVILLE",
      "city": "PARIS",
      "zipCode": "75018",
      "country": "FR",
      "latitude": 48.8846,
      "longitude": 2.3469,
      "openingHours": ["Lun-Ven: 9h-19h", "Sam: 9h-12h"],
      "distance": 0.5,
      "type": "RELAY"
    }
  ]
}

Track Shipment

GET /store/mondial-relay/tracking/{trackingNumber}

Admin API (Authenticated)

Get All Shipments

GET /admin/mondial-relay/shipments

Create Shipment

POST /admin/mondial-relay/shipments
Content-Type: application/json

{
  "orderId": "order_123",
  "relayPointId": "FR-071039",
  "weight": 1000,
  "deliveryMode": "24R",
  "recipient": {
    "title": "M.",
    "firstname": "John",
    "lastname": "Doe",
    "streetname": "123 Main St",
    "houseNo": "",
    "countryCode": "FR",
    "postCode": "75001",
    "city": "Paris",
    "phoneNo": "0123456789",
    "email": "[email protected]"
  }
}

Download Label

GET /admin/mondial-relay/label/{shipmentNumber}

Update Order Metadata

POST /admin/mondial-relay/update-order-metadata
Content-Type: application/json

{
  "orderId": "order_123",
  "metadata": {
    "trackingNumber": "MR123456789",
    "labelUrl": "https://...",
    "relayPointId": "FR-071039"
  }
}

Services

MondialRelayAPI1Service

Purpose: Handle relay point search using Mondial Relay's SOAP API

Key Methods:

searchRelayPoints(params): Search for relay points
generateSecurityKey(params): Generate MD5 security key for API authentication

Usage:

import { MondialRelayAPI1Service } from './services/mondial-relay-api1.service'

const api1Service = new MondialRelayAPI1Service(
  'https://api.mondialrelay.com/Web_Services.asmx',
  'YOUR_ENSEIGNE',
  'YOUR_PRIVATE_KEY'
)

const relayPoints = await api1Service.searchRelayPoints({
  zipCode: '75001',
  city: 'Paris',
  countryCode: 'FR'
})

MondialRelayAPI2Service

Purpose: Handle shipment creation and tracking using Mondial Relay's REST API

Key Methods:

createShipment(data): Create a new shipment
trackShipment(trackingNumber): Track an existing shipment
buildShipmentXML(data): Build XML request for shipment creation
parseShipmentResponse(response): Parse API response

Usage:

import { MondialRelayAPI2Service } from './services/mondial-relay-api2.service'

const api2Service = new MondialRelayAPI2Service(
  'https://connect-api-sandbox.mondialrelay.com',
  'YOUR_LOGIN',
  'YOUR_PASSWORD',
  'YOUR_CUSTOMER_ID'
)

const shipment = await api2Service.createShipment({
  orderNumber: 'ORDER_123',
  customerNumber: 'CUSTOMER_456',
  deliveryMode: '24R',
  location: 'FR-071039',
  weight: 1000,
  content: 'Products',
  recipient: { /* recipient data */ },
  sender: { /* sender data */ }
})

MondialRelayFulfillmentService

Purpose: Medusa fulfillment provider for automatic order processing

Key Methods:

createFulfillment(): Process order fulfillment
validateFulfillmentData(): Validate fulfillment data
updateOrderMetadata(): Update order with tracking information

Configuration:

// In medusa-config.ts
{
  resolve: "medusa-plugin-mondial-relay-v2",
  options: {
    // Options are loaded from environment variables
  }
}

Admin Interface

Shipment Management Page

Access the Mondial Relay admin interface at /app/mondial-relay in your Medusa admin.

Features:

View all shipments with tracking numbers
Download shipping labels
Track shipment status
View relay point information
Export shipment data

Admin Route Configuration

The admin interface is automatically registered when the plugin is installed. No additional configuration is required.

Frontend Integration

React Components

The plugin provides React components for frontend integration:

MondialRelaySelector

import { MondialRelaySelector } from './components/mondial-relay-selector'

<MondialRelaySelector
  onSelectPoint={(point) => {
    // Handle relay point selection
    console.log('Selected point:', point)
  }}
  zipCode="75001"
  city="Paris"
/>

MondialRelayRates

import { MondialRelayRates } from './components/mondial-relay-rates'

<MondialRelayRates
  cartId="cart_123"
  onSelectRate={(rate) => {
    // Handle rate selection
    console.log('Selected rate:', rate)
  }}
/>

API Integration

Fetch Shipping Rates

const fetchRates = async (cartId: string) => {
  const response = await fetch(`/store/mondial-relay/rates?cart_id=${cartId}`)
  const data = await response.json()
  return data.rates
}

Search Relay Points

const searchRelayPoints = async (zipCode: string, city: string) => {
  const response = await fetch(`/store/mondial-relay/relay-points?zipCode=${zipCode}&city=${city}`)
  const data = await response.json()
  return data.relayPoints
}

Create Shipment

const createShipment = async (orderId: string, relayPointId: string) => {
  const response = await fetch('/admin/mondial-relay/shipments', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      orderId,
      relayPointId,
      weight: 1000,
      deliveryMode: '24R'
    })
  })
  return response.json()
}

Environment Variables

Required Variables

| Variable | Description | Example | |----------|-------------|---------| | MONDIAL_RELAY_API1_URL | API 1 SOAP endpoint | https://api.mondialrelay.com/Web_Services.asmx | | MONDIAL_RELAY_ENSEIGNE | Your enseigne code | YOUR_ENSEIGNE | | MONDIAL_RELAY_PRIVATE_KEY | Your private key | YOUR_PRIVATE_KEY | | MONDIAL_RELAY_API_BASE_URL | API 2 REST base URL | https://connect-api-sandbox.mondialrelay.com | | MONDIAL_RELAY_LOGIN | API 2 login | [email protected] | | MONDIAL_RELAY_PASSWORD | API 2 password | your-password | | MONDIAL_RELAY_CUSTOMER_ID | Your customer ID | YOUR_CUSTOMER_ID |

Business Address Variables

| Variable | Description | Example | |----------|-------------|---------| | BUSINESS_TITLE | Sender title | Mr | | BUSINESS_FIRSTNAME | Sender first name | John | | BUSINESS_LASTNAME | Sender last name | Doe | | BUSINESS_STREET | Street address | 123 Main Street | | BUSINESS_HOUSE_NO | House number | 123 | | BUSINESS_COUNTRY_CODE | Country code | FR | | BUSINESS_POSTCODE | Postal code | 75001 | | BUSINESS_CITY | City | Paris | | BUSINESS_PHONE | Phone number | 0123456789 | | BUSINESS_MOBILE | Mobile number | 0123456789 | | BUSINESS_EMAIL | Email address | [email protected] |

Development

Project Structure

medusa-plugin-mondial-relay-v2/
├── src/
│   ├── admin/                    # Admin interface
│   │   └── routes/
│   │       └── mondial-relay/
│   │           └── page.tsx      # Admin page component
│   ├── api/                      # API routes
│   │   ├── admin/               # Admin API endpoints
│   │   │   └── mondial-relay/
│   │   │       ├── shipments/   # Shipment management
│   │   │       ├── label/       # Label downloads
│   │   │       └── tracking/    # Tracking endpoints
│   │   └── store/               # Store API endpoints
│   │       └── mondial-relay/
│   │           ├── rates/       # Shipping rates
│   │           ├── relay-points/ # Relay point search
│   │           └── tracking/     # Public tracking
│   ├── providers/               # Fulfillment provider
│   │   └── mondial-relay/
│   │       ├── index.ts         # Provider registration
│   │       └── service.ts       # Fulfillment service
│   ├── services/                # Core services
│   │   ├── mondial-relay-api1.service.ts  # API 1 service
│   │   ├── mondial-relay-api2.service.ts  # API 2 service
│   │   └── ign-geocoding.service.ts       # Geocoding service
│   └── index.ts                 # Plugin entry point
├── package.json
├── tsconfig.json
└── README.md

Building the Plugin

# Development build
npm run dev

# Production build
npm run build

# Publish with yalc
yalc publish

Testing

# Run tests (if available)
npm test

# Test API endpoints
curl -X GET "http://localhost:9000/store/mondial-relay/rates?cart_id=test"
curl -X GET "http://localhost:9000/store/mondial-relay/relay-points?zipCode=75001&city=Paris"

Debugging

Enable debug logging by setting the following environment variable:

DEBUG=medusa-plugin-mondial-relay-v2:*

Troubleshooting

Common Issues

1. API Authentication Errors

Error: Invalid credentials or Authentication failed

Solution:

Verify your API credentials in the .env file
Ensure you're using the correct environment (sandbox vs production)
Check that your enseigne and private key are correct

2. Relay Point Search Not Working

Error: No relay points found or API 1 error

Solution:

Verify the postal code format (5 digits for France)
Check that the city name is spelled correctly
Ensure your API 1 credentials are valid
Try using GPS coordinates instead of postal code

3. Shipment Creation Fails

Error: Shipment creation failed or API 2 error

Solution:

Verify all required fields are provided
Check that the relay point ID is valid
Ensure the weight is within Mondial Relay limits (max 3kg)
Verify parcel dimensions are within limits

4. Label Download Issues

Error: Label not found or Download failed

Solution:

Ensure the shipment was created successfully
Check that the tracking number is correct
Verify the label URL is accessible
Try regenerating the shipment

Debug Mode

Enable detailed logging by adding these environment variables:

DEBUG=medusa-plugin-mondial-relay-v2:*
MONDIAL_RELAY_DEBUG=true

API Response Logging

The plugin logs all API requests and responses. Check your Medusa logs for detailed information:

# View logs
tail -f logs/medusa.log

# View specific plugin logs
grep "Mondial Relay" logs/medusa.log

Support

For additional support:

Check the Medusa.js documentation
Review the Mondial Relay API documentation
Open an issue in the plugin repository
Contact Mondial Relay support for API-specific issues

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Changelog

v0.0.1

Initial release
API 1 integration for relay point search
API 2 integration for shipment creation
Admin interface for shipment management
Fulfillment provider integration
Frontend components for store integration

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Medusa Plugin Mondial Relay v2

Table of Contents

Features

🚚 Mondial Relay API 1 (SOAP)

📦 Mondial Relay API 2 (REST)

🎯 Fulfillment Provider

🖥️ Admin Interface

Installation

Prerequisites

Install the Plugin

Add to Medusa Backend

Configure in medusa-config.ts

Configuration

Environment Variables

Production vs Sandbox

API Endpoints

Store API (Public)

Get Shipping Rates

Search Relay Points

Track Shipment

Admin API (Authenticated)

Get All Shipments

Create Shipment

Download Label

Update Order Metadata

Services

MondialRelayAPI1Service

MondialRelayAPI2Service

MondialRelayFulfillmentService

Admin Interface

Shipment Management Page

Admin Route Configuration

Frontend Integration

React Components

MondialRelaySelector

MondialRelayRates

API Integration

Fetch Shipping Rates

Search Relay Points

Create Shipment

Environment Variables

Required Variables

Business Address Variables

Development

Project Structure

Building the Plugin

Testing

Debugging

Troubleshooting

Common Issues

1. API Authentication Errors

2. Relay Point Search Not Working

3. Shipment Creation Fails

4. Label Download Issues

Debug Mode

API Response Logging

Support

License

Contributing

Changelog

v0.0.1