FAQ - API Sendcloud

Sujet:  Questions fréquemment posées concernant les intégrations de boutique en ligne en utilisant les API de Sendcloud.

Quelles sont les limites de débit notre API?

Limites

Notre API est limitée dans le nombre de requêtes qui peuvent être faites par minute. Les limites sont différentes pour les endpoints liés à l'expédition.

• Safe requests (GET): 1000 requêtes par minute.
• Unsafe requests (POST/PATCH/PUT/DELETE): 100 requêtes par minute.
• Shipping-related safe requests (GET): 420 requêtes par minute.
• Shipping-related unsafe requests (POST/PATCH/PUT/DELETE): 100 requêtes par minute.

Capacité maximale

Les endpoints considérés comme non sûrs (unsafe) disposent d'une capacité maximale définie, qui correspond au nombre maximum de demandes simultanées que l'API peut gérer. Elle permet d'augmenter temporairement les requêtes pour répondre à de courtes périodes de trafic élevé sans dépasser les limites globales.

• Unsafe requests (POST/PATCH/PUT/DELETE): 15 requêtes par seconde.
• Shipping-related unsafe requests (POST/PATCH/PUT/DELETE): 15 requêtes par seconde

Pour en savoir plus sur la limitation du débit, consultez notre documentation pour développeurs.

Ceci peut être modifié à la discrétion de Sendcloud.

Comment puis-je utiliser l'API de Sendcloud au mieux ?

Il existe plusieurs façons d'utiliser efficacement notre API. Par exemple, vous pouvez créer des colis en masse, avoir la mise à jour de vos colis avec le paramètre updated_after ou utiliser des webhooks pour obtenir des mises à jour directement dans votre système.

Vous pouvez faire des appels groupées en parallèle à notre API, pour des petits groupes de colis. Pour annoncer 100 colis, vous pourriez faire 5 lots de 20 appels en parallèle de notre API.

Je veux créer des étiquettes immédiatement lorsque je crée un colis via l'API. Comment puis-je faire? 

Pour créer des colis et des étiquettes d'envoi en un seul API call, attribuez la valeur "true" au champ request_label dans la demande de Création d'un parcel endpoint. Cela est davantage expliqué dans notre documentation. 

Comment puis-je maintenir l'idempotence pour les commandes/envois que j'importe ou crée dans Sendcloud? 

Dans le contexte des API, l'idempotence fait référence au fait que des demandes multiples ont le même effet qu'une seule demande. Cela permet d'éviter les erreurs de l'utilisateur, et dans le cas des API de Sendcloud, la duplication des commandes dans notre système. Il existe deux endpoints qui tentent d'être idempotents: 

• Mettre à jour un colis
  Utilisez le champ external_reference pour maintenir l'idempotence. 

• Créer/Mettre à jour une liste d'envois
  Il s'agit d'un upsert endpoint, cela signifie que, si un envoi existe déjà dans la base de données Sendcloud, l'envoi sera mis à jour. S'il n'y a pas de correspondance, alors il sera créé. Vous devez utiliser une combinaison de external_order_id et external_shipment_id pour maintenir l'idempotence. Seuls les envois dont l'horodatage updated_at (ISO 8601 DateTime) a été modifié, seront mis à jour. Nous vous recommandons d'utiliser une combinaison de ces champs pour une intégration solide. 

Pourquoi le champ sender_address est-il obligatoire lors de la création d'étiquettes via l'API?

Les transporteurs exigent qu'une adresse d'expéditeur soit présente sur chaque étiquette d'envoi afin d'identifier l'origine d'un colis. Si aucune adresse d'expédition n'est spécifiée lorsque vous créez un colis via l'API, votre adresse par défaut (telle qu'enregistrée dans votre compte Sendcloud) sera utilisée pour imprimer l'étiquette. Nous expliquons plus en détail comment obtenir un identifiant d'adresse d'expéditeur et la relation entre les adresses d'expédition, les étiquettes et les marques, dans notre documentation. 

Puis-je utiliser les règles d'expédition lorsque je crée des commandes via l'API?

Les règles d'expédition s'appliqueront aux commandes que vous créez via votre compte Sendcloud, à partir du moment où la valeur du champ apply_shipping_rules est true. Nous vous recommandons d'utiliser la méthode d'expédition "Unstamped letter" pour créer vos commandes si vous voulez que les règles d'expédition s'appliquent correctement à vos commandes. Cela vous permettra d'éviter les champs requis pour la méthode d'expédition et toutes les règles que vous avez configurées et qui affectent la sélection de la méthode d'expédition seront correctement appliquées à votre commande. 

Puis-je tester l'API sans être facturé pour les étiquettes que je crée?

Vous pouvez utiliser la méthode d'expédition Sendcloud "Unstamped letter" pour créer vos envois. Cela vous permet de tester l'API sans être facturé pour les étiquettes que vous créez. 

Veuillez noter qu'il n'est pas possible d'utiliser cette méthode pour tester la création d'étiquette de retour. Pour cela, il vous faut utiliser une méthode d'expédition qui prend en charge les demandes d'annulation de Sendcloud, et annulez l'étiquette avant 23h59 le jour de sa création. Pour davantage d'information, nous vous invitons à consulter notre documentation sur les étiquettes de test. 

Je reçois le message d'erreur "User is not allowed to announce". Quel est le problème?

Nous vous invitons à vérifier que vous avez bien suivi toutes les étapes de la configuration de base de votre compte, et que vous avez bien activé votre prélèvement automatique. Voir: Bienvenue chez Sendcloud

Puis-je voir toutes mes méthodes 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 méthodes d'expédition en plus de celles proposées par Sendcloud en faisant une demande GET au endpoint pour récupérer la liste des méthodes d'expédition. Par contre, les prix de votre contrat ne seront pas récupérés à moins que vous n'ayez téléchargé vos propres tarifs. 

Puis-je voir mes propres tarifs avec mes contrats transporteur en utilisant l'API pour pouvoir voir et comparer les tarifs et les méthodes?

Oui, si vous avez téléchargé vos propres tarifs dans votre compte Sendcloud en suivant les étapes de cet article.

Je reçois le message d'erreur "Invalid shipment ID" lorsque j'essaie de créer un envoi via l'API. Que se passe-t-il?

Il est probable que l'identifiant de la méthode d'expédition shipping_method_id que vous utilisez, renvoie à une méthode qui ne prend pas en charge les envois à destination ou en provenance de l'adresse indiquée, par exemple, si vous utilisez une méthode nationale pour un envoi à l'international. Il se peut également que vous essayiez d'utiliser une méthode de retour pour un envoi sortant, ou l'inverse. Vous pouvez utiliser l'endpoint des produits d'expédition pour trouver une méthode qui est adaptée à l'envoi, en fonction des paramètres que vous définissez. 

Enfin, veillez à ce que l'identifiant de la méthode d'expédition corresponde toujours à la méthode que vous souhaitez utiliser. Les identifiants des méthodes d'expédition de notre base de données sont instables et ne doivent pas être mises en cache pendant plus d'une heure. 

J'ai réussi à créer une requête pour un envoi, mais le colis n'apparaît pas dans mon compte Sendcloud. Quel est le problème?

Il est probable que la requêtes n'ait pas inclus de valeur pour le champ booléen request_label.

• Lorsque le champ est true, l'étiquette est imprimée à côté de la demande de création d'un envoi, et ce dernier apparaîtra dans l'onglet étiquettes créées, dans Sendcloud. 
• Lorsque la valeur est false, l'envoi est créé mais apparaît dans la liste des commandes importées, en attente de traitement.
• Si vous n'avez pas ajouté de valeur, vous pouvez utiliser l'endpoint Update a parcel pour modifier le champ request_label en true ou false. Vous pouvez trouver l'identifiant unique du colis (dont vous avez besoin pour la commande) en utilisant l'endpoint Retrieve all parcels. 

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

Oui. Par exemple, vous pouvez ajouter le type de note suivante "Veuillez emballer cet article dans du papier cadeau". Ces notes apparaîtront également sur les bons d'expédition ou les listes de prélèvement si vous utilisez Pack & Go.

J'ai créé un rapport à partir de l'API, mais mon fichier CSV est vide. Quel est le problème?

Veuillez tenir compte du filtre direction lorsque vous créez la vers vers l'endpoint. Si vous précisez que la direction est incoming, vous ne verrez que les retours. Si vous n'avez aucun retour entrant, le rapport sera alors vide. 

Aussi, vous devez préciser l'identifiant de l'intégration dans votre requête. Vous ne pouvez pas créer un rapport pour toutes vos intégrations, ainsi vous devez spécifier l'identifiant de la bonne intégration pour voir vos colis entrants ou sortants. 

Où puis-je trouver l'integration_id?

Vous pouvez trouver votre identifiant integration_id dans l'endpoint Retrieve a list of integrations ou depuis votre compte Sendcloud (Réglages> Boutique(s) connectée(s)> trouvez votre intégration dans la liste > Modifier). L'idenfiant de votre boutique sera affichée à la find de l'URL, par exemple "https://app.sendcloud.com/v2/settings/integrations/api/95977"

Où puis-je trouver mon sender_address_id? 

Depuis l'endpoint Retrieve a list of sender addresses, ou depuis votre compte Sendcloud (Réglages> Mes Adresses > Modifier une adresse). L'idenfiant sera affichée à la find de l'URL, par exemple 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'

Où puis-je trouver mon brand_id?

Depuis l'endpoint Retrieve configured brands, ou depuis votre compte Sendcloud (Réglages > Marques > Modifier une marque). L'idenfiant sera affichée à la find de l'URL, par exemple 'https://app.sendcloud.com/v2/settings/brands/86054'

Je reçois le message d'erreur suivant: "Service point delivery is not enabled for this integration." Quel est le problème?

Vous devez activer la livraison en point relais dans Sendcloud, dans Réglages > Boutique(s) connectée(s) > API > Modifier > Cochez la case pour activer la livraison en point relais. Plus de détail à ce propos ici.

Je ne vois pas les méthodes de tous les transporteurs lorsque je fais une requête GET pour récupérer une liste des méthodes d'expédition

Tout d'abord, vérifiez que vous avez activé tous les transporteurs que vous souhaitez utilisez (dans votre compte Sendcloud > Mes Envois > Transporteurs). Utilisez le menu déroulant pour sélectionner plus de transporteurs pour les pays dans lesquels vous avez une adresse d'expédition active. 

Ensuite, vous devrez préciser l'une de vos adresses d'expédition dans votre appel API aux endpoints des méthodes d'expédition pour pouvoir les voir pour les pays autres que celui de votre adresse d'expédition par défaut. Par exemple, si votre adresse d'expédition par défaut est en France, mais que vous voulez voir les méthodes d'expédition pour Royal Mail (UK), vous devrez renseigner l'identifiant de l'adresse d'expédition au Royaume-Uni pour récupérer les méthodes applicables au Rouayume-Uni. Cela est davantage expliqué dans notre documentation. 

Les numéros de rue sont dupliqués sur mes étiquettes d'expédition lorsque je crée des envois via l'API. Que se passe-t-il?

Le format le plus utilisé pour une adresse est le suivant:

• address : Stadhuisplein
• house_number: 10

Une autre méthode utilisée est celle-ci:

• address: Stadhuisplein 10

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

Oui, c'est possible—cela est expliqué en détail dans notre documentation. 

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

Oui, vous pouvez attribuer la même marque à plusieurs ou toutes vos adresses d'expédition.

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

Une seule marque peut être attribuée par adresse d'expédition. Ici, la solution est de créer une seconde adresse d'expédition et à attribuer une marque d'expédition différente à chacune d'elles. Une seule adresse peut être l'adresse par défaut. Nous vous invitons donc à donner un nom spécifique à ces adresses d'expédition pour les identifier facilement dans votre compte.

Puis-je créer des envois à l'international via l'API?

Oui, bien sûr. Vos documents douaniers seront générés automatiquement si les champs obligatoires prévus à cet effet sont bien remplis pour chaque article. Cela est expliqué en détails dans notre documentation: International shipping.

Quels sont les champs obligatoires pour les envois à l'international?

• customs_invoice_number
• customs_shipment_type
• country_state(Demandés uniquement pour l'Australie, le Canada, l'Italy, et les Etats-Unis).
• parcel_items
  • origin_country (ISO 2) 
  • hs_code

Articles et ressources liés

→ Documentation API Sendcloud et Guide de démarrage rapide

→ Sendcloud API Reference

→ Portail de développeur Sendcloud

→ Points relais pour les intégrations API