1. Qu'est-ce que le suivi logistique ?

Le suivi logistique est un outil essentiel pour surveiller le processus de transport, permettant aux utilisateurs de suivre les itinéraires de transport, les exceptions et les changements de statut majeurs.

Les principales fonctionnalités de l'API de suivi sont les suivantes :

• Surveillance automatique : une fois qu'un numéro de suivi est enregistré, il est surveillé automatiquement et les résultats de la requête sont transmis sans consommer de quotas supplémentaires. Remarque : cette fonctionnalité fonctionne de manière asynchrone et ne convient pas aux pages Web frontales, aux mini-programmes ou aux applications.
• Capacité au niveau de l'entreprise : l'API de suivi offre des capacités de traitement de données au niveau de l'entreprise, permettant l'enregistrement de 400 000 numéros de suivi par heure.
• Intégration des transporteurs mondiaux : l'API de suivi prend en charge l'intégration avec plus de 2 000 transporteurs mondiaux, fournissant des méthodes d'appel, des structures de réponse et des nœuds d'état unifiés, réduisant ainsi efficacement les coûts de développement.
• Meilleures pratiques de gestion des données : il est fortement recommandé de stocker les informations logistiques sur votre serveur ou service de stockage.
• Identification unique des données : chaque élément de données est identifié de manière unique grâce à la combinaison du numéro de suivi + du transporteur.
• Présentation du processus opérationnel : le processus opérationnel comprend l'abonnement aux expéditions > le suivi périodique > l'examen des changements de statut des expéditions > la transmission des résultats.

2. Avant utilisation

2.1 Créer un compte 17TRACK

Les comptes API ne sont pas spécifiques à un environnement. Il est recommandé de conserver des comptes API distincts pour les environnements de test et de production afin de garantir les configurations spécifiques à l'environnement et l'intégrité des données. Veuillez visiter 17TRACK-Api pour ouvrir un compte.

 

2.2 Numéro de suivi et code transporteur

• Visitez 17TRACK pour vérifier la disponibilité du numéro de suivi préparé
• Visitez Transporteurs pour vérifier les transporteurs pris en charge
• Qu'est-ce qu'un code transporteur ? Le code transporteur est une spécification de paramètre développée spécifiquement pour être utilisée avec l'API de suivi. Vous trouverez plus d'informations sur Code transporteur. Par exemple, le code transporteur pour USPS est 21051.

3. Guide d'intégration

3.1 Intégration de systèmes non tiers

Utilisateur cible

Le guide d'intégration suivant est spécifiquement destiné aux principaux prestataires logistiques, commerçants, prestataires de services et fournisseurs de systèmes qui disposent de leurs propres systèmes propriétaires et équipes de développement informatique.

Étape 1

(Pour un test rapide, vous pouvez vérifier le push via https://webhook.site)

1. Assurez-vous que votre serveur est accessible depuis le réseau public pour recevoir les mises à jour de suivi. Cela peut nécessiter d'ajuster les configurations de votre pare-feu et de votre passerelle pour autoriser les connexions entrantes depuis les serveurs de 17TRACK.
2. Développez une interface capable de recevoir des informations de suivi et assurez-vous qu'elle peut gérer plusieurs requêtes simultanées. Il est conseillé de distribuer les données à l'aide de services indépendants tels que des files d'attente ou des caches pour une meilleure évolutivité.
3. Implémentez la vérification de signature dans votre interface de réception d'informations pour confirmer l'authenticité et l'intégrité des données reçues de 17TRACK. Reportez-vous à Vérifier la signature pour obtenir des conseils. Un exemple de code est fourni ci-dessous :

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

    String src = requestText + "/" + key;

    MessageDigest md = MessageDigest.getInstance("SHA-256");
    byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

    BigInteger number = new BigInteger(1, hash);
    StringBuilder hexString = new StringBuilder(number.toString(16));
    while (hexString.length() < 64) {
        hexString.insert(0, '0');
    }
    return hexString.toString();
}

 

Étape 2

1. Obtenez la clé API en vous connectant et en visitant la page des paramètres API sur Api-Settings.
2. Pour configurer l'interface de réception des données, connectez-vous et accédez à la page des paramètres API sur Api-settings. Saisissez ensuite l'URL de l'interface dans la section WebHook.

Étape 3

1. Appelez l'interface d'enregistrement (/register) pour vous abonner aux numéros de suivi. Il est recommandé de transmettre l'ID de données dans le système d'entreprise via une balise pour faciliter l'utilisation future des résultats push. (Référence d'interface : Register Tracking Number)

Étape 4

1. Surveillez le fonctionnement de l'interface de réception des informations. Pour garantir que les résultats de suivi sont utilisés efficacement et en temps opportun par l'entreprise, veuillez noter : que les données peuvent être continuellement poussées dans des états simultanés, chaque poussée contenant l'ensemble de données complet. Si la réception normale échoue et qu'un code d'état temporaire autre que 200 est renvoyé, 17TRACK fournit des poussées compensatoires, comme détaillé ici : comment fonctionne la poussée
   
   Si les résultats de suivi ne peuvent pas être trouvés, cela peut être dû aux scénarios suivants :
   • Le suivi est en cours. (Dans des circonstances normales, les résultats de suivi initiaux devraient être disponibles dans un délai d'une minute, le suivi ultérieur étant effectué 3 à 4 fois toutes les 24 heures jusqu'à la livraison.)
   • Numéro de suivi incorrect. Dans ce cas, appelez l'interface Supprimer le suivi (/deletetrack) puis réabonnez-vous.
   • Opérateur incorrect. Dans ce cas, appelez l'interface Changer d'opérateur (/changecarrier) pour mettre à jour l'opérateur.
   • Une anomalie dans l'interface du transporteur.
   • Les opérateurs n'ont pas mis à jour les données de suivi.
   • Des paramètres de suivi supplémentaires sont manquants. Lors de l'abonnement, il est nécessaire d'inclure des paramètres de suivi supplémentaires pour certains opérateurs, tels que les numéros de téléphone portable et les codes postaux.
   • Les opérateurs n'ont pas mis à jour leurs données pendant 30 jours consécutifs. Dans ce cas, 17TRACK arrêtera automatiquement le suivi.

3.2 Intégration de systèmes tiers

Utilisateur cible

Le guide d'intégration suivant est conçu pour les prestataires logistiques de petite et moyenne taille et les commerçants de taille moyenne qui utilisent des systèmes ERP, TMS, WMS et CRM tiers

Étape 1

(Ne serait-ce que pour un test rapide, vous pouvez vérifier le push via https://webhook.site)

1. Veuillez confirmer auprès du fournisseur du système si le système actuel prend en charge la réception des données de suivi push via la méthode Webhook. [Différent des systèmes développés en interne]
2. Veuillez confirmer auprès du fournisseur du système si une solution alternative est disponible au cas où le push n'est pas pris en charge : appelez l'interface gettrackinfo (/gettrackinfo) pour récupérer les données à intervalles réguliers. (Remarque : cette méthode ne peut pas garantir la même efficacité de retour de données que la méthode push et n'est pas non plus recommandée par 17TRACK.) [Différent des systèmes développés en interne]
3. Veuillez confirmer auprès du fournisseur du système si l'accès à l'API 17TRACK est pris en charge. Si cela est pris en charge, confirmez si la version intégrée actuelle répond aux exigences de l'entreprise. Dans le cas contraire, veuillez négocier avec le fournisseur du système pour intégrer une autre version. [Différent des systèmes développés en interne]
4. Si le push est pris en charge, complétez la logique de vérification de signature dans l'interface de réception d'informations pour vous assurer que la source d'informations est sûre et valide. Veuillez vous référer à Vérifier la signature, l'exemple de code est le suivant :

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

   String src = requestText + "/" + key;

   MessageDigest md = MessageDigest.getInstance("SHA-256");
   byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

   BigInteger number = new BigInteger(1, hash);
   StringBuilder hexString = new StringBuilder(number.toString(16));
   while (hexString.length() < 64) {
       hexString.insert(0, '0');
   }
   return hexString.toString();
}

Étape 2

1. Obtenez la clé API : connectez-vous à la console API, récupérez la clé sur la page Paramètres et fournissez-la au fournisseur système responsable de l'intégration. (Voir Paramètres API)
2. Ignorez cette étape si le fournisseur système ne prend pas en charge la méthode push. Si c'est le cas, contactez le fournisseur système pour lui fournir l'URL de l'interface push. (Voir Paramètres API)

Étape 3

1. Appelez l'interface d'enregistrement (/register) pour vous abonner aux numéros de suivi. Il est recommandé au fournisseur du système de transmettre l'ID de données dans le système d'entreprise via une balise pour faciliter l'utilisation future des résultats push. (Référence d'interface : Register Tracking Number)

Étape 4

1. Veuillez vous connecter au système que vous utilisez et examiner les résultats dans le module de suivi. Si nécessaire, demandez de l'aide et des réponses au service client du fournisseur du système.
2. Surveillez le fonctionnement de l'interface de réception des informations. Pour garantir que les résultats de suivi sont utilisés en temps opportun et efficacement par l'entreprise, veuillez noter : que les données peuvent être continuellement poussées dans des états simultanés, chaque poussée contenant l'ensemble de données complet. Dans les cas où la réception normale échoue et qu'un code d'état temporaire non 200 est renvoyé, 17TRACK fournit des poussées compensatoires, comme détaillé ici : comment fonctionne la poussée

Wenn keine Tracking-Ergebnisse gefunden werden können, kann dies folgende Gründe haben:

• Das Tracking läuft. (Unter normalen Umständen sollten die ersten Tracking-Ergebnisse innerhalb von 1 Minute verfügbar sein, wobei das nachfolgende Tracking bis zur Zustellung 3 bis 4 Mal alle 24 Stunden durchgeführt wird.)
• Falsche Tracking-Nummer. Rufen Sie in diesem Fall die Schnittstelle zum Löschen von Trackings (/deletetrack) auf und abonnieren Sie dann erneut.
• Falscher Spediteur. Rufen Sie in diesem Fall die Schnittstelle zum Ändern von Spediteuren (/changecarrier) auf, um den Spediteur zu aktualisieren.
• Eine Anomalie in der Schnittstelle des Spediteurs.
• Spediteure haben die Tracking-Daten nicht aktualisiert.
• Zusätzliche Tracking-Parameter fehlen. Beim Abonnieren müssen für bestimmte Spediteure zusätzliche Tracking-Parameter angegeben werden, z. B. Handynummern und Postleitzahlen.
• Spediteure haben ihre Daten 30 Tage in Folge nicht aktualisiert. In diesem Fall stoppt 17TRACK das Tracking automatisch.

4. Versionen

Hauptversionen

Difference	V1.0	V2.0 (May 2022)
Request Address	https://api.17track.net/track/v1	https://api.17track.net/track/v2
Registration interface (/register) simplifies auto-recognition operations	{ carrier : null , auto_detection : true }	{ carrier : null }
Simplified signature verification	TRACKING_STOPPED/ {"number":"RM101474005CN", "carrier":3011,"tag":""} /6A8D7CFC3F7A41149E0A4EE8ABD0DD8A	{"event":"TRACKING_UPDATED", "data":{"number":"RR123456789CN", "carrier":3011,"tag":null}} /123456ABCDEF
Response structuring + node semantics	Not supported	Supported
Independent query additional parameters	Used in conjunction with a tracking number	Independent parameter
Origin and Destination	Not supported	Supported
Timeliness information	Not supported	Supported
Status	7 status	9 main status, 27 sub-status
Attachment Information	Not supported	Weight, volume, etc. (if supported by the carrier).
Carrier information	Not supported	Name, alias, official phone number, official website, etc.
Translation of events	Not supported	8 languages supported

Unterversionen

v2.1 (Aktualisiert im August 2023):

1. 3 Freigabe-Unterzustände hinzugefügt.
2. Ereignisstatusknoten hinzugefügt.
3. Die Registrierungsschnittstelle unterstützt Bestellnummer- und Notizparameter.
4. Bestellnummer, Zeitlimit und andere Informationen zur Gettracklist-Schnittstelle hinzugefügt.

v2.2 (Aktualisiert im Oktober 2023):

1. Die Rohinformationsstruktur für den Zeitpunkt des Logistikereignisses integrieren.