Colissimo Labels, Pickup Points & Tracking (OpenCart 4)

Overview

Ship with Colissimo (La Poste) from OpenCart 4.1. The extension integrates with the Colissimo web services using your own Colissimo contract: customers choose home delivery or a pickup point at checkout, you create the label (with its CN23 customs data when needed) from the order page, and the parcel status comes back to the order.

What it does

• Three checkout methods. Home delivery without signature (DOM, COM to Overseas France), home delivery with signature (DOS, CDS) and pickup point (HD: post office, Pickup shop or locker), each with your own price (flat or by weight, free from an order value, weight limit up to 30 kg, delivery countries, tax class, geo zone).
• Pickup point picker. Below the pickup method the customer opens the official Colissimo map (with your web services application key) or a built-in list of points near the delivery address. The browser only reports the point identifier; the shop looks it up again at Colissimo for the delivery country and the parcel weight and keeps Colissimo's answer. At checkout no order is created without a valid point, and a pickup delivery in France needs a French mobile number (Colissimo sends the pickup code by SMS).
• Labels. From the Colissimo tab of the order or automatically at an order status: PDF (10x15 or A4) or ZPL (203 / 300 dpi), optional insurance, box size, deposit date in Paris time.
• CN23 customs data. For Overseas France, countries outside the EU, Andorra and the special EU tax zones (Canary Islands, Ceuta, Melilla, Mount Athos, Aland, Heligoland, Busingen, Livigno, Campione): one article per order line with the net unit price converted to EUR, quantity, weight, HS code and origin; EORI number; shipping cost; the CN23 file to download (or printed on the label).
• Return labels. Colissimo Return France (CORE) from the order page; Colissimo can e-mail the label link to the customer.
• Tracking. The cron run reads the Colissimo timeline of open parcels; the tracking link goes to the order history and a delivered parcel can move the order to a status of your choice.
• Check-only mode. Colissimo has no test system: in check-only mode every label request goes to Colissimo's data control and nothing is created.
• Never two labels. The request is saved with its customer reference before it is sent. If Colissimo does not answer, nothing is sent again: you adopt the parcel number found in the Colissimo Box, or confirm that nothing was created.
• Safe by default. Password, application key and widget token stored encrypted; automatic calls paused when Colissimo refuses the credentials (30000) and for one hour after a login block (30013); personal data masked in the log; data kept across updates. Events and cron only: no OCMOD, no core edits.

Requirements

• OpenCart 4.1.0.x, PHP 8.1 to 8.3 (as OpenCart 4.1 requires) with cURL and OpenSSL.
• A Colissimo contract with web services access: the web services application key (Colissimo Box, Applications) or the contract number and Colissimo Box password. Not included. The pickup point map needs the application key.
• For customs data and insurance: the euro (EUR) in System > Localisation > Currencies with its rate.

Not in 1.0

Cash on delivery, DDP, the hand-over slip, mailbox pickup, international return labels, Colissimo Flash, several Colissimo contracts in one shop, labels of many orders in one file. OpenCart 3 is not supported (no OpenCart 3 package is shipped).

Colissimo and La Poste are trademarks of their owner. This extension is independent software by Kavio Labs that integrates with the Colissimo web services; it is not affiliated with or endorsed by La Poste.

Installation

1. Install the extension. Extensions > Installer > Upload kv_colissimo.ocmod.zip, then Install.
2. Install the shipping method. Extensions > Extensions > Shipping > Colissimo Labels, Pickup Points & Tracking > Install, then Edit.
3. Connection tab. Leave the mode on "Check only". Enter the web services application key, or the contract number and the Colissimo Box password. Enter the sender address (printed on every label and used for return labels) and, if you ship outside the EU, your EORI number.
4. Save and test. The shop sends a minimal parcel to Colissimo's data control (nothing is created) and, with an application key, fetches a widget token.
5. Checkout tab. Switch the extension on and enter a price (or weight table) for each method you offer, and their delivery countries.
6. Labels & customs tab. Label format, customs nature, origin country and default HS code, the order statuses.
7. Telephone field. Pickup points in France need the customer's mobile number (Colissimo sends the pickup code by SMS). Switch on Telephone Display and Telephone Required in System > Settings > Option (both are off on a new OpenCart 4.1). While the field is hidden the pickup point method is not offered for France.
8. Euro rate. Add EUR to System > Localisation > Currencies if your default currency is not the euro.
9. Cron. Make sure the OpenCart cron runs (*/10 * * * * php /path/to/cron.php); the extension adds a job that runs at every cron call and does nothing when nothing is due. You can also call the secret cron address shown on the Labels tab.
10. Test. Place an order with a French address, choose a pickup point, then press "Check with Colissimo" on the Colissimo tab of the order: Colissimo validates the data without creating a label.
11. Go live. Switch the mode to "Live" and save. The next label request creates a real label (a label is invoiced only when it is scanned).

Updating: upload the new package and install it again. Your settings, connection, labels and points are kept (OpenCart 4 updates are uninstall + install; the extension never drops its tables on uninstall).

Configuration

Pause after a refusal. When Colissimo refuses the credentials (shipping service 30000, pickup point service 201, tracking 202 / 401 / 403), automatic calls (cron, labels at a status, checkout searches) stop until you save or test the connection again. After a login block (30013) every call stops for one hour, and the connection test refuses to call before then: another attempt would extend the block.

Usage

Colissimo tab of an order. Shown for orders with a Colissimo method (or with a Colissimo label or point).

• Check with Colissimo (check-only mode): Colissimo validates the label data; nothing is created.
• Create label (live mode): the label opens with Label; the parcel number links to the La Poste tracking page. CN23 downloads the customs declaration when the parcel needs one.
• Set point: type a pickup point identifier to change the point of the order; it is looked up at Colissimo in the delivery country.
• Track: reads the Colissimo timeline now.
• Cancel: cancels the label in the store, before the hand-over. The Colissimo web services have no cancel operation; a label that is never scanned is not invoiced.
• Create return label: Colissimo Return France, from the customer to your sender address (deliveries in metropolitan France). Tick the box to let Colissimo e-mail the label link to the customer.

Result unknown. If Colissimo does not answer a label request, the label is marked "Result unknown" and nothing is sent again. Look for the customer reference shown (for example O1024-7) in the Colissimo Box. If you find the parcel, type its number and press Adopt: the number is checked with the tracking service and the label is fetched again. If there is none, press Nothing was created to allow a new label. A return label request with an unknown result (reference R1024-7) is cleared the same way.

Automatic labels. With "Create the label at status" set, the label is created after the order reaches that status (after the page answered, so customers never wait for Colissimo). Failures are shown on the Colissimo tab; safe ones are retried by the cron run.

Shipments tab of the settings lists the latest labels with their state.

Developer notes

Extension code kv_colissimo (OpenCart 4.1), namespace KavioLabs\KvColissimo (shared core in system/library/), shipping codes kv_colissimo.home (DOM / COM), kv_colissimo.signature (DOS / CDS) and kv_colissimo.pickup (HD), licence id kv_oc_colissimo. Port of the CS-Cart add-on kv_colissimo 1.0.0 with all fixes of its release audit (research/quality/AUDIT-2026-11-07-colissimo.md): EUR conversion of customs and insurance values, CN23 for Andorra and the special EU tax zones, tracking 401 / 403 never retried, account pause after 30000 / 30013. PHP 8.1 to 8.3 (OpenCart 4.1 requires 8.1); the code keeps PHP 7.4 syntax.

Services (base https://ws.colissimo.fr)

Credentials: the application key (header apiKey, body apikey / apiKey for pickup points and tracking), else the contract number and password in the body. The User-Agent is KavioLabs-kv_colissimo/1.0 (OpenCart).

Request fields

Field limits of SLS II.5.2 (company and lines 35, last name 35, first name 29, city 35, orderNumber 30, senderParcelRef 17, addresseeParcelRef 15, instructions 35, article 64): text is transliterated first, then cut with mb_substr (Parcel::clean). Phones: French numbers as 0NNNNNNNNN, others as +<dial><number>; the dummy numbers of the document are refused; a mobile number goes to mobileNumber. Weight in kg with two decimals (0.01 to 30). Amounts in euro cents. depositDate and the pickup search date in Europe/Paris (error 30002). orderNumber = O<order>-<record> (R for returns): the record is written before the call, so the reference is known even when the answer is lost.

CN23 (Customs): for Overseas France, outside the EU, Andorra, and the special EU tax zones by postal code (Parcel::needsCn23). One article per order line: order_product.price (OpenCart keeps it without tax, in the default currency) converted to EUR with value(EUR) / value(default) of the currency table (OpenCart's own Currency::convert rule); HS code from a product attribute whose name contains "HS code" (or similar), else the default; artref = the model. transportationAmount / totalAmount = the shipping total of the order in EUR cents; returnTypeChoice outside Overseas France; EORI as customField.

Idempotency and pauses

• One per-order database lock (GET_LOCK) around create, adopt, "nothing was created", return label and cancel. A busy order answers "try again" (the cron queue retries in minutes).
• The shipment row (state W) is written before generateLabel. A timeout or a 5xx makes it U (result unknown); it is never sent again automatically. A row still W when the lock is taken again belongs to a request that died: it becomes U too.
• Refusals (HTTP 4xx, ERROR messages in an HTTP 200 answer) delete the pending row.
• Client\Api::trip() maps SLS 30000, pickup 201 and tracking 202 / 401 / 403 to a B pause (until the connection is saved or tested again) and SLS 30013 to an L pause (one hour; saving does not lift it, the connection test does not call). Client::api() returns null while paused, so cron, labels at a status and checkout searches make no call.

Events

Cron: OpenCart cron job kv_colissimo (every call) and the secret address index.php?route=extension/kv_colissimo/shipping/kv_colissimo.cron&key=.... Storefront AJAX (POST with the session token of the checkout page): .widget, .points, .point. No flow leaves the shop, so the OpenCart 4.1 SameSite=Strict session cookie is never lost.

Tables

kv_colissimo_accounts (sealed password, key and widget token), _shipments (C created, T in transit, D delivered, P problem, X cancelled, W pending, U unknown), _points, _jobs, _log. Uninstall keeps every table and the settings snapshot (Keep): OpenCart 4 updates are uninstall + install.

Tests

php81 tests/unit.php / php83 tests/unit.php (throw-away MariaDB database, scripted transport, every body validated against tests/fixtures/official/sls-openapi.json); STORE=oc41b KV_AGENT=<name> node tests/e2e.js --shots against tests/mock-server/server.php (started on 127.0.0.1; the test refuses to run unless the store's hidden base_url setting is a loopback address). Never point a test at ws.colissimo.fr: wrong credentials lock the login (30013).

Conformance with the Colissimo documents

What was checked, against what, and what is still open. Colissimo gives no test accounts: the extension was built from the published documents and the public files of the services, and tested against a local stand-in that follows them, never against a Colissimo contract.

Open points for a real contract (same as the CS-Cart add-on): key-only authentication of generateLabel without contractNumber / password, the answer body of getLabel, the live Content-ID of the CN23 part (cn23 per the OpenAPI description), the widget callback fields (identifiant, reseau), the eligible overseas territories for COM / CDS, postal code lengths outside France, foreign mobile numbers longer than the AN10..12 of the document. Not implemented: cash on delivery, DDP, the hand-over slip, mailbox pickup, international returns, Colissimo Flash.

Logo. The Colissimo communication kit offers the logo to merchants for their own merchant site and gives no procedure for software vendors, so the extension and its product pages use the text "Colissimo" only. The widget shows its own logo because it is La Poste's own tool.

FAQ

Are the checkout prices live Colissimo prices?

No. The Colissimo web services have no rate operation; you enter your prices per method.

Which countries?

Home delivery to the countries you list (Overseas France gets COM / CDS, parcels outside the EU a CN23); pickup points in the countries you list where your contract offers them (France by default). Your Colissimo contract decides where Colissimo delivers.

Is there a map at checkout?

Yes, the official Colissimo pickup point map when you enter the web services application key; otherwise, and whenever the map cannot load, a list of points near the delivery address.

Why is the pickup point method missing for France?

The telephone field is hidden in your store. Switch on Telephone Display and Telephone Required in System > Settings > Option: Colissimo sends the pickup code to the customer's mobile number.

Can I test without creating labels?

Yes: check-only mode sends every request to Colissimo's data control and creates nothing. Colissimo has no test system.

Can a label be created twice?

No. The request is saved before it is sent; after a lost answer nothing is sent again until you adopt the parcel or confirm that nothing was created.

Does it fill in the CN23?

Yes, from the order lines: net unit price in EUR, quantity, weight, HS code (product attribute "HS code" or your default), origin, EORI.

Thermal printers?

Yes, ZPL 10x15 at 203 or 300 dpi.

Cash on delivery?

No, not in 1.0.

Does any page leave the shop?

No. The pickup point map runs in a frame on the checkout page; there is no payment or return redirect. Only the tracking link opens the La Poste tracking page.

OCMOD?

No. Events and cron only.

OpenCart 3?

No, OpenCart 4.1 only.

What did you test?

Tested on OpenCart 4.1.0.4 (PHP 8.3) against a local stand-in built from the Colissimo documents and the OpenAPI file of the shipping web service, not against a Colissimo contract; unit tests on PHP 8.1 and 8.3.

Are you affiliated with La Poste?

No. Colissimo and La Poste are trademarks of their owner.