Skip to main content
AccueilBlogGuidesComment valider les numéros de suivi avant de les soumettre à l’API : 7 règles à suivre

Comment valider les numéros de suivi avant de les soumettre à l’API : 7 règles à suivre

17TRACK

Validez un numéro de suivi par étapes avant de l’envoyer à une API de suivi : normalisez la saisie, vérifiez sa structure de base, confirmez le contexte du transporteur, appliquez une somme de contrôle uniquement lorsque le transporteur en documente une, et rejetez les valeurs manifestement dangereuses ou incomplètes. Ne vous fiez pas à une seule expression régulière universelle. Les formats des numéros de suivi varient selon le transporteur, le service, le pays et le type d’expédition. Un validateur efficace doit donc empêcher les requêtes incorrectes sans bloquer les numéros légitimes utilisant un format inhabituel.

Comment valider les numéros de suivi avant l’envoi à une API : 7 règles

Ce guide s’adresse aux développeurs et aux équipes opérationnelles qui intègrent le suivi des expéditions dans un système de gestion des commandes, un flux de travail d’entrepôt, un portail client ou une application e-commerce. L’objectif n’est pas de prouver qu’un colis existe avant son envoi. La validation syntaxique et la validation du statut de l’expédition sont deux étapes distinctes.

Ce que la validation peut confirmer — et ce qu’elle ne peut pas confirmer

Un validateur préalable à l’envoi peut identifier les problèmes courants de saisie, comme une valeur vide, des espaces accidentels, des caractères non pris en charge, une longueur excessive ou un numéro de suivi placé dans le mauvais champ. Il peut également identifier un transporteur probable lorsque celui-ci est connu et que son format est documenté.

Il ne peut normalement pas confirmer qu’un numéro correspond à une expédition réelle, que le colis a été accepté par un transporteur ou que le numéro est actuellement traçable. Ces questions nécessitent une recherche auprès du transporteur ou de la plateforme de suivi. Un numéro peut réussir le contrôle de format tout en étant inutilisé, subtilement mal saisi, expiré ou associé à un autre service.

Les sept règles

1. Normaliser la valeur sans en modifier le sens

Les utilisateurs et les systèmes en amont ajoutent souvent des espaces au début ou à la fin, des sauts de ligne, des espaces insécables ou des caractères de mise en forme. Normalisez-les de manière sûre avant la validation. Une première étape courante consiste à supprimer les espaces environnants et à convertir les espaces non imprimables en espaces ordinaires. Si le format documenté du transporteur autorise les espaces internes ou les traits d’union, déterminez s’il faut les supprimer pour la requête API ou conserver la valeur d’origine pour l’affichage et l’audit.

Lorsque cela est possible, conservez deux valeurs : la saisie d’origine et une valeur canonique. La première aide les équipes d’assistance à analyser les problèmes de qualité des données ; la seconde est utilisée pour la validation et l’envoi. Évitez les transformations susceptibles de modifier les identifiants. Ne convertissez pas automatiquement les lettres en chiffres, ne remplacez pas les caractères ambigus et ne supprimez pas toute la ponctuation, sauf si le transporteur concerné ou la documentation de l’API prend explicitement ce comportement en charge.

La gestion d’Unicode mérite une attention particulière. Un caractère visuellement similaire provenant d’un autre alphabet peut ne pas être accepté par une API, même s’il ressemble à une lettre ou à un chiffre ASCII. Limiter la valeur canonique au jeu de caractères autorisé par l’intégration sélectionnée peut éviter des erreurs déroutantes en aval.

2. Rejeter les valeurs qui échouent aux contrôles structurels de base

Avant d’appliquer une logique spécifique au transporteur, vérifiez si la valeur est présente et plausible. Les contrôles utiles comprennent les longueurs minimale et maximale, les classes de caractères autorisées et la présence éventuelle uniquement d’espaces ou d’un espace réservé tel que « N/A », « TBD » ou « test ». Les limites exactes doivent provenir du contrat de l’API ou de la documentation du transporteur. N’inventez pas une longueur maximale universelle simplement parce que la plupart des exemples sont courts.

Un contrôle structurel doit être volontairement prudent. Par exemple, une règle qui n’autorise que les chiffres rejettera des identifiants alphanumériques valides. Une règle qui impose une longueur fixe peut rejeter des variantes de service ou des formats internationaux. Utilisez des contrôles génériques pour détecter les erreurs évidentes, puis appliquez des contrôles plus précis uniquement lorsque le transporteur et le service sont connus.

Validez également le type de données à la frontière de l’application. Un numéro de suivi doit généralement être traité comme une chaîne de caractères, et non comme un entier. La conversion numérique peut supprimer les zéros initiaux et créer des problèmes de précision dans les systèmes utilisant des types numériques à largeur fixe. Conservez la valeur exactement sous forme de chaîne après la normalisation approuvée.

3. Utiliser le contexte du transporteur plutôt que de deviner à partir du seul numéro

Un numéro de suivi sans transporteur est une donnée ambiguë. Différents transporteurs peuvent utiliser des longueurs, des préfixes ou des jeux de caractères qui se chevauchent, et un format plausible pour l’un peut être invalide pour l’autre. Si la commande, l’étiquette, le système d’entrepôt ou le compte marchand identifie déjà le transporteur, transmettez ce contexte avec le numéro de suivi chaque fois que l’API le permet.

Le contexte du transporteur améliore à la fois la validation et le routage. Il permet à votre application de sélectionner les règles de format pertinentes, réduit les correspondances erronées et rend les messages d’erreur plus utiles. Il empêche également qu’un résultat de détection automatique soit traité comme un fait lorsque plusieurs transporteurs pourraient accepter une valeur d’apparence similaire.

Si le transporteur est inconnu, utilisez une approche en deux étapes. Commencez par effectuer les contrôles de sécurité génériques. Ensuite, envoyez la valeur uniquement via un flux API prenant explicitement en charge la détection du transporteur, ou placez-la dans une file de vérification lorsque le processus métier exige un transporteur confirmé. N’attribuez pas silencieusement un transporteur sur la seule base d’un préfixe, sauf si cette correspondance est maintenue et documentée.

4. Appliquer les sommes de contrôle uniquement lorsque la règle est documentée

Certains systèmes d’identifiants utilisent des chiffres de contrôle, mais les numéros de suivi ne sont pas régis par une norme universelle unique de somme de contrôle. Une somme de contrôle peut détecter certaines erreurs de transcription, mais elle ne prouve pas qu’une expédition existe. Plus important encore, l’application du mauvais algorithme peut rejeter des numéros valides.

N’implémentez une somme de contrôle que lorsque le transporteur, le service, la spécification de l’étiquette ou la documentation de l’API concerné définit l’algorithme et la partie de la saisie couverte. Enregistrez la version de la règle et testez-la avec des exemples officiels. Si aucune règle faisant autorité n’est disponible, ignorez la somme de contrôle plutôt que de deviner à partir de tendances observées sur un petit échantillon.

Considérez le résultat d’une somme de contrôle comme un signal parmi d’autres, et non comme une décision de validation complète. Un échec peut justifier le blocage d’un envoi lorsque la règle fait autorité. Une réussite doit faire passer la valeur à l’étape suivante, et non la marquer comme une expédition active.

5. Séparer la validation du format de l’éligibilité de l’API

Une valeur peut être correctement formée tout en étant inadaptée au point de terminaison appelé. Avant l’envoi, consultez la documentation de l’API concernant les champs obligatoires, les identifiants de transporteurs acceptés, les exigences d’authentification, les limites de requêtes, le traitement des doublons et les éventuelles restrictions relatives aux types de services ou aux destinations. Il s’agit de règles d’intégration, et non de règles propres aux numéros de suivi, mais elles déterminent si un identifiant valide peut être traité avec succès.

La documentation de l’API de suivi 17TRACK montre pourquoi cette distinction est importante : les développeurs doivent suivre le modèle de requête de la plateforme et le comportement d’intégration pris en charge, plutôt que d’inventer une requête à partir de l’apparence d’un numéro de suivi. Consultez la documentation actuelle concernant les exigences des points de terminaison et le traitement des réponses à l’adresse Documentation de l’API 17TRACK.

Séparez les erreurs de validation des erreurs de transport et d’authentification. « Format de numéro de suivi invalide », « transporteur inconnu », « limite de débit atteinte » et « échec de l’autorisation » exigent des actions différentes. Un simple message générique « Échec de l’envoi » rend les nouvelles tentatives et les rapports opérationnels moins fiables.

6. Protéger l’API avec des entrées limitées, la déduplication et des nouvelles tentatives sûres

La validation constitue également une mesure de protection opérationnelle. Imposer une longueur d’entrée limitée avant l’analyse ou la journalisation. Rejetez les caractères de contrôle et les structures de données inattendues. Appliquez des limites de débit à la frontière de votre propre application afin qu’une importation défectueuse ne puisse pas générer une rafale incontrôlée de requêtes.

Dédupliquez avant l’envoi lorsque le processus métier n’exige pas de réenregistrement. Une clé de déduplication utile peut inclure le numéro de suivi canonique, le transporteur, le compte et le contexte de l’expédition. La clé correcte dépend de votre flux de travail ; le même identifiant peut parfois être réutilisé pour différents services ou enregistrements métier. Ne supposez donc pas que le numéro seul est toujours globalement unique.

Utilisez des nouvelles tentatives limitées avec temporisation progressive pour les échecs temporaires et évitez de recommencer pour les erreurs de validation permanentes. Enregistrez une clé d’idempotence ou un enregistrement d’envoi lorsque l’API et votre architecture le permettent. Consignez suffisamment d’informations pour résoudre les problèmes, mais protégez les identifiants, les données client et les informations sensibles relatives aux expéditions. Un validateur doit réduire les échecs répétés, et non créer un second problème de sécurité par une journalisation excessive.

7. Confirmer le résultat après l’envoi et surveiller les faux positifs

La dernière règle consiste à considérer la validation préalable comme une barrière, et non comme un verdict. Après acceptation de la requête, examinez la réponse de l’API et enregistrez son statut, l’identifiant de requête, l’association au transporteur et tout code d’erreur documenté. Si la plateforme accepte la requête mais ne peut pas encore renvoyer d’événements de déplacement, cela peut indiquer un délai de traitement plutôt qu’un numéro invalide.

Définissez une politique de suivi pour les numéros qui restent non résolus. La période doit tenir compte du transporteur, du service, de l’origine de l’expédition et de votre politique de service client ; aucune durée universelle ne permet de prouver qu’un numéro est invalide. Faites remonter les enregistrements sans transporteur, présentant des erreurs répétées du fournisseur, des résultats de transporteur contradictoires ou un statut ne correspondant pas à celui de la commande.

Mesurez les rejets à tort et les acceptations à tort. Une expression régulière stricte peut réduire les envois mal formés tout en bloquant par erreur des expéditions légitimes. Un validateur permissif peut augmenter le nombre de requêtes acceptées, mais créer du bruit en aval. Examinez les échantillons ayant échoué par transporteur et par service, mettez à jour les règles documentées via le contrôle de version et testez les modifications sur un ensemble représentatif de données de test respectant la confidentialité.

Séquence de validation pratique

Une implémentation maintenable peut suivre la séquence suivante :

  1. Vérifier que la requête contient une valeur de type chaîne et un enregistrement métier valide.
  2. Enregistrer la saisie d’origine, puis créer une forme canonique documentée.
  3. Rejeter les valeurs vides, les espaces réservés, les caractères dangereux et les valeurs en dehors de la plage de longueur documentée.
  4. Déterminer le transporteur à partir de données de commande fiables ou utiliser un flux de détection explicitement pris en charge.
  5. Appliquer les règles de syntaxe et de somme de contrôle propres au transporteur uniquement lorsqu’une documentation faisant autorité les prend en charge.
  6. Vérifier les exigences du point de terminaison, l’état des doublons et l’éligibilité aux nouvelles tentatives.
  7. Envoyer la requête, classer la réponse, enregistrer le résultat et planifier le suivi des enregistrements non résolus.

Cette séquence facilite les tests du validateur, car chaque décision repose sur une raison différente. Elle fournit également aux équipes opérationnelles des catégories d’échec exploitables au lieu d’une unique erreur opaque.

Liste de contrôle de l’implémentation

  • Stocker les numéros de suivi sous forme de chaînes afin de préserver les zéros initiaux.
  • Conserver séparément les valeurs d’origine et canoniques lorsque la traçabilité est importante.
  • Gérer les règles des transporteurs dans une configuration versionnée plutôt que dans des conditions codées en dur dispersées.
  • Tester les lettres, les chiffres, les traits d’union, les espaces, les caractères Unicode similaires, les espaces réservés et les longueurs limites.
  • Utiliser le contexte fiable du transporteur lorsqu’il est disponible.
  • Ne pas déduire l’existence d’une expédition d’une correspondance réussie avec une expression régulière.
  • Classer séparément les erreurs de validation permanentes et les erreurs temporaires d’API ou de réseau.
  • Consulter la documentation du fournisseur avant de modifier les règles de format ou la logique des requêtes.

FAQ

Une expression régulière peut-elle valider un numéro de suivi ?

Elle peut valider un modèle limité lorsque le format du transporteur et du service est connu. Elle ne peut pas prouver que le numéro existe, qu’il appartient à une expédition donnée ou qu’il est actuellement actif. Une expression universelle risque de créer des rejets à tort ou des correspondances erronées.

Faut-il envoyer à l’API un numéro qui semble invalide ?

Les valeurs clairement vides, dangereuses ou structurellement impossibles doivent normalement être bloquées avant l’envoi. Un format inhabituel mais par ailleurs sûr ne doit pas être rejeté uniquement parce qu’il ne correspond pas à une supposition interne. Consultez d’abord la documentation du transporteur ou utilisez un processus de détection pris en charge.

Une somme de contrôle suffit-elle à confirmer une expédition ?

Non. Une somme de contrôle, lorsqu’elle s’applique, vérifie uniquement que la valeur respecte une règle mathématique. Elle ne confirme pas qu’un transporteur a émis le numéro ni que le colis est entré dans le réseau.

Que faire lorsque le transporteur est inconnu ?

Effectuez les contrôles de sécurité génériques et utilisez, si elle est disponible, une procédure API prenant explicitement en charge la détection du transporteur. Sinon, conservez l’enregistrement pour enrichissement ou examen manuel au lieu de deviner silencieusement le transporteur.

Comment gérer les erreurs d’API ?

Classez-les selon leur cause. Corrigez les saisies mal formées et les valeurs de transporteur non prises en charge ; recommencez les tentatives pour les défaillances temporaires du réseau ou du fournisseur, avec des limites et une temporisation progressive ; et transmettez les erreurs d’authentification ou de quota au responsable de l’intégration. Enregistrez les détails de réponse nécessaires au diagnostic sans exposer de secrets.

Sources

  • Documentation de l’API 17TRACK — conseils relatifs aux requêtes et à l’intégration pour les développeurs d’API de suivi.
  • API de suivi 17TRACK — informations officielles sur le produit et cas d’utilisation de l’API.
  • Suivi USPS — point d’accès officiel au suivi du transporteur et conseils destinés aux clients.
  • Suivi UPS — point d’accès officiel au suivi du transporteur.