Skip to main content
AccueilBlogGuidesVotre première requête à l’API de suivi : présentation d’un client REST avec Postman et Curl

Votre première requête à l’API de suivi : présentation d’un client REST avec Postman et Curl

17TRACK

Pour effectuer votre première requête vers l’API de suivi, configurez le point de terminaison, l’en-tête d’authentification et le corps JSON dans un client REST, envoyez la requête, puis examinez le statut HTTP ainsi que le corps de la réponse. Ce guide utilise l’API de suivi de 17TRACK pour présenter le même flux de travail dans Postman et curl : enregistrer un envoi, demander ses informations de suivi et vérifier si le résultat est prêt à être utilisé par votre application.

Votre première requête vers l’API de suivi : guide d’utilisation avec un client REST

L’objectif est un petit test d’intégration reproductible, et non un déploiement en production. Vous aurez besoin d’un identifiant d’API et d’un numéro de suivi que vous êtes autorisé à traiter. Les commandes ci-dessous utilisent le modèle de point de terminaison v2.2 ; confirmez la version du point de terminaison et les exigences propres à votre compte dans la documentation de l’API 17TRACK avant de les exécuter.

Comprendre ce que votre première requête doit accomplir

Une intégration de suivi des envois comporte deux aspects distincts : indiquer au service quel envoi suivre et récupérer les informations de suivi associées à cet envoi. Dans le flux de travail présenté ici, ces opérations correspondent à des requêtes distinctes. L’enregistrement ne signifie pas que le colis a déjà été acheminé, et un enregistrement réussi ne garantit pas que les événements du transporteur seront immédiatement disponibles.

Pour votre premier test, utilisez un seul envoi plutôt qu’un lot. Il sera ainsi plus facile d’isoler les erreurs d’authentification, les numéros de suivi invalides et l’interprétation de la réponse. Votre première étape utile n’est pas simplement : « J’ai reçu HTTP 200 ». C’est plutôt : « L’API a accepté l’opération demandée et je peux expliquer le résultat au niveau de l’envoi. »

Postman fournit une interface visuelle pour modifier les requêtes et examiner les réponses. curl rend le même échange HTTP reproductible depuis un terminal. Aucun des deux ne modifie les règles d’authentification de l’API, les données d’envoi ou le comportement de traitement. Utilisez l’outil qui vous aide à examiner plus clairement la requête, puis reproduisez la configuration fonctionnelle dans l’autre outil.

Préparer vos identifiants, votre envoi et les détails de la requête

Avant d’ouvrir l’un ou l’autre client, réunissez les éléments suivants :

  • Un identifiant d’API autorisé : obtenez-le via la configuration de votre compte API 17TRACK. Une session de suivi destinée aux consommateurs ne remplace pas un identifiant d’API.
  • Un véritable numéro de suivi : utilisez un envoi qui vous appartient ou auquel vous êtes autorisé à accéder. Pour tester des données de suivi réelles, un envoi récemment actif est généralement plus utile qu’un numéro inventé.
  • Le transporteur, s’il est connu : gardez son nom à disposition pour le diagnostic. Si un identifiant de transporteur est requis dans votre cas, utilisez la valeur et le champ définis dans la documentation de l’API au lieu de les deviner.
  • Le contrat actuel de la requête : confirmez la version de l’API, l’en-tête d’authentification, le schéma de la requête et les éventuelles restrictions du compte.
  • Un espace de travail sûr : évitez de placer des identifiants, des informations client ou des réponses de suivi complètes dans des dépôts publics, des captures d’écran ou des messages d’assistance partagés.

Les exemples de requêtes minimales utilisent les paramètres suivants :

ParamètreConfiguration d’exemple
URL de basehttps://api.17track.net/track/v2.2
Opération d’enregistrementPOST /register
Opération d’obtention des informations de suiviPOST /gettrackinfo
En-tête d’authentification17token: YOUR_API_TOKEN
Format du corpsContent-Type: application/json, avec un tableau JSON d’objets d’envoi

Conservez les numéros de suivi sous forme de chaînes. Leur conversion en type numérique peut supprimer les zéros initiaux ou modifier leur valeur. Le paramètre fictif YOUR_TRACKING_NUMBER ci-dessous doit être remplacé par votre véritable envoi de test ; il ne s’agit pas d’un numéro d’exemple fonctionnel.

Effectuer la requête d’enregistrement dans Postman

1. Créer un petit environnement de test

Dans Postman, créez un environnement comportant trois variables : base_url, tracking_token et tracking_number. Définissez base_url sur l’URL de base ci-dessus et saisissez vos identifiants ainsi que votre numéro d’envoi dans les deux autres variables. Sélectionnez cet environnement avant d’envoyer la requête.

Utilisez les contrôles de gestion des secrets disponibles dans Postman pour le jeton, et vérifiez ce que votre espace de travail partage ou synchronise. Masquer une valeur dans l’interface ne remplace pas le contrôle des personnes qui peuvent y accéder. N’exportez pas des identifiants renseignés avec une collection destinée à des collègues ou à une documentation publique.

2. Configurer la méthode, l’URL et les en-têtes

Créez une requête HTTP, sélectionnez POST et saisissez {{base_url}}/register comme URL. Dans l’onglet Headers, ajoutez :

17token: {{tracking_token}}
Content-Type: application/json

Dans cet exemple, l’identifiant doit figurer dans l’en-tête personnalisé 17token. Ne le remplacez pas par une configuration de jeton Bearer simplement parce qu’une autre API utilise ce modèle. Vérifiez également si les paramètres hérités de la collection introduisent un en-tête Authorization inattendu.

3. Ajouter le corps JSON

Ouvrez Body, choisissez raw, puis JSON. Saisissez :

[
  {
    "number": "{{tracking_number}}"
  }
]

Les crochets extérieurs sont importants : cette requête utilise un tableau, même s’il ne contient qu’un seul envoi. Utilisez des guillemets doubles, supprimez les virgules finales et n’ajoutez pas de commentaires au JSON. Si la documentation exige des informations supplémentaires pour votre transporteur ou votre envoi, ajoutez les champs documentés avant l’envoi.

4. Envoyer et examiner le résultat

Cliquez sur Send. Vérifiez d’abord si vous avez reçu une réponse HTTP. Une défaillance DNS, une erreur TLS, un problème de proxy ou un délai d’attente ne sont pas équivalents à une réponse indiquant que la requête est invalide. Examinez ensuite le corps de la réponse pour connaître le résultat de l’opération et les éventuelles informations d’acceptation ou de rejet au niveau de l’envoi.

Enregistrez la requête sous le nom « Register test shipment ». Notez le statut HTTP, le résultat de l’API et tout message d’erreur sans copier le jeton. Si l’enregistrement échoue, résolvez ce problème avant de continuer. Soumettre plusieurs fois une requête inchangée rend le diagnostic plus difficile et peut consommer les ressources du compte.

Reproduire la requête avec curl

Les commandes suivantes utilisent un shell de type POSIX, tel que Bash ou Zsh. PowerShell et l’invite de commandes Windows appliquent des règles différentes pour les guillemets et les variables. Dans PowerShell, utilisez curl.exe si nécessaire afin d’appeler l’exécutable curl plutôt qu’un alias propre au shell.

Définissez l’URL de base et chargez vos identifiants dans une variable d’environnement selon votre procédure habituelle de gestion des secrets :

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Une variable d’environnement évite d’inclure l’identifiant dans l’exemple réutilisable, mais elle ne constitue pas un système complet de gestion des secrets. Pour les tests locaux, évitez de saisir un véritable jeton dans une commande que l’historique du shell conservera. Pour l’automatisation, utilisez le coffre de secrets de votre plateforme et limitez les journaux.

Créez un fichier nommé shipment.json et remplacez le paramètre fictif par votre numéro de suivi de test :

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Envoyez la requête d’enregistrement :

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Cette commande enregistre le corps de la réponse dans register-response.json et affiche séparément le statut HTTP. Les délais de connexion et d’exécution totale sont des choix pour les tests locaux, et non des garanties du service 17TRACK. Ouvrez le fichier enregistré pour examiner le résultat de l’API ; la seule ligne de statut ne suffit pas.

curl peut terminer un transfert avec succès même lorsque le serveur renvoie une réponse HTTP d’erreur. À l’inverse, une défaillance du transport peut empêcher la réception d’une réponse exploitable de l’API. Dans vos scripts, traitez séparément le code de sortie de curl, le statut HTTP et le résultat au niveau de l’application.

Demander les informations de suivi de l’envoi

Après avoir confirmé l’enregistrement, dupliquez la requête Postman et remplacez l’URL par {{base_url}}/gettrackinfo. Conservez la méthode POST, l’en-tête d’authentification, le type de contenu et le corps de l’envoi. Enregistrez-la séparément afin de ne pas réenregistrer accidentellement l’envoi lorsque vous souhaitez récupérer ses données.

La requête curl équivalente est :

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Ne supposez pas qu’un envoi nouvellement enregistré renverra immédiatement un historique complet des événements. La disponibilité des données dépend de l’envoi et du traitement du service. Si les informations ne sont pas encore disponibles, suivez les instructions documentées de récupération et de mise à jour au lieu de réenregistrer continuellement le même numéro ou d’exécuter une boucle d’interrogation trop fréquente.

Lire la réponse sur trois niveaux

  1. Transport : le client s’est-il connecté et a-t-il reçu une réponse HTTP ?
  2. Opération : l’API a-t-elle accepté la requête et l’envoi individuel a-t-il réussi ?
  3. Informations sur l’envoi : les données renvoyées identifient-elles le colis prévu, et qu’établissent réellement son statut ou son historique d’événements ?

Utilisez le schéma officiel de la réponse pour localiser les champs de statut, de transporteur et d’événement. Maintenez la distinction entre un statut d’envoi normalisé et la description originale de l’événement fournie par le transporteur. Une recherche réussie ne prouve pas la livraison, et l’absence d’événements ne prouve pas qu’un colis est perdu.

Lorsque vous stockez des horodatages, conservez les informations de fuseau horaire ou de décalage fournies. Évitez de trier des chaînes de dates brutes provenant de formats différents en supposant qu’elles représentent une séquence chronologique correcte. Distinguez également l’heure à laquelle votre application a récupéré un enregistrement de l’heure à laquelle l’événement d’expédition s’est produit.

Diagnostiquer les problèmes sans tout modifier en même temps

  • Aucune réponse : vérifiez le nom d’hôte, l’accès réseau, les paramètres du proxy, la configuration TLS et le délai d’attente local. Ne désactivez pas systématiquement la vérification des certificats.
  • Échec de l’authentification : confirmez que le jeton est actif, que l’en-tête 17token est présent et que l’environnement Postman sélectionné résout correctement la variable. Vérifiez la présence éventuelle d’espaces accidentels.
  • Requête invalide : vérifiez la version de l’API, le chemin de l’opération, la méthode POST, le type de contenu et la structure du tableau JSON par rapport à la documentation.
  • Envoi rejeté : lisez l’erreur propre à l’envoi. Vérifiez le numéro et les informations de transporteur requises au lieu de considérer chaque rejet comme un problème d’authentification.
  • Aucun événement de suivi : confirmez l’enregistrement et l’identité de l’envoi prévu. Vérifiez si des informations sur le transporteur sont nécessaires et si des mises à jour sont disponibles avant de réessayer.
  • Postman fonctionne mais curl échoue : comparez l’URL résolue, les en-têtes réels et les octets du corps. Les guillemets du shell et les variables d’environnement non définies sont des causes fréquentes de divergence entre les requêtes.

Modifiez une seule variable par test et conservez un bref relevé du résultat. Si vous inspectez la console de Postman ou utilisez la sortie détaillée de curl, traitez-la comme sensible : les en-têtes de requête peuvent révéler des identifiants. Masquez les secrets et les informations client avant de partager les diagnostics.

Savoir quand le guide est terminé

Vous avez effectué un premier test d’intégration significatif lorsque les deux clients envoient la requête prévue, que l’enregistrement est compris, que la récupération renvoie un résultat interprétable et que vous pouvez distinguer une défaillance de l’API d’un envoi ne contenant aucune nouvelle information. Des codes de statut HTTP identiques ne suffisent pas à établir que les deux clients se sont comportés de manière identique.

Avant d’intégrer le flux de travail à une application, conservez les identifiants sur le serveur, validez les entrées et utilisez une gestion structurée des erreurs. Consultez les limites de débit, les limites de lots, les recommandations de nouvelle tentative et les options de diffusion des mises à jour documentées pour votre compte. Ne supposez pas qu’il est sûr de réessayer aveuglément un enregistrement après un délai d’attente : le serveur peut avoir traité la requête même si votre client n’a pas reçu la réponse.

Ajoutez des tests pour un identifiant invalide, un JSON mal formé, un numéro d’envoi invalide, un envoi déjà enregistré, des données de suivi indisponibles et un délai d’attente réseau. Chaque cas doit conduire à un résultat applicatif délibéré plutôt qu’à une exception non gérée ou à un statut trompeur présenté au client.

FAQ

Puis-je tester sans véritable numéro de suivi ?

Vous pouvez tester certains comportements de validation des requêtes avec une valeur invalide, mais cela ne vérifie pas le suivi d’un envoi. Pour tester de véritables événements, utilisez un envoi autorisé ou un scénario de test documenté si le service en fournit un. Ne supposez pas que des numéros d’exemple arbitraires appartiennent à un environnement sandbox.

Pourquoi une réponse HTTP 200 contient-elle encore un échec ?

Le statut HTTP et les résultats de l’application décrivent des niveaux différents. Un serveur peut recevoir et traiter correctement une requête tout en indiquant qu’un envoi individuel a été rejeté. Lisez le corps de la réponse et le résultat documenté au niveau de l’envoi, et pas uniquement le statut HTTP.

Pourquoi POST est-il utilisé pour récupérer les informations de suivi ?

Utilisez la méthode indiquée par le contrat du point de terminaison. Cet exemple de récupération accepte les identifiants d’envoi dans le corps d’une requête JSON via POST. Le remplacer par GET parce que l’opération lit des données ne respecte pas la requête documentée.

Dois-je placer le jeton d’API dans le JavaScript du navigateur ?

N’intégrez pas un identifiant d’API privé dans du code frontend distribué publiquement. Faites transiter les requêtes par un backend autorisé qui protège l’identifiant, valide les entrées et contrôle les informations d’envoi auxquelles chaque utilisateur peut accéder.

Ai-je besoin de Postman et de curl pour la production ?

Non. Ce sont des outils utiles pour les tests et le diagnostic. Votre application de production peut utiliser un client HTTP approprié. Conservez une requête Postman ou une commande curl nettoyée comme référence reproductible, sans jeton actif ni données client superflues.

Sources

  • 17TRACK API documentation — référence pour l’authentification, les contrats des points de terminaison, les champs des requêtes, l’interprétation des réponses et les exigences d’intégration.
  • Postman documentation: Send API requests — configuration des requêtes et inspection des réponses.
  • Postman documentation: Variables — configuration des requêtes à l’aide de variables.
  • curl manual — options de commande pour les en-têtes, les corps de requête, les délais d’attente, les réponses enregistrées et l’affichage du statut HTTP.