L’API Tracking Number Subscription Advanced Integrated Visibility permet aux abonnés Advanced Integrated Visibility d’associer des numéros de suivi avec un projet webhook AIV à l’aide des points de terminaisons de l’API.La fonctionnalité de numéro de suivi associé prend en charge deux méthodes de traitement :

• L’association de numéros de suivi – synchrone renvoie les résultats du traitement dans la même réponse HTTP. Cette option est la mieux adaptée aux applications qui nécessitent une confirmation immédiate lors de l’association d’un plus petit nombre de numéros de suivi.
• L’association de numéros de suivi – asynchrone soumet la demande pour un traitement en arrière-plan et renvoie un ID de tâche pouvant être utilisé pour récupérer l’état du traitement et les résultats plus tard. Cette option est la mieux adaptée au traitement de plus grands lots de numéros de suivi. 

Choisissez la méthode de traitement qui répond le mieux aux exigences de performance et de charge de travail de votre application.

Remarque :

• Vous devez disposer d’un accès administrateur ou contributeur pour votre projet Advanced Integrated Visibility.
• Pour plus d’informations sur Advanced Integrated Visibility et ses fonctionnalités, consultez la page Documentation Advanced Integrated Visibility.

L’API Tracking Number Subscription Advanced Integrated Visibility fournit les avantages suivants :

• Vous pouvez facilement associer, mettre à jour et gérer les numéros de suivi pour votre projet de webhook Advanced Integrated Visibility à l’aide des points de terminaison d’API.
• Associez plusieurs numéros de suivi dans une seule requête API au lieu de traiter chaque numéro de suivi individuellement.
• Choisissez entre le traitement synchrone pour des résultats immédiats ou le traitement asynchrone pour des opérations par lots plus importantes.

Utilisez les points de terminaison suivants pour gérer votre projet Advanced Integrated Visibility :

• Association de numéros de suivi – synchrone : vous permet d’associer des numéros de suivi à un webhook et de recevoir l’état final du traitement dans la même réponse HTTP.
• Association de numéros de suivi – asynchrone : vous permet d’associer des numéros de suivi à un webhook et d’utiliser le jobId renvoyé plus tard pour vérifier l’état de la tâche asynchrone ou télécharger les informations à l’aide des points de terminaison associés :     
  • Statut de tâche du numéro de suivi
  • Détails de tâche du numéro de suivi

Ces API sont disponibles à partir de la vue d’ensemble de votre projet Advanced Integrated Visibility.

Ces API ne sont accessibles qu’à partir de la vue d’ensemble de votre projet, comme illustré dans la capture d’écran ci-dessus.

Le tableau suivant résume les différences entre les points de terminaison d’association de numéros de suivi synchrones et asynchrones.
 

Utilisez le point de terminaison synchrone lorsque vous avez besoin d’une confirmation immédiate pour de plus petits lots de numéros de suivi. Utilisez le point de terminaison asynchrone lorsque vous traitez de plus grands lots qui ne nécessitent pas de réponse immédiate.

Utilisez ce point de terminaison pour associer un ou plusieurs numéros de suivi à un projet de webhook Advanced Integrated Visibility et recevoir les résultats du traitement dans la même réponse HTTP.

Ce point de terminaison est destiné aux applications qui nécessitent une confirmation immédiate et prend en charge des requêtes contenant jusqu’à 150 numéros de suivi.

Entrée requise : 

• subscriptionID
• trackingNumber

Avantages

Le point de terminaison synchrone offre les avantages suivants :

• Résultats de traitement immédiats
• Informations détaillées sur les succès et les échecs dans une seule réponse
• Prise en charge jusqu’à 150 numéros de suivi par demande
• Validation de la requête et application des règles de gestion avant le traitement
• Codes d’erreur lisibles par une machine et messages d’erreur descriptifs
• ID de transaction pour faciliter le suivi des requêtes et le diagnostic des erreurs

Le point de terminaison d’association de numéros de suivi synchrone applique plusieurs règles de validation, notamment :

• Exiger un subscriptionId valide et actif
• Autoriser un seul subscriptionId par requête
• Exiger un trackingNumber
• Garantir que les numéros de suivi respectent les exigences de formatage de FedEx, notamment la limite de 6 à 22 chiffres

Les réponses d’erreur suivent une structure cohérente avec un tableau errors[] contenant un code et un message pour faciliter le traitement.

"errors": [

{

"code": "ERROR.CODE",

"message": "Descriptive error message"

}

Le point de terminaison d’association de numéros de transaction – synchrone autorise les succès partiels. Lorsque certains numéros de suivi échouent, l’API synchrone renvoie tout de même un code 200 OK et affiche les éléments suivants :

• failedTrackingNumbers
• Un message de description

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Les numéros de suivi ci-dessous n’ont pas pu être téléchargés en raison d’erreurs de validation ou du système"

      }

    }

Consultez les sections relatives aux règles de gestion pour obtenir des détails et des règles supplémentaires.

Utilisez ce point de terminaison pour soumettre un ou plusieurs numéros de suivi souscrits à un traitement en arrière-plan.

La requête renvoie un identifiant de tâche (job ID) que vous pouvez utiliser avec le point de terminaison Statut de tâche de numéros de suivi pour suivre le traitement, et avec le point de terminaison Informations de tâche de numéros de suivi pour télécharger les résultats une fois la tâche terminée.

Entrée requise :

• Action
• Informations du numéro de suivi

Vous pouvez associer jusqu’à 1 000 numéros de suivi à une seule requête.

Avantages

Le point de terminaison asynchrone offre les avantages suivants :

• Prise en charge des envois par lots importants jusqu’à 1 000 numéros de suivi
• Permet de traiter les requêtes de longue durée en arrière-plan
• Permet le suivi du statut des tâches et le téléchargement de rapports de traitement
• Élimine les risques de dépassement de délai de requête (timeout) pour les charges de travail importantes

Utilisez ce point de terminaison pour obtenir le statut d’une tâche asynchrone (une ou plusieurs requêtes consécutives dans la file d’attente) ou le statut de toutes les tâches soumises.

Voici les informations de saisie requises pour cette requête :

• jobID : indiquez l’identifiant de tâche pour lequel vous souhaitez récupérer le statut.

Remarque : l’ID de tâche est une entrée facultative pour ce point de terminaison. Si vous ne le spécifiez pas, vous obtiendrez le statut de toutes les tâches soumises.

Une réponse positive à cette requête renverra l’ID de la tâche, le statut de cette dernière ainsi que l’horodatage de sa création et de sa fin. Elle indiquera également le statut actuel des tâches, mais aussi les messages de réussite, les avertissements ou les erreurs que les utilisateurs peuvent corriger, le cas échéant.

• Si le statut de la tâche indique « TERMINÉ », cela signifie que tous les numéros de suivi ont été validés et traités.
  • Le statut « TERMINÉ » indique que les numéros de suivi ont été validés et traités. Cela ne veut pas pour autant dire que tous les numéros de suivi ont été ajoutés au projet Advanced Integrated Visibility.
  • Pour les tâches comprenant plusieurs numéros de suivi, le statut peut être considéré comme COMPLETED même si certains numéros ne parviennent pas à s’associer au projet alors que d’autres réussissent. Pour confirmer le statut de chaque numéro de suivi dans la requête d’association d’origine, téléchargez le rapport de lot.

Remarque : si le statut de la tâche indique « ÉCHEC », la demande n’a pas pu être traitée pour des raisons diverses, ou une erreur s’est produite. L’utilisateur doit réessayer.

Le tableau suivant présente les statuts de tâche et leurs descriptions respectives :

Utilisez ce point de terminaison pour télécharger le rapport JSON d’une tâche asynchrone dont le statut indique « TERMINÉ ».

Voici les informations de saisie requises pour cette requête :

• jobID : indiquez l’identifiant de tâche pour lequel vous souhaitez récupérer le statut. L’ID de tâche est obligatoire pour ce point de terminaison.

Remarque :

• Vous ne pouvez télécharger qu’un seul rapport de tâche asynchrone à la fois.
• Si la tâche n’a pas le statut « TERMINÉ » et que vous essayez de télécharger le rapport, un message d’erreur s’affiche.

Une réponse sans erreur à cette demande renverra le rapport de la tâche au format JSON.

Règles métier courantes

• Il n’y a pas de limite au nombre total de numéros de suivi pouvant être associés à un projet Advanced Integrated Visibility.
• Les numéros de suivi associés à un projet Advanced Integrated Visibility sont dissociés 40 jours après avoir été correctement associés au webhook.
• Les informations de suivi confidentielles, telles que l’adresse du destinataire, la signature du destinataire et les informations sensibles relatives à la livraison, ne sont pas disponibles via l’API d’abonnement aux numéros de suivi.

Règles métier pour le point de terminaison synchrone

• Jusqu’à 150 numéros de suivi par demande.
• Tous les numéros de suivi doivent utiliser le même subscriptionId.
• L’abonnement au webhook Advanced Integrated Visibility indiqué doit être valide et actif.
• Les requêtes sont soumises à un délai d’expiration de 30 secondes.

Règles métier pour le point de terminaison asynchrone

• Jusqu’à 1 000 numéros de suivi par demande.
• Le statut et les informations d’une tâche correspondant à une demande asynchrone sont conservés pendant 90 jours après que les numéros de suivi ont été correctement associés au webhook Advanced Integrated Visibility.