Connecter Sendcloud à votre logiciel métier : API v3, webhooks et organisation des expéditions

Pourquoi passer par Sendcloud plutôt que par chaque transporteur ?

Sendcloud est une plateforme d'expédition qui place une seule API entre votre logiciel et plusieurs transporteurs : votre code parle à Sendcloud, qui parle à chaque transporteur. Sa page consacrée à l'API annonce plus de 170 transporteurs locaux et internationaux.

Le calcul est simple. Un grossiste qui confie ses colis lourds, ses envois express et ses petits paquets à trois transporteurs différents écrit une intégration au lieu de trois. En contrepartie, il ajoute un intermédiaire et un abonnement, et certaines fonctions propres à un transporteur peuvent manquer. Une entreprise qui n'expédie qu'avec un seul transporteur, sous un contrat négocié, a souvent intérêt à s'y relier directement : voir nos pages Chronopost et Colissimo.

Que couvre l'API v3 de Sendcloud ?

L'API de Sendcloud est une API REST : appels en HTTPS avec les verbes GET, POST, PATCH ou PUT, échanges en JSON, et aucun kit de développement imposé, selon sa documentation. L'index de la documentation développeur liste les ressources de la version 3 :

Pour les expéditions, Sendcloud distingue deux modes. La création synchrone, conseillée pour les petits volumes et les tests, renvoie aussitôt le résultat de l'annonce et le fichier d'étiquette, jusqu'à 15 colis par expédition. La création asynchrone, recommandée en production à fort volume et pour le multicolis, accepte jusqu'à 50 colis mais ne confirme pas l'annonce : il faut relire l'expédition ensuite. Les retours disposent de leur propre API, Returns, qui permet aussi de valider un retour avant de le créer.

Clés, OAuth 2.0 et limites d'appels publiées

Chaque connexion à Sendcloud repose sur une intégration « Sendcloud API » ajoutée dans les paramètres du compte, qui génère une clé publique et une clé secrète. Deux modes d'authentification sont documentés :

• Basic : la clé publique sert d'identifiant, la clé secrète de mot de passe.
• OAuth 2.0 (flux client credentials) : les clés servent à obtenir un jeton valable une heure, à mettre en cache et à renouveler peu avant son expiration. Une option de l'intégration peut imposer OAuth 2.0 et refuser l'authentification Basic.

Le centre d'aide de Sendcloud recommande de copier les clés et de les conserver en lieu sûr : une clé perdue se régénère, et la connexion doit alors être reconfigurée.

Au-delà, l'API répond HTTP 429. Conséquence concrète : un ERP qui veut créer 300 expéditions d'un coup à l'ouverture de l'entrepôt y passera environ trois minutes. L'intégration doit donc mettre les demandes en file et les étaler, plutôt que d'échouer au 101e appel.

Webhooks : être prévenu sans interroger l'API

Un webhook Sendcloud prévient votre logiciel dès qu'un colis change de statut, sans qu'il ait à interroger l'API en boucle (le principe est décrit dans notre définition du webhook). La documentation de la version 3 liste aussi des événements sur les retours créés et sur les intégrations connectées, modifiées ou supprimées.

• Activation : dans le panneau Sendcloud, intégration par intégration, avec l'adresse de réception et un bouton d'envoi de test.
• Signature : chaque envoi porte l'en-tête Sendcloud-Signature, une empreinte HMAC SHA-256 calculée sur le corps brut de la requête avec la clé secrète ou une clé de signature dédiée. Le récepteur la recalcule et rejette tout écart.
• Échecs : Sendcloud relance jusqu'à 10 fois, d'abord après 5 minutes puis à intervalles croissants plafonnés à 1 heure, avant de consigner l'échec dans son journal des problèmes de connexion.
• Ordre : les envois peuvent arriver dans le désordre ; le champ timestamp désigne la mise à jour la plus récente.
• Retours : les mises à jour d'un colis retour n'arrivent que si l'envoi aller a été créé par l'intégration API.

Tester sans payer d'étiquettes

La documentation de Sendcloud ne décrit pas d'environnement de test séparé : on teste sur son compte réel, par l'une de deux méthodes.

1. L'option « Unstamped letter », code sendcloud:letter pour un envoi et sendcloud:letterreturn pour un retour : les étiquettes créées avec ces options ne sont pas facturées, selon la documentation développeur. La FAQ de la page tarifaire, relevée en octobre 2026, évoque toutefois une limite de 50 étiquettes de ce type au-delà de laquelle elles sont facturées : à faire confirmer pour votre compte.
2. Créer une vraie étiquette puis l'annuler dans le délai prévu, quand un transporteur précis doit être testé. Risque signalé par Sendcloud : certains transporteurs refusent l'annulation une fois l'étiquette créée ou manifestée, et elle reste alors facturée.

Deux précautions complètent ces tests. Un code HTTP 200 ne prouve pas que l'annonce au transporteur a réussi : il faut lire l'objet errors et le statut de l'expédition ; une expédition au statut « Announcement Failed » n'est pas facturée. Et avant la première étiquette, le compte doit avoir ses adresses d'expédition, des transporteurs activés et un moyen de paiement.

Quatre organisations d'expédition reliées par l'API

• L'ERP dépose, l'entrepôt expédie. Un négociant en fournitures de bureau garde la saisie des commandes dans son ERP. Toutes les dix minutes, l'intégration crée ou met à jour les commandes par lots dans Sendcloud ; les préparateurs travaillent dans l'interface Sendcloud ; le webhook de statut renvoie le numéro de suivi vers l'ERP.
• Le WMS édite lui-même. Un fabricant de mobilier dont l'entrepôt a son propre logiciel crée l'expédition en mode asynchrone à la fin du colisage, jusqu'à 50 colis par expédition (moins chez certains transporteurs), relit le résultat, puis récupère chaque étiquette par l'identifiant de colis et l'imprime au quai.
• Le service client voit tout. Le webhook de changement de statut alimente la fiche commande : le conseiller répond sans ouvrir un autre outil. Pour un envoi fait hors Sendcloud, l'API de suivi accepte la création d'un colis externe.
• Le retour remet en stock. Le SAV accepte un retour dans le logiciel métier, qui le crée par l'API Returns ; à la réception, l'article revient dans le stock du bon dépôt, logique détaillée dans notre page sur la gestion de stock multi-sites.

Intégration native Sendcloud ou connexion développée ?

La page Intégrations d'un compte Sendcloud liste les connexions disponibles, dont « Sendcloud API ». Si votre boutique y figure déjà, testez cette connexion native avant d'envisager un développement. Vérifiez aussi la formule : selon la page tarifaire relevée en octobre 2026, la formule Free facture chaque étiquette générée, et utiliser son propre contrat transporteur demande une formule payante.

Une connexion développée se justifie quand les commandes viennent d'un ERP, d'un WMS ou d'un logiciel métier sans intégration native, quand les retours doivent agir sur le stock, quand les règles de choix du transporteur dépendent de données que seul votre logiciel connaît (client, marge, dépôt), ou quand le volume impose d'étaler finement les écritures.

Ce que YMHB Web met en place autour de Sendcloud

Nous construisons un service d'intégration à côté de vos logiciels, avec une file d'attente qui respecte les limites d'appels, une vérification systématique de la signature des webhooks, une table qui relie chaque commande à son expédition Sendcloud et un journal de chaque échange. Une interrogation de rattrapage reprend les statuts manqués si les dix relances d'un webhook ont échoué.

Les clés et l'intégration Sendcloud sont créées sur votre compte, le code est déposé chez vous et vous revient au paiement intégral, et notre documentation explique comment régénérer une clé ou ajouter un transporteur. Le cadrage des flux précède tout chiffrage, comme pour nos autres intégrations entre logiciels, avec un objectif : en finir avec les doubles saisies entre la gestion et l'expédition.