FAQ - API Sendcloud

Sujet : Dans cet article, nous répondons aux questions les plus fréquemment posées concernant les intégrations personnalisées de boutique utilisant les API Sendcloud.

Quelles sont les limites de taux (rate limits) ?

Limites de taux

Notre API applique des limites de taux qui restreignent le nombre de requêtes pouvant être effectuées par minute. Veuillez noter que des limites différentes s’appliquent aux endpoints liés à l’expédition.

• Requêtes sûres (GET) : 1000 requêtes par minute
• Requêtes non sûres (POST/PATCH/PUT/DELETE) : 100 requêtes par minute.

Rafale maximale (maximum burst)

Les endpoints considérés comme non sûrs disposent d’une capacité de rafale définie, correspondant au nombre maximal de requêtes simultanées que l’API peut traiter. Cela permet une augmentation temporaire du taux de requêtes afin de gérer de courtes périodes de trafic élevé, sans dépasser les limites globales.

• Requêtes non sûres (POST/PATCH/PUT/DELETE) : 15 requêtes par seconde.

Pour en savoir plus sur les limites de taux, consultez notre documentation développeur.

Ces informations peuvent être modifiées à la discrétion de Sendcloud.

Je souhaite créer des étiquettes immédiatement lors de la création d’un envoi via l’API. Comment faire ?

Pour créer des envois et des étiquettes d’expédition en un seul appel API, utilisez l’endpoint synchrone de l’ API Shipments ou de l’ API Ship an Order. L’étiquette sera automatiquement renvoyée dans la réponse, dans le champ data.parcels.label_file. Cette fonctionnalité est uniquement disponible pour les envois Single Collo (envoi composé d’un seul colis).

Comment garantir l’idempotence des commandes/envois que j’importe ou crée dans Sendcloud ?

Dans le contexte des API, l’idempotence signifie que plusieurs requêtes identiques produisent le même effet qu’une seule requête. Cela permet d’éviter les erreurs utilisateur et, dans le cas des API Sendcloud, la duplication des commandes dans notre système. Quatre endpoints visent à être idempotents :

• Tous les endpoints POST de l’ API Shipments
  Utilisez le champ external_reference_id pour garantir l’idempotence.

Puis-je utiliser des règles d’expédition lors de la création d’envois via l’API ?

Les règles d’expédition s’appliqueront aux envois créés via l’API, à condition d’utiliser les endpoints synchrones ou asynchrones « Create a shipment with rules and/or defaults ». Nous vous recommandons d’utiliser l’option d’expédition « Lettre non affranchie » ("shipping_option_code": "sendcloud:letter") si vous souhaitez que les règles d’expédition s’appliquent correctement. Cela vous permettra de contourner l’objet obligatoire ship_with, et toutes les règles configurées influençant la sélection de l’option d’expédition seront correctement appliquées à votre colis.

Puis-je tester l’API sans être facturé pour les étiquettes créées ?

Vous pouvez utiliser l’option d’expédition Sendcloud « Lettre non affranchie » ("shipping_option_code": "sendcloud:letter") pour créer vos envois. Cela vous permet de tester l’API sans risquer d’être facturé pour les étiquettes créées.

Veuillez noter qu’il n’est pas possible d’utiliser cette option d’expédition pour tester la création d’étiquettes de retour. Pour tester des étiquettes de retour, utilisez une option d’expédition prenant en charge les demandes d’annulation depuis Sendcloud et annulez l’étiquette avant 23h59 le jour de sa création. Consultez notre documentation sur les étiquettes de test pour plus d’informations.

Je reçois le message d’erreur « User is not allowed to announce ». Que se passe-t-il ?

Assurez-vous d’avoir suivi toutes les étapes de configuration de base du compte et d’avoir activé un mode de paiement par prélèvement automatique. Consultez : Commencer avec Sendcloud.

Puis-je voir toutes mes options d’expédition via l’API lorsque je connecte un contrat transporteur direct ?

Oui — si vous avez connecté votre propre contrat transporteur, vous pourrez récupérer vos propres options d’expédition ainsi que les options Sendcloud en effectuant une requête vers l’endpoint Shipping options API. Veuillez noter que les tarifs de votre contrat ne seront pas récupérés sauf si vous avez importé vos propres tarifs transporteur.

Puis-je consulter mes propres tarifs issus de mes contrats transporteur directs via l’API pour comparer les méthodes ?

Oui, si vous avez importé vos propres tarifs dans votre compte Sendcloud en suivant les étapes décrites dans cet article.

Je reçois le message d’erreur « No shipping option could be found for[…] » lors de la création d’un envoi via l’API. Que se passe-t-il ?

Il est probable que le shipping_option_code utilisé corresponde à une option d’expédition qui ne prend pas en charge l’envoi vers ou depuis l’adresse indiquée (par exemple, une méthode nationale pour un envoi international). Il est également possible que vous utilisiez une option de retour pour un envoi sortant, ou inversement. Vous pouvez utiliser l’ endpoint Shipping options afin de trouver une option adaptée à votre envoi selon les paramètres définis dans votre requête.

L’API prend-elle en charge l’importation de champs de notes ou remarques dans les commandes ?

Oui. Par exemple, cela peut être utilisé pour ajouter des notes aux commandes, telles que « Merci d’emballer cet article comme un cadeau avant l’expédition ». Ces notes apparaîtront également sur les bons de livraison ou listes de picking si vous utilisez Pack & Go.

J’ai créé un rapport via l’API, mais mon fichier CSV est vide. Que se passe-t-il ?

Veuillez vérifier le filtre direction lors de la création de votre requête vers l’endpoint de reporting. Si vous définissez direction sur incoming, vous ne verrez que les colis retour. Si vous n’avez aucun retour entrant, le rapport sera vide.

Vous devez également spécifier l’ID d’intégration dans votre requête. Il n’est pas possible de créer un rapport pour l’ensemble de vos intégrations. Assurez-vous donc d’indiquer le bon ID pour voir vos colis sortants ou entrants par intégration.

Comment trouver mon integration_id ?

Vous pouvez trouver votre integration_id via l’endpoint Retrieve a list of integrations, ou depuis votre panneau Sendcloud (Paramètres > Intégrations > recherchez votre intégration dans la liste > Modifier). L’ID d’intégration apparaît à la fin de l’URL, par exemple : 'https://app.sendcloud.com/v2/settings/integrations/api/95977'

Comment trouver mon sender_address_id ?

Via l’endpoint Retrieve a list of sender addresses, ou depuis votre panneau Sendcloud (Paramètres > Adresses > Modifier une adresse). L’ID apparaît à la fin de l’URL, par exemple : 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'

Comment trouver mon brand_id ?

Via l’endpoint Retrieve configured brands, ou dans votre panneau Sendcloud (Paramètres > Marques > Modifier une marque). L’ID apparaît à la fin de l’URL, par exemple : 'https://app.sendcloud.com/v2/settings/brands/86054'

Je reçois le message d’erreur « Service point delivery is not enabled for this integration. ». Que se passe-t-il ?

Vous devez activer la livraison en point relais dans le panneau Sendcloud : Paramètres > Intégrations > API > Modifier > Cochez la case pour activer la livraison en point relais. Cela est expliqué plus en détail ici.

Les numéros de maison sont dupliqués sur mes étiquettes lorsque je crée des colis via l’API. Que se passe-t-il ?

Le format d’adresse le plus couramment utilisé est le suivant :

• address : Stadhuisplein
• house_number: 10

Une autre méthode courante est :

• address: Stadhuisplein 10

Puis-je créer des envois multi-colis (multicollo) via l’API ?

Oui, c’est possible — cela est décrit plus en détail dans notre documentation.

Puis-je attribuer la même marque à plusieurs adresses d’expéditeur ?

Oui, vous pouvez attribuer la même marque à certaines ou à toutes vos adresses d’expéditeur.

Puis-je attribuer plusieurs marques à la même adresse d’expéditeur ?

Une seule marque peut être attribuée par adresse d’expéditeur. La solution consiste à créer une adresse d’expéditeur en double et à attribuer une marque différente à chacune. Une seule adresse peut être définie comme adresse par défaut ; nous vous recommandons donc de donner un nom explicite au doublon afin de l’identifier facilement dans le panneau.

Puis-je créer des envois internationaux via l’API ?

Oui, absolument. Vos documents douaniers seront générés automatiquement, à condition que les champs obligatoires (voir ci-dessous) soient correctement renseignés pour chaque produit inclus dans l’envoi. Cela est expliqué plus en détail dans notre documentation : Expédition internationale

Quels champs sont obligatoires pour l’expédition internationale ?

• customs_invoice_number
• customs_shipment_type
• country_state (obligatoire uniquement pour l’Australie, le Canada, l’Italie et les États-Unis.)
• parcel_items
  • origin_country (ISO 2)
  • hs_code

Articles et ressources associés

→ Documentation API Sendcloud et Guide de démarrage rapide

→ Référence de l’API Sendcloud

→ Portail développeur Sendcloud

→ Points relais pour les intégrations API