PrestaShop

PrestaShop Mondial Relay: Conquering the 'Incorrect Parcel Weight' API 20 Error

Debugging PrestaShop PHP code for Mondial Relay weight issue
Debugging PrestaShop PHP code for Mondial Relay weight issue

PrestaShop Mondial Relay: Conquering the 'Incorrect Parcel Weight' API 20 Error

As e-commerce migration experts at Migrate My Shop, we frequently encounter complex challenges in integrating shipping modules with PrestaShop. One of the most frustrating, yet common, issues that can halt your order fulfillment process is the dreaded "API 20: Poids du colis incorrect" (Incorrect parcel weight) error when using the Mondial Relay module.

This error, as highlighted in a recent PrestaShop forum thread, can leave merchants pulling their hair out, especially when all settings seem correct. Let's dive deep into understanding and resolving this persistent problem, ensuring your parcels are weighed correctly and labels are generated without a hitch.

The Frustrating Scenario: When Correct Weight Isn't Enough

Imagine this: You have a PrestaShop 8.1.4 store, running Mondial Relay module 4.3.1. An order comes in, totaling a clear 1.6 kg. You navigate to generate the shipping label, only to be met with a brick wall. If you enter "1.6" into the weight field, the module rejects it, claiming the weight is "inferior to 15g" – clearly expecting grams. So, you correctly enter "1600" (for 1600 grams), and *boom*: "API 20: Poids du colis incorrect."

This was the exact predicament faced by 'kerlin' in the PrestaShop forum. Despite extensive troubleshooting, including:

  • Setting PrestaShop's default weight unit to grams.
  • Attempting an older module version (3.6.2).
  • Clearing PrestaShop cache and deleting development/production folders.
  • Resetting and reconfiguring the Mondial Relay module.
  • Trying various weight formats and values (e.g., 20g).

The error persisted. What makes it even more perplexing is that other shipping modules, like Colissimo, worked flawlessly on the same setup, pointing directly to an issue within the Mondial Relay integration itself.

A PrestaShop admin panel showing an error message 'API 20: Poids du colis incorrect' next to a Mondial Relay shipping label generation interface.
Illustration 1: Visualizing the 'API 20: Poids du colis incorrect' error within the PrestaShop back office.

Unpacking the Root Causes: Unit Mismatches and Data Formatting

The community's insights, particularly from 'Alexandre Carette' and 'Waldbyte', quickly converged on the most probable culprits: a fundamental disconnect in how weight data is handled between PrestaShop, the Mondial Relay module, and the Mondial Relay API.

  1. Inconsistent Weight Units: PrestaShop can be configured for kilograms or grams. Mondial Relay's API almost exclusively expects weight in grams (as an integer). If there's a mismatch at any point – PrestaShop storing in kg, the module converting incorrectly, or the API expecting grams when it receives kg – an error will occur.
  2. Data Formatting Discrepancies: Even if the unit is correct, the *format* can be wrong. The API might expect an integer (e.g., 1600) but receive a float (e.g., 1.600 or 1,600). Decimal separators (point vs. comma) can also cause issues, especially in international contexts.
  3. Module-Specific Logic & Bugs: Sometimes, the module itself introduces complexities. It might perform internal recalculations, conversions, or apply specific data types (e.g., forcing a float when an integer is needed) just before sending the data to the API. A known issue in Mondial Relay module 4.3.1, for instance, involved weight recalculation during relay point address creation, as pointed out by 'GekkodeFR'.

Your Actionable Troubleshooting Guide

To effectively tackle the "API 20: Poids du colis incorrect" error, follow these systematic steps:

Step 1: Verify PrestaShop & Product Configuration

  • PrestaShop Default Weight Unit: Navigate to Shop Parameters > General > Localization > Units. Ensure your default weight unit is set to grams (g). Save changes.
  • Product Weights: Double-check individual product pages. Ensure all product weights are entered in grams (e.g., 1600 for 1.6 kg). If you changed the default unit, you might need to re-save products or run a mass update if you have many.
  • Order Weight: Confirm that the total weight displayed for the problematic order in the PrestaShop back office is accurate and in grams.

Step 2: Scrutinize Mondial Relay Module Settings

  • Module Weight Unit: Go to your Mondial Relay module configuration. Look for any settings related to "Default weight unit," "Weight format," or "Unit conversion." Explicitly set it to grams or ensure no conflicting conversions are active.
  • Test with Rounded Weights: As 'Alexandre Carette' suggested, try generating a label for a test order with a simple, rounded integer weight (e.g., 1500g or 2000g). This helps rule out decimal formatting issues.

Step 3: Deep Dive into Code (For Developers or Advanced Users)

If the above steps don't resolve the issue, the problem likely lies in how the module processes and sends the weight to the API. This requires code inspection:

  • Identify API Call Point: Locate the file responsible for making the API call to Mondial Relay. This is often found in the module's main directory (e.g., mondialrelay.php, carrier.php, or within a dedicated service class).
  • Inspect Weight Variable: Just before the API request is sent, use debugging techniques (e.g., error_log(print_r($weight_variable, true)); or Xdebug) to inspect the exact value and data type of the weight variable being transmitted. Look for explicit type casting like (float) or (int), or formatting functions like number_format() or str_replace().
    // Example of what to look for in the module's code
    $parcelWeight = (float)$order->getTotalWeight(); // Could be forcing float
    $parcelWeight = number_format($parcelWeight, 0, '', ''); // Or formatting
    
    // Debugging example just before API call
    error_log('Mondial Relay API Weight: ' . var_export($parcelWeight, true));
    // Then check your PrestaShop /var/logs/prod/ or /dev/ logs
    
  • Check for Known Bugs: 'GekkodeFR' pointed to a potential bug in version 4.3.1 related to SelectRelayActions.php. Search the PrestaShop forums or the module's GitHub repository for patches or community fixes related to your specific module version.
A developer's screen showing PHP code with debugging statements, highlighting a weight variable before an API call.
Illustration 2: Debugging PHP code to inspect the exact weight value sent to the Mondial Relay API.

Step 4: API Interaction & Logs

  • Mondial Relay API Documentation: Consult Mondial Relay's official API documentation (if publicly available or provided by the module developer) to confirm the exact expected format for parcel weight (e.g., integer in grams, no decimals).
  • Module/Server Logs: While direct API logs might not be accessible, check your PrestaShop logs (/var/logs/prod/ or /var/logs/dev/) and server error logs for any additional clues beyond the "API 20" message.

Step 5: Cache & Environment

  • Clear All Caches: After making any changes, always clear PrestaShop's cache (Advanced Parameters > Performance > Clear Cache), your browser cache, and any server-side caches (e.g., Varnish, Redis) you might be using.
  • Test on Staging: If you're making code changes, always perform them on a staging environment first to avoid disrupting your live store.

When All Else Fails: Seek Expert Help

If you've exhausted all these troubleshooting steps and the "API 20: Poids du colis incorrect" error persists, it might be time to call in the experts. Complex module integrations, especially those involving external APIs, can have subtle issues that require deep technical knowledge of both PrestaShop and PHP development.

At Migrate My Shop, we specialize in PrestaShop migrations and complex module integrations. Our team of developers can quickly diagnose and resolve such issues, ensuring your e-commerce operations run smoothly. Don't let a shipping error hold back your business – sometimes, a fresh pair of expert eyes is all it takes.

Share:

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools