How to Integrate the Colissimo Shipping API

What Colissimo's SLS Web Service Is and Why Direct Integration Gets Tricky

If you ship into or out of France in any volume, you've already dealt with Colissimo. It's La Poste's parcel arm, and building a direct Colissimo API integration means working with what La Poste calls SLS, Simple Label Solution. The Colissimo SLS Web Service allows users to generate shipping labels and customs documents for parcels, and automatically transmit electronic announcements to La Poste - Colissimo. That's the entire integration surface: one web service, two transport modes, and a contract gate that trips up more teams than the actual coding does.

SLS runs in both SOAP and REST. The response format can be delivered as REST/JSON+XOP, and La Poste has been actively pushing the REST/JSON path forward with version updates through 2025. The documentation itself changes often. As of the latest update in November 2025, La Poste added a label customization feature available from WS version 3.0 and fixed WS access URLs, which tells you something important: this isn't a "build it once and forget it" API. It's versioned, actively maintained, and worth monitoring the same way you'd monitor any carrier that ships breaking changes without much warning.

What You Need Before You Start

You need a signed Colissimo Business contract before you write a single line of code. A personal or standard La Poste account will not authenticate against SLS. The service requires you to use your La Poste - Colissimo contract number and your password, which you may receive by email when starting your contract or by request from your usual La Poste - Colissimo sales contact. That same login also does double duty: the login credentials also enable you to access your customer web account. Before you touch production, confirm you have the following:

• A signed Business/Pro contract with your product codes enabled (DOM, Point Retrait, international, etc.), issued by your La Poste sales contact.
• Your contractNumber and password, or the newer apiKey if your account manager has already migrated you.
• Access to the SLS sandbox environment, which allows developers to test the integration of the SLS Web service and Document without impacting the production environment.
• The current SLS technical documentation, since parameter names and error codes change between releases, and the Redoc SLS API reference is the version La Poste treats as canonical.

One documentation note worth flagging early: as of March 2025 La Poste added recommendations that the contract number and password fields no longer be used in new integrations, which is your first signal that apiKey is the intended long-term auth method, not a side option.

Step-by-Step: Connecting to the Colissimo SLS Web Service

1. Request Business Pro API access and confirm your product codes. Talk to your La Poste Entreprises account manager and get written confirmation of which product codes are enabled on your contract before you start building. A missing product code produces a confusing error later, not an obvious one at setup.
2. Choose SOAP or REST as your transport. Both are documented in the same technical guide, but new features land on REST first. If you're starting from zero, build against REST/JSON; if you're maintaining a legacy integration, know that SOAP still works but is not where La Poste's active development is going.
3. Point your first calls at the sandbox environment. All shippers can carry out shipping label creation tests without being invoiced, though it's worth informing the sales contact beforehand. Confirm your calls return valid label responses before anything touches production.
4. Build the generateLabel request. At minimum you're mapping your contract credentials, a letter.service.productCode field (this is where DOM or another product code goes), a parcel.weight value, and full sender and addressee address blocks including company name, address lines, country code, city and zip. Get the field order right, because the WSDL is strict about it: the parameters must be entered in the order defined in the wsdl, otherwise an "unmarshalling error" will be returned.
5. Switch from login/password headers to apiKey. This is the step most existing integration guides skip, and it's the one that will bite you later if you don't do it now. The login header parameter is deprecated in current SLS documentation; you're instructed to use apiKey instead as described in the API authentication section. To generate one, you connect to the Cbox with your login details, then go to your profile and generate the key from there. Once you have it, you include it in the header of all your requests, in the format apikey: followed by your key value.
6. Parse the response correctly. The SLS web service uses MTOM technology, meaning the label is attached in MIME format to the web service's response, not embedded as a plain field. La Poste is explicit that you should not try to shortcut this: it's strongly recommended to use a library to retrieve the attachment, and you should avoid reading the attachment directly from the raw response by position, since technical fields can shift between framework versions.
7. Cut over to production and run one real shipment. Swap sandbox URLs for production, and generate a single low-value shipment before scaling volume. Production behaves differently from sandbox in one concrete way: shippers will be invoiced for any label scanned during production, so your first real label is also your first real cost, which is a useful forcing function to actually verify the workflow end to end rather than assume it's fine.

How You Know the Integration Is Working

Success looks like a clean generateLabel response with a valid parcel number and an unblocked attachment, tested first in sandbox where nothing gets billed and nothing hits Colissimo's live network. Once you've moved to production, the real confirmation is operational: the label prints correctly, the parcel number tracks through Colissimo's system, and you get invoiced only when the label is scanned during production, not before. If you're seeing charges appear before a parcel physically moves, or no charges appear at all after weeks of "production" shipments, you're likely still pointed at the wrong environment or product code.

Failure Mode: Authentication Breaks After a Password or Key Change

This is the single most common support ticket for direct Colissimo integrations, and it's entirely avoidable once you know the pattern. Colissimo treats your customer portal login and your webservice credentials as linked but not automatically synced. If you change your password in the customer account, you must also change it when invoking the web service, otherwise access to the web service will be denied. The same rule applies to the newer apiKey: if you change your Web Services application key in the customer area, you must also change it in the web service invocation, otherwise access to the web service will be denied.

When this happens, you'll see it immediately rather than as a slow degradation. In the event of an authentication error, the API returns a status code 30000 with a message describing the nature of the error. Build a specific handler for that code rather than lumping it in with generic 4xx/5xx retry logic, because retrying an auth failure just burns your rate limit without fixing anything.

The bigger structural risk is the deprecation itself. Anything still hardcoded to login/password headers is technically working today but is explicitly flagged as legacy in current documentation. Treat any credential rotation, portal password or apiKey, as a two-system change: update the portal, then immediately update the config your integration reads from, and test a single call before walking away.

Direct Integration vs. a Connectivity Layer

If Colissimo is your only or dominant carrier, maintaining this SOAP/REST/apiKey logic in-house is entirely reasonable. The API surface is narrow enough that one engineer can own it. The complication shows up when Colissimo is one of fifteen or thirty carriers, and every one of them has its own version of this same problem: different auth models, different deprecation timelines, different field-ordering quirks.

Platforms like Cargoson maintain the Colissimo connector natively, exposing it through their own services endpoint that returns the Colissimo services available on a company account, and books shipments to the carrier's system in real time with labels generated immediately. That's the trade-off in one sentence: you give up direct control over the SOAP/REST plumbing, and in exchange you stop being the one who finds out about an apiKey deprecation the hard way.

Next Steps

Before your next sprint planning, pull up every carrier integration your team maintains and check which ones still authenticate with login/password headers instead of a rotating key or token. Colissimo isn't unique in making this switch, and it won't be the last carrier to do it. Start with whichever integration handles your highest shipment volume, confirm it's on the current auth method, and only then move down the list.