Comment enregistrer un numéro de suivi via l’API : champs de la requête, codes des transporteurs et réponses
Pour enregistrer un numéro de suivi via une API, envoyez une demande d’enregistrement authentifiée contenant le numéro de suivi de l’envoi et, lorsque cela est requis, un identifiant de transporteur. Examinez ensuite la réponse pour chaque envoi soumis — et pas uniquement le statut HTTP — puis enregistrez si l’enregistrement a réussi, échoué ou reste incertain. L’enregistrement démarre le processus de suivi ; il ne prouve pas que le transporteur a scanné le colis ni que les événements de suivi sont déjà disponibles.
Ce guide s’adresse aux développeurs qui connectent un système de gestion des commandes, une application d’entrepôt ou une plateforme e-commerce à une API de suivi. Il utilise 17TRACK comme exemple concret d’intégration et explique quels détails doivent être vérifiés dans la documentation correspondant à la version d’API sélectionnée.
Ce que fait l’enregistrement — et ce qu’il ne fait pas
Une demande d’enregistrement indique à un service de suivi quel envoi vous souhaitez suivre. Elle est différente de l’achat d’une étiquette d’expédition, de la réservation d’une collecte ou de la demande à un transporteur de créer un envoi. Dans une intégration classique, le processus d’expédition génère d’abord un numéro de suivi, puis votre application enregistre ce numéro.
Gardez ces trois événements distincts dans votre application :
- Envoi créé : votre système d’expédition a attribué un numéro de suivi.
- Enregistrement accepté : le service de suivi a accepté l’envoi pour le suivi.
- Informations de suivi reçues : les événements du transporteur sont devenus disponibles via le service de suivi.
Ne mettez pas une commande à jour avec le statut « en transit » simplement parce que l’enregistrement a réussi. Une étiquette récemment créée peut ne pas avoir encore fait l’objet d’un scan physique de prise en charge. Le statut d’expédition visible par le client doit provenir des événements de suivi interprétés selon vos règles de correspondance des statuts, et non de la réponse d’enregistrement.
Pour les intégrations 17TRACK, commencez par la présentation de l’API de suivi et utilisez la documentation officielle de l’API comme référence pour les points de terminaison, les définitions des champs, l’authentification et les codes de réponse. Les exemples ci-dessous se concentrent sur l’enregistrement plutôt que sur les tâches distinctes de récupération des résultats ou de réception des mises à jour.
Préparez les champs de la requête avant d’écrire l’appel API
La préparation la plus utile consiste à définir un petit contrat de champs entre votre système d’expédition et votre intégration de suivi. Déterminez l’origine de chaque valeur, si elle peut être absente et comment elle sera validée.
| Champ ou valeur | Objectif | Règle d’implémentation |
|---|---|---|
| Numéro de suivi | Identifie l’envoi à suivre. | Stockez-le et transmettez-le sous forme de chaîne ; préservez les zéros initiaux. |
| Identifiant du transporteur | Identifie le transporteur dans le système du fournisseur de suivi. | Utilisez l’identifiant indiqué par le fournisseur, et non un code interne d’entrepôt. |
| Référence interne | Relie l’enregistrement à votre fiche d’envoi. | Utilisez un champ de référence pris en charge s’il existe ; conservez dans tous les cas votre propre correspondance en base de données. |
| Données d’identification supplémentaires | Peuvent aider à identifier un envoi lorsqu’un transporteur exige davantage que son numéro de suivi. | Soumettez uniquement les champs documentés pour cette intégration et ce transporteur. |
| Identifiant API | Authentifie le compte appelant. | Conservez-le sur le serveur et excluez-le des journaux de l’application. |
Traitez le numéro de suivi comme un identifiant
Ne convertissez jamais un numéro de suivi en entier. Une conversion numérique peut supprimer les zéros initiaux, et les grandes valeurs peuvent perdre en précision dans certains environnements de programmation. Supprimez les espaces superflus environnants, mais ne retirez pas la ponctuation et ne modifiez pas la casse, sauf si la documentation concernée ou le format du transporteur autorise cette normalisation.
Validez les erreurs évidentes avant d’appeler l’API : chaînes vides, retours à la ligne inattendus et numéro de commande copié dans le champ du numéro de suivi. N’imposez pas une règle universelle de longueur ou de caractères à tous les transporteurs. Une règle adaptée à un transporteur peut rejeter des numéros légitimes d’un autre.
Gardez les références de commande séparées des identités d’envoi
Une commande peut comporter plusieurs colis et un envoi de remplacement peut introduire un autre numéro de suivi. Modélisez l’enregistrement au niveau de l’envoi ou du colis plutôt que de supposer un seul numéro de suivi par commande.
Si vous utilisez une balise ou un champ de référence pris en charge par le fournisseur, privilégiez une référence opaque de l’envoi plutôt que l’adresse e-mail ou l’adresse postale du client. Votre propre base de données doit rester le lien de référence entre les commandes, les envois, les numéros de suivi et les correspondances de transporteurs.
Choisissez le bon code transporteur
Un code transporteur n’est pas nécessairement un identifiant universel du secteur. La valeur reconnue par une plateforme de suivi peut différer du nom du transporteur enregistré dans votre logiciel d’expédition. Même deux systèmes utilisant des codes numériques peuvent attribuer des numéros différents au même transporteur.
Conservez une correspondance explicite entre votre service d’expédition et l’identifiant du transporteur utilisé par le fournisseur de suivi. Si nécessaire, distinguez l’activité régionale ou le service d’un transporteur de sa marque globale. Une correspondance fondée uniquement sur un nom affiché peut devenir ambiguë lorsque les systèmes d’expédition utilisent des alias.
- Lorsque le transporteur est connu : utilisez l’identifiant documenté lorsqu’il est pris en charge, en particulier lorsque les formats de numéros de suivi se chevauchent.
- Lorsque le transporteur est inconnu : utilisez la détection automatique uniquement via le mécanisme documenté. Ne supposez pas qu’une omission, une chaîne vide, zéro et null signifient la même chose.
- Lorsque le résultat semble incorrect : vérifiez l’étiquette originale, le service d’expédition et la correspondance avant d’enregistrer plusieurs fois le même numéro.
La détection automatique est utile, mais elle ne prouve pas qu’un transporteur donné détient physiquement l’envoi. De même, un code transporteur valide ne garantit pas que le numéro de suivi fourni lui appartient.
Gardez les correspondances de transporteurs configurables plutôt que de les disperser dans le code de l’application. Notez la date de leur dernière vérification et incluez un envoi connu dans les tests de régression chaque fois que vous les modifiez.
Exemple : soumettre une demande d’enregistrement 17TRACK
L’exemple suivant illustre le point de terminaison d’enregistrement 17TRACK v2.2, l’en-tête d’authentification 17token et un tableau contenant un objet de numéro de suivi. Vérifiez que cette version et ses exigences correspondent à votre compte et à la documentation officielle avant le déploiement. Le numéro de suivi est un espace réservé et doit être remplacé par un véritable identifiant d’envoi.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Cet exemple minimal ne montre ni la sélection du transporteur ni les champs supplémentaires propres à un transporteur. Consultez la documentation de l’enregistrement pour déterminer comment fonctionne la détection lorsque le champ du transporteur est omis et si votre envoi nécessite des informations supplémentaires. Si vous fournissez un transporteur, utilisez le champ carrier documenté et l’identifiant attendu par cette version de l’API.
Exécutez cette requête depuis un environnement côté serveur. N’intégrez pas le jeton dans une boutique publique, un script de navigateur ou une application mobile distribuée aux clients. Une variable d’environnement est pratique pour un exemple local ; les déploiements de production doivent utiliser les contrôles de gestion des secrets de votre organisation.
Avant d’augmenter le volume, testez un envoi connu et examinez la réponse complète. Testez ensuite une entrée invalide ainsi qu’un lot contenant des éléments valides et invalides. Ces vérifications montrent si votre intégration gère réellement les résultats au niveau des éléments plutôt que de reconnaître uniquement une réponse HTTP réussie.
Lisez la réponse à trois niveaux
Un gestionnaire de réponses fiable répond à trois questions distinctes : la requête a-t-elle atteint le service, le service a-t-il accepté l’opération et que s’est-il passé pour chaque envoi ?
1. Résultat HTTP et résultat du transport
Un délai d’attente de connexion, un échec TLS ou une réponse interrompue ne vous indique pas nécessairement si le serveur a traité la requête. Marquez ce résultat comme incertain jusqu’à sa réconciliation. Un statut HTTP de succès confirme un échange HTTP réussi, mais vous devez tout de même examiner la réponse de l’application.
2. Résultat au niveau de la requête
Examinez le résultat global et les champs d’erreur documentés par l’API. Les erreurs d’authentification, le JSON mal formé et les restrictions de compte nécessitent des actions différentes. Enregistrez le code d’erreur et le message d’origine du fournisseur au lieu de réduire chaque échec à « suivi indisponible ».
Ne supposez pas qu’un code numérique d’application a la même signification qu’un code de statut HTTP. Leurs significations proviennent de couches différentes et doivent être interprétées séparément.
3. Résultat au niveau de l’envoi
Pour un enregistrement par lots, comptabilisez chaque élément soumis. Une réponse peut distinguer les envois acceptés et rejetés ; votre analyseur doit suivre exactement le schéma documenté pour la version sélectionnée. Ne marquez pas tout un lot comme enregistré simplement parce qu’un élément a réussi.
Normalisez les réponses du fournisseur dans vos propres états applicatifs stables. Par exemple, votre base de données peut utiliser accepted, rejected et uncertain. Il s’agit d’états internes suggérés, et non de valeurs littérales des réponses 17TRACK. Conservez la réponse originale du fournisseur selon une politique appropriée de conservation et d’accès afin que les développeurs puissent examiner les divergences.
Un enregistrement d’enregistrement utile contient l’identifiant interne de l’envoi, le numéro soumis, la sélection du transporteur, l’heure de la tentative, la version de l’API, le résultat et les détails de l’erreur du fournisseur. Gardez le statut d’enregistrement séparé du statut de livraison.
Gérez les nouvelles tentatives sans créer de boucle infinie
La stratégie de nouvelle tentative doit dépendre de l’échec, et non simplement de la présence d’une exception.
- Entrée invalide : corrigez le champ avant de réessayer. Répéter une requête mal formée inchangée a peu de chances d’aider.
- Échec d’authentification : vérifiez les identifiants et la configuration du compte. Évitez de soumettre à répétition le même lot en échec.
- Limitation de débit : respectez les limites documentées et les éventuelles instructions de nouvelle tentative. Utilisez un délai progressif limité plutôt que des tentatives parallèles immédiates.
- Panne temporaire du service : réessayez dans une limite définie de tentatives et de temps.
- Délai d’attente après soumission : réconciliez l’état d’enregistrement de l’envoi selon le comportement documenté de l’API avant de supposer que la première tentative a échoué.
- Réponse liée à un doublon : vérifiez si l’envoi est déjà enregistré et correctement associé à votre fiche applicative.
Ne supposez pas que l’enregistrement est idempotent, sauf si la documentation définit ce comportement. La déduplication côté application réduit les soumissions répétées accidentelles, mais n’établit pas la politique du fournisseur en matière de doublons.
Utilisez une règle d’unicité interne adaptée à votre modèle d’envoi. Le numéro de suivi seul peut ne pas constituer une clé permanente suffisante entre les transporteurs et sur de longues périodes de conservation. Préservez le contexte du transporteur et votre identifiant d’envoi, et documentez la gestion des remplacements et des numéros corrigés.
Surveillez séparément l’enregistrement et les mises à jour de suivi
La surveillance de l’API doit distinguer une défaillance d’intégration d’un envoi qui ne possède simplement aucun nouvel événement du transporteur. Ces situations nécessitent des responsables et des corrections différents.
Pour l’enregistrement, surveillez les nombres d’acceptations et de rejets, les catégories d’erreurs, les résultats incertains, le retard des nouvelles tentatives et la latence des réponses. Pour le suivi ultérieur, surveillez séparément la réception des mises à jour ou les échecs de récupération. Évitez de définir des seuils d’alerte numériques avant de comprendre le trafic normal et les limites opérationnelles documentées du fournisseur.
Un contrôle pratique en production doit répondre aux questions suivantes :
- Chaque envoi en attente de suivi possède-t-il un enregistrement d’enregistrement ?
- Chaque enregistrement accepté peut-il être rattaché au bon colis ?
- Les éléments rejetés sont-ils transmis à une personne capable de corriger les données sous-jacentes ?
- Les requêtes incertaines sont-elles réconciliées plutôt qu’abandonnées ou réessayées indéfiniment ?
- Les statuts visibles par les clients sont-ils dérivés des événements d’envoi plutôt que de l’acceptation de l’enregistrement ?
- Les identifiants et les informations personnelles inutiles sont-ils exclus des journaux ?
Pour les opérations e-commerce, le relais opérationnel est aussi important que l’appel API. Les développeurs doivent être responsables des échecs de transport et d’analyse ; les équipes d’expédition ou d’exécution doivent pouvoir examiner les étiquettes incorrectes, les correspondances de transporteurs et les informations d’envoi manquantes.
FAQ
Puis-je enregistrer un numéro de suivi avant le premier scan du transporteur ?
L’enregistrement et les scans du transporteur sont des événements distincts. Un service peut accepter un numéro avant que les événements de suivi soient disponibles, sous réserve de ses règles de validation. N’interprétez pas l’acceptation comme la preuve que le transporteur a reçu le colis.
Dois-je toujours fournir un code transporteur ?
Cela dépend du comportement de détection documenté par l’API et de l’envoi concerné. Lorsque le transporteur est connu, un identifiant explicite et correctement associé peut réduire l’ambiguïté. Lorsqu’il est inconnu, utilisez la méthode de détection automatique documentée plutôt que d’inventer une valeur de transporteur.
Pourquoi l’API a-t-elle renvoyé un succès HTTP alors qu’un envoi a échoué ?
La requête HTTP peut réussir alors que l’application rejette un élément individuel. Lisez le résultat global de l’application ainsi que les résultats au niveau de l’envoi. Cette distinction est particulièrement importante pour les requêtes par lots.
Que dois-je faire lorsqu’une demande d’enregistrement expire ?
Traitez le résultat comme incertain. Le serveur peut avoir traité la requête avant l’échec de la connexion. Vérifiez le comportement documenté du fournisseur concernant les doublons ainsi que les méthodes disponibles de consultation de l’enregistrement ou du suivi, puis réconciliez ou réessayez dans le cadre d’une politique limitée.
L’enregistrement configure-t-il automatiquement les notifications de suivi ?
Ne le supposez pas. L’enregistrement, la récupération du suivi et la configuration des webhooks sont des aspects distincts de l’intégration. Vérifiez la documentation pertinente et testez le parcours complet des mises à jour avant de vous y fier pour les notifications clients.
Sources
- Documentation de l’API 17TRACK — référence pour les points de terminaison d’enregistrement, l’authentification, les champs de requête, les identifiants de transporteurs, les schémas de réponse et la gestion des erreurs. Faites correspondre les détails de l’implémentation à la version d’API déployée.
- Présentation de l’API de suivi 17TRACK — point de départ officiel pour le produit d’API de suivi et les ressources d’intégration destinées aux développeurs.


