Comment envoyer plusieurs numéros de suivi dans une seule requête API (limites des lots et échecs partiels)
Pour envoyer plusieurs numéros de suivi dans une seule requête API, utilisez un point de terminaison de la Tracking API qui accepte explicitement les lots, formatez chaque expédition conformément à son schéma de requête et divisez les listes plus importantes en lots respectant les limites documentées. Examinez ensuite à la fois la réponse HTTP et le résultat de chaque expédition : une requête HTTP réussie ne signifie pas nécessairement que tous les numéros de suivi ont été acceptés. Réessayez uniquement les échecs éligibles et rapprochez les résultats incertains avant de renvoyer un lot entier.

Ce guide s’adresse aux développeurs qui connectent le suivi des expéditions à un système de gestion des commandes, une plateforme d’entrepôt, une application de commerce électronique ou un tableau de bord interne. L’objectif n’est pas simplement d’envoyer moins de requêtes, mais de comptabiliser chaque expédition sans créer de travail en double ni perdre les enregistrements échoués.
Tout d’abord, identifiez ce que fait réellement le point de terminaison de lot
Une intégration de suivi peut impliquer plusieurs opérations distinctes. L’enregistrement des expéditions, la récupération de leurs dernières informations de suivi et la réception des mises à jour ultérieures ne sont pas interchangeables.
- Enregistrement : Soumettre les expéditions afin que le service puisse commencer ou maintenir leur suivi.
- Recherche : Demander les informations de suivi des expéditions, sous réserve des règles de récupération du point de terminaison.
- Mise à jour de la livraison : Recevoir les changements ultérieurs via un mécanisme pris en charge, tel que des webhooks, ou les récupérer au moyen de requêtes planifiées.
Consultez la documentation pour connaître l’opération exacte dont vous avez besoin. Un point de terminaison d’enregistrement acceptant plusieurs enregistrements ne prouve pas qu’un point de terminaison de recherche accepte le même nombre, utilise le même schéma ou partage la même limite de débit.
Pour une intégration 17TRACK, commencez par la page du produit Tracking API et utilisez la documentation officielle de l’API pour confirmer l’opération, la méthode d’authentification, le format de la requête et les champs de réponse. Considérez les exemples ci-dessous comme des modèles d’implémentation et non comme un substitut au contrat de cette API.
Les limites des lots ne se résument pas à un nombre maximal d’expéditions
Il n’existe pas de limite universelle pour les lots dans une Tracking API. Les limites peuvent varier selon le fournisseur, le point de terminaison, la version de l’API et la configuration du compte. Avant d’implémenter le traitement par lots, consignez séparément ces contraintes.
| Contrainte | Élément à confirmer | Conséquence pour l’implémentation |
|---|---|---|
| Éléments par requête | Nombre maximal d’enregistrements pour l’opération concernée | Diviser la liste d’entrée avant l’envoi |
| Taille du corps de la requête | Toute limite documentée en octets | Tenir compte des champs facultatifs et de la taille de sérialisation |
| Débit des requêtes | Nombre de requêtes autorisées sur un intervalle défini | Réguler les requêtes au moyen d’un limiteur partagé |
| Concurrence | Toute restriction concernant les requêtes simultanées | Limiter le nombre de travailleurs actifs |
| Comptabilisation de l’utilisation | Déterminer si l’utilisation est comptée par requête, par expédition ou selon une autre unité | Estimer la consommation séparément du volume de requêtes |
Par exemple, si un point de terminaison hypothétique autorise 25 enregistrements par requête, 63 enregistrements nécessitent trois requêtes contenant respectivement 25, 25 et 13 enregistrements. Ces chiffres illustrent uniquement le découpage en lots ; ils ne correspondent pas à des limites indiquées par 17TRACK.
Ne supposez pas que le traitement par lots réduit l’utilisation facturable. Il peut réduire la surcharge liée aux requêtes HTTP, mais tout effet sur les frais dépend des règles réelles de comptabilisation du fournisseur. De même, une taille de lot valide n’autorise pas un nombre illimité de requêtes parallèles.
Préparez les enregistrements avant de construire la requête
La plupart des échecs de lots évitables commencent lors de la préparation des entrées. Validez chaque expédition avant de l’ajouter à un lot, mais évitez les règles qui rejetteraient par inadvertance des numéros de suivi légitimes provenant de différents transporteurs.
- Conservez les numéros de suivi sous forme de chaînes. Les convertir en nombres peut supprimer les zéros initiaux ou modifier les identifiants longs.
- Supprimez les espaces superflus environnants. Ne supprimez pas les caractères internes et ne modifiez pas la casse, sauf si la spécification concernée autorise cette normalisation.
- Validez les champs obligatoires. Certains flux de travail peuvent nécessiter un identifiant de transporteur ou des informations supplémentaires sur l’expédition. Utilisez uniquement les noms et valeurs de champs documentés.
- Définissez une portée explicite pour la déduplication. Un numéro de suivi répété n’est pas automatiquement un doublon pour chaque transporteur, marchand ou expédition historique.
- Conservez un identifiant d’expédition local. Enregistrez la relation entre l’article sortant et votre commande ou enregistrement d’expédition, même lorsque l’API n’accepte pas de champs de référence personnalisés.
Pour le suivi des transporteurs sur plusieurs réseaux, ne déduisez pas le transporteur uniquement de la longueur ou du préfixe d’un numéro de suivi, sauf si cette déduction est fiable dans votre flux de travail spécifique. Lorsque l’API prend en charge l’identification du transporteur, suivez son comportement documenté en cas d’ambiguïté.
Structure de requête illustrative
Le JSON suivant montre le concept d’une charge utile groupée. L’enveloppe, les noms de propriétés et les identifiants sont illustratifs et ne constituent pas un schéma de requête 17TRACK. Certaines API attendent un tableau de niveau supérieur plutôt qu’un objet contenant un tableau.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Construisez la charge utile au moyen d’un sérialiseur JSON plutôt qu’en concaténant des chaînes. Envoyez les identifiants d’authentification via le mécanisme documenté et gardez-les hors du contrôle de version, du code transmis au navigateur et des journaux courants.
Traitez la réponse à deux niveaux
Une requête par lots possède un résultat au niveau du transport et un résultat au niveau de l’application. Votre intégration doit évaluer les deux.
Niveau 1 : la requête a-t-elle reçu une réponse exploitable ?
Commencez par le statut HTTP, les en-têtes de réponse et le corps de la réponse. Les erreurs d’authentification, les requêtes mal formées, la limitation du débit et les défaillances du serveur peuvent empêcher le traitement normal des éléments. Un délai d’attente réseau est différent : le client peut ignorer si le serveur a reçu ou traité la requête.
La sémantique HTTP est définie dans la RFC 9110. Toutefois, la documentation du fournisseur détermine la manière dont ses champs de résultat au niveau de l’application correspondent aux résultats réels des expéditions.
Niveau 2 : qu’est-il arrivé à chaque expédition ?
Si la réponse prend en charge les résultats au niveau des éléments, classez chaque enregistrement soumis. Ne supposez pas qu’un HTTP 200 signifie que chaque enregistrement a réussi, ni qu’une liste de résultats conserve l’ordre de la requête, sauf si le contrat le garantit explicitement.
- Accepté : L’opération a réussi selon la définition documentée du point de terminaison.
- Échec d’entrée permanent : Corrigez ou examinez l’enregistrement avant toute nouvelle tentative.
- Échec réessayable : Planifiez une nouvelle tentative conformément aux recommandations du fournisseur.
- Résultat inconnu : La réponse est absente, incomplète ou ne peut pas être associée de manière sûre à l’enregistrement soumis.
Conservez séparément les réponses telles que « déjà enregistré » ou les réponses similaires liées aux doublons jusqu’à ce que vous compreniez leur signification documentée. Elles peuvent indiquer que l’état souhaité existe déjà, mais ne doivent pas être automatiquement considérées comme une confirmation de propriété, de configuration ou d’abonnement réussi.
Après le traitement d’une réponse, chaque enregistrement d’entrée doit avoir exactement un résultat local. Un contrôle de rapprochement utile est le suivant : enregistrements soumis = enregistrements acceptés + échecs permanents + échecs réessayables + résultats inconnus. Il s’agit d’une règle de comptabilisation locale et non d’un format de réponse API obligatoire.
Gérez les échecs partiels sans rejouer les enregistrements réussis
Supposons qu’un lot illustratif contienne dix expéditions : sept sont acceptées, deux comportent des champs obligatoires invalides et une rencontre une erreur temporaire documentée. Enregistrez les sept résultats réussis, envoyez les deux enregistrements invalides pour correction et réessayez uniquement l’échec temporaire.
Rejouer les dix enregistrements génère un trafic inutile et peut compliquer la gestion des doublons. Il devient également plus difficile de distinguer un rejet initial d’une réponse ultérieure liée à un doublon.
| Résultat | Action recommandée |
|---|---|
| Champ invalide ou valeur non prise en charge | Corriger l’entrée ; ne pas réessayer sans modification |
| Échec d’authentification ou d’autorisation | Suspendre le travail concerné et corriger les identifiants ou les accès |
| Réponse de limitation du débit | Attendre conformément aux recommandations documentées et aux en-têtes de réponse applicables |
| Erreur temporaire au niveau de l’élément | Réessayer cet élément avec un nombre de tentatives et un délai d’attente limités |
| Délai d’attente après soumission | Marquer comme incertain ; effectuer un rapprochement ou utiliser les garanties documentées de sécurité des nouvelles tentatives |
| Résultat non reconnu ou incomplet | Conserver les preuves et examiner le cas plutôt que de supposer la réussite |
HTTP 429 indique un nombre excessif de requêtes et sa réponse peut inclure un en-tête Retry-After, comme l’explique la RFC 6585. Ne supposez pas que cet en-tête est toujours présent. Lorsqu’aucun délai explicite n’est fourni, utilisez une stratégie de temporisation limitée cohérente avec la documentation de l’API.
Ajoutez une variation aléatoire afin de répartir les nouvelles tentatives de plusieurs travailleurs, définissez un nombre maximal de tentatives ou une durée maximale de réessai et envoyez les enregistrements épuisés vers une file d’examen. Des tentatives infinies peuvent masquer un problème de configuration persistant.
Pourquoi les délais d’attente nécessitent un traitement particulier
Un délai d’attente ne prouve pas un rejet. Le serveur peut avoir accepté le lot avant l’interruption de la connexion. Rejouer automatiquement une requête qui modifie l’état peut donc répéter l’opération.
Si le point de terminaison prend en charge des clés d’idempotence documentées, suivez ses règles, notamment la portée et la durée de conservation de la clé. N’inventez pas un en-tête d’idempotence en supposant que le serveur l’honorera. Sinon, utilisez un flux de recherche ou de rapprochement pris en charge pour déterminer si l’état souhaité existe avant de renvoyer la requête. La déduplication locale aide à coordonner vos propres travailleurs, mais ne garantit pas l’idempotence côté serveur.
Un flux pratique de traitement par lots
Conservez les détails propres au fournisseur dans un adaptateur afin que la file d’attente, le planificateur de nouvelles tentatives et la logique de surveillance ne dépendent pas des noms de champs de réponse bruts.
valider les enregistrements et conserver les identifiants d’expédition locaux
résoudre les doublons dans la portée métier prévue
diviser les enregistrements selon les limites documentées des éléments et de la charge utile
pour chaque lot via un pool de travailleurs limité :
conserver un enregistrement de tentative avant l’envoi
attendre le limiteur de débit partagé
envoyer via l’adaptateur propre au fournisseur
si le résultat est incertain :
mettre en file le rapprochement
continuer
classer les résultats au niveau de la requête et des éléments
conserver un résultat pour chaque enregistrement soumis
planifier uniquement les échecs éligibles pour une nouvelle tentative
diriger les enregistrements invalides ou épuisés vers un examen
Rendez la conservation des résultats et la planification des nouvelles tentatives récupérables. Par exemple, un enregistrement de tâche durable ou un modèle de mise en file transactionnel peut empêcher une panne du processus de faire perdre la décision de réessai. Lorsqu’ils redémarrent, les travailleurs doivent pouvoir distinguer le travail non envoyé du travail dont le résultat distant reste incertain.
Utilisez la taille du lot comme un paramètre configurable lié au point de terminaison concerné, et non comme une constante dispersée dans la base de code. Un lot plus petit peut être utile lors du dépannage ou de l’isolation d’enregistrements problématiques ; le plus grand lot autorisé n’est pas automatiquement la meilleure taille opérationnelle.
Surveillez les résultats des expéditions, pas uniquement la disponibilité HTTP
La surveillance de l’API doit indiquer si les expéditions atteignent l’état prévu. Un tableau de bord qui ne signale que les taux de réussite HTTP peut ne pas détecter les échecs partiels dans des réponses par ailleurs réussies.
- Taux d’acceptation des éléments : Enregistrements acceptés divisés par les enregistrements soumis, avec un traitement clairement défini des nouvelles tentatives.
- Répartition des échecs : Totaux par point de terminaison, code d’erreur documenté et contexte pertinent du transporteur.
- Résultats inconnus : Enregistrements non rapprochés et durée pendant laquelle ils sont restés non résolus.
- Arriéré des nouvelles tentatives : Nouvelles tentatives en attente, ancienneté de la plus ancienne et tentatives épuisées.
- État des requêtes : Latence, délais d’attente, limitation du débit et erreurs serveur.
- Fraîcheur du suivi : Vérifier si les expéditions acceptées reçoivent ensuite des informations de suivi exploitables.
L’acceptation de l’enregistrement ne prouve pas l’existence d’un nouveau scan du transporteur. Séparez l’état du traitement de l’API du déplacement de l’expédition et de la fraîcheur des données afin de ne pas confondre un incident d’intégration avec un retard de livraison.
Consignez les identifiants locaux des lots, les références d’expédition, le nombre de tentatives, les codes d’erreur documentés et les identifiants de requête du fournisseur lorsqu’ils sont disponibles. Masquez les identifiants et les informations personnelles inutiles. Utilisez les identifiants de suivi uniquement lorsque cela est nécessaire sur le plan opérationnel et évitez de placer des identifiants d’expédition bruts dans les étiquettes de métriques à cardinalité élevée.
Testez ces cas avant la mise en production
Utilisez un environnement sandbox documenté ou un environnement de test contrôlé lorsqu’il est disponible. Ne supposez pas que des numéros de suivi inventés produiront des réponses de production prévisibles.
- Soumettez un lot valide à la limite documentée d’éléments, puis testez la manière dont votre client empêche l’envoi d’un lot trop volumineux.
- Vérifiez que les numéros de suivi comportant des zéros initiaux survivent à la sérialisation et au stockage.
- Testez des éléments acceptés et rejetés dans un même lot sans réessayer les enregistrements réussis.
- Simulez une limitation du débit et confirmez que plusieurs travailleurs respectent la même limite.
- Simulez un délai d’attente après la soumission et vérifiez le parcours de rapprochement.
- Redémarrez un travailleur entre la réception de la réponse et sa conservation locale.
- Testez les résultats d’éléments manquants, inconnus ou impossibles à associer.
- Confirmez que les enregistrements invalides atteignent une file de correction visible au lieu d’être réessayés indéfiniment.
Une intégration prête pour la production peut expliquer l’état de chaque expédition soumise, y compris celles dont le résultat est temporairement inconnu. Réduire le nombre de requêtes est utile ; préserver cette traçabilité est l’objectif de conception le plus important.
FAQ
Combien de numéros de suivi puis-je envoyer dans une seule requête ?
Utilisez la limite documentée pour le point de terminaison et la version exacte de l’API. Vérifiez également la taille des requêtes, les limites de débit et les éventuelles contraintes propres au compte. Il n’existe pas de nombre universel sûr à appliquer à toutes les Tracking API ou à toutes les opérations d’une même API.
Un seul numéro de suivi invalide peut-il faire échouer tout le lot ?
Oui, selon les règles de validation du point de terminaison. Certaines API renvoient des rejets individuels, tandis que d’autres peuvent rejeter une requête avant le traitement des éléments. Vérifiez les erreurs au niveau de la requête et les résultats au niveau des éléments ; ne supposez pas que tous les points de terminaison de lots prennent en charge l’acceptation partielle.
Dois-je réessayer un lot lorsque la réponse HTTP est réussie ?
Pas automatiquement. Analysez d’abord le statut documenté au niveau de l’application et les résultats des éléments. Conservez les enregistrements réussis et réessayez uniquement les échecs éligibles. Si le résultat ne peut pas être interprété de manière sûre, classez-le comme incertain et examinez-le.
Puis-je mélanger plusieurs transporteurs dans un même lot ?
Uniquement lorsque le point de terminaison prend en charge cette structure de requête. Vérifiez si les informations du transporteur sont fournies pour chaque expédition, si l’identification automatique est prise en charge et ce qui se produit lorsque l’identification est ambiguë. Un service multi-transporteurs ne définit pas à lui seul les règles de traitement par lots de chaque point de terminaison.
Le traitement par lots accélère-t-il l’arrivée des mises à jour de suivi ?
Le traitement par lots peut réduire le nombre de requêtes envoyées par votre application, mais il n’accélère pas à lui seul l’apparition des événements du transporteur. L’enregistrement, la récupération des données, la disponibilité des scans du transporteur et la transmission des mises à jour sont des étapes distinctes du flux de travail.
Sources
- Tracking API 17TRACK — point d’entrée officiel du produit pour les développeurs qui évaluent une intégration de suivi.
- Documentation de l’API 17TRACK — référence du contrat de point de terminaison propre au fournisseur, des limites, de l’authentification et du traitement des réponses.
- RFC 9110 : sémantique HTTP — sémantique des statuts HTTP, idempotence, nouvelles tentatives automatiques et Retry-After.
- RFC 6585 : codes d’état HTTP supplémentaires — définition de HTTP 429 Too Many Requests et de son en-tête Retry-After facultatif.


