Connecter Colissimo à votre logiciel métier : étiquettes, retours et suivi par web services

Quel web service Colissimo pour quel besoin ?

Colissimo découpe son offre technique en web services spécialisés, un par moment de la vie du colis, présentés dans la rubrique « Outils et services » de son espace professionnel.

La même page précise que plusieurs de ces services exigent au minimum le protocole TLS 1.2 : un serveur ancien peut échouer avant même la première étiquette.

SLS, le web service d'affranchissement, méthode par méthode

SLS transforme une commande en colis Colissimo. Sa documentation technique, publiée par La Poste sur colissimo.fr, donne pour la version 3.1 une adresse REST et une adresse SOAP, et précise que ces adresses sont réservées aux offres entreprise.

Chaque appel précise un code produit (DOM et DOS pour le domicile sans ou avec signature, HD pour les livraisons hors domicile comme les points de retrait, etc.) et un format d'impression : PDF en 10 x 15 ou A4 pour une imprimante laser, ZPL pour les imprimantes Zebra, DPL pour les Datamax. La documentation fixe le poids maximal à 30 kg (ou au poids maximal accepté par le point de collecte), remplace les accents et signale une erreur pour les caractères non latins.

Clé d'API, mot de passe de contrat : comment s'authentifier ?

Le web service SLS s'authentifie par une clé de connexion. La documentation SLS indique qu'on l'obtient en se connectant à la Cbox, l'espace client Colissimo, avec son nom d'utilisateur et son mot de passe ; la clé accompagne ensuite chaque requête dans l'en-tête apikey, peut être régénérée à tout moment et n'a « pas de durée de vie limitée pour le moment ».

• Délégation : un logisticien ou une place de marché qui affranchit pour le compte d'un chargeur envoie sa propre clé et indique le compte affranchi dans le champ ACCOUNT_NUMBER.
• Suivi Timeline : sa spécification (version 2.6, décembre 2024) demande le numéro de contrat, fourni par La Poste Colissimo à l'ouverture du compte client, et un mot de passe.
• Transport : les appels se font en HTTPS, avec au minimum TLS 1.2 pour la plupart des web services Colissimo.

Une clé qui n'expire jamais reste valable si elle fuit : rangez-la dans un coffre de secrets et régénérez-la au départ de chaque prestataire.

Bac à sable et facturation : ce que Colissimo autorise en test

Colissimo fournit un bac à sable séparé de la production. Selon la documentation SLS, les étiquettes qu'il produit portent la mention « DEMO », un seul numéro de colis fictif est renvoyé (le code trafic suivi de 9999999) : ces étiquettes ne servent qu'aux essais.

• Tests gratuits : « Tout chargeur peut effectuer des tests de génération d'étiquettes d'affranchissement sans être facturé », écrit La Poste, qui demande d'en informer son commercial.
• Production facturée : toute étiquette générée, posée sur un colis et flashée en production est facturée au chargeur.
• Pas de test de charge : La Poste demande à ses clients de ne pas en effectuer.
• Validation des étiquettes : pour les étiquettes Colissimo Retour produites par le client, le Contrat Privilège de La Poste (édition de mars 2023) prévoit le respect d'un cahier des charges de La Poste et la validation d'un exemplaire type avant diffusion ; demandez à votre interlocuteur commercial ce qui s'applique à votre contrat.

Cinq automatismes Colissimo pour une PME

1. L'étiquette sort au poste d'emballage. Chez un vendeur de pièces de motoculture, le préparateur scanne le bon : le logiciel appelle generateLabel avec le poids pesé et le code produit, stocke le numéro de colis sur la commande et envoie le ZPL à l'imprimante thermique. La documentation SLS recommande ce format à partir de 1 000 colis par mois.
2. Le retour sans imprimante chez le client. Le SAV accepte un retour : generateToken produit un code sécurisé qui remplace l'étiquette retour, une fois le service activé dans l'onglet Retour de la Cbox. Variante : getListMailBoxPickingDates puis planPickup pour un enlèvement dans sa boîte aux lettres.
3. Le dépôt en un seul flashage. En fin de journée, generateBordereauByParcelsNumbers regroupe les colis du jour sur un bordereau de dépôt, que l'agent flashe une fois au lieu de scanner chaque colis.
4. La commande se clôt à la livraison. Une tâche interroge la méthode timelineCompany du suivi Timeline ; quand l'étape 5 est active et datée, le colis est livré et la commande se ferme. Les codes 105 (numéro de colis inconnu ou trop ancien) et 1000 (suivi indisponible ou erreur non prévue) déclenchent une nouvelle tentative plutôt qu'une alerte au client.
5. L'envoi vers l'outre-mer part avec ses papiers. Pour un colis vers la Réunion, generateLabel produit la CN23 avec l'étiquette ; le web service Documents reçoit les pièces de dédouanement.

Ce qui casse une intégration Colissimo en production

• Les adresses étrangères : un nom en caractères non latins provoque une erreur SLS. Le logiciel translittère ou bloque la commande avant l'appel, pas devant le carton.
• L'ordre des paramètres en SOAP : la spécification Timeline exige l'ordre défini dans le WSDL, faute de quoi le service renvoie une erreur de désérialisation (unmarshalling error).
• Les évolutions fréquentes : le journal des modifications de la documentation SLS compte plusieurs mises à jour en 2025 et en 2026, dont un code produit ajouté en 2026. Une veille et des tests rejoués avant chaque changement évitent les surprises.
• Les doublons : une commande ne doit produire qu'un numéro de colis. Pour réimprimer, on appelle getLabel, jamais un second generateLabel qui serait facturé si le colis part avec.
• Les colis hors limites : la documentation SLS plafonne le poids à 30 kg, ou moins selon le point de collecte ; mieux vaut le savoir dès la préparation.
• Les données personnelles : seuls les champs utiles à la livraison partent chez La Poste, et les journaux ont une durée de conservation définie, comme l'explique notre guide RGPD et logiciel métier.

Module Colissimo, Coliship ou intégration sur mesure ?

Commencez par l'existant. Colissimo propose des modules pour PrestaShop, Magento, Oxatis, WooCommerce et Shopify, qui affichent les points de retrait, éditent les étiquettes et intègrent le suivi ; Coliship, son outil d'affranchissement en ligne, couvre les envois en France, vers l'outre-mer et à l'international, retours compris. Une boutique qui prépare ses colis depuis son administration s'en contente souvent (voir nos pages WooCommerce et PrestaShop).

L'intégration développée se justifie quand les commandes viennent d'un ERP ou d'un logiciel métier, quand l'étiquette doit sortir au scan du bon de préparation, quand les retours doivent remettre automatiquement les articles en stock, ou quand Colissimo cohabite avec un express comme Chronopost. Avec trois transporteurs ou plus, une plateforme comme Sendcloud mérite d'être comparée à des connexions directes.

Ce que YMHB Web met en place pour Colissimo

Nous appliquons à Colissimo la méthode éprouvée sur les services web Chronopost d'APARO : un service d'intégration séparé de vos logiciels, une table qui relie chaque commande à son numéro de colis, une file d'attente qui rejoue les appels échoués et un journal consultable de chaque échange. La clé d'API et le contrat restent au nom de votre entreprise, le code vous appartient au paiement intégral, et la documentation décrit les flux, les codes produit retenus et la marche à suivre quand La Poste modifie son web service. Le périmètre est fixé au cadrage, avant tout chiffrage, comme pour nos autres intégrations entre logiciels.