L’API d’abonnement aux numéros de suivi à la visibilité intégrée avancée permet aux abonnés de la visibilité intégrée avancée d’associer des numéros de suivi à un projet de webhook à l’aide de points de terminaison de l’API. La fonctionnalité d’association des numéros de suivi prend en charge deux méthodes de traitement :

• Association des numéros de suivi – synchrone renvoie les résultats du traitement dans la même réponse HTTP. Cette option convient le mieux aux applications qui nécessitent une confirmation immédiate lors de l’association d’un plus petit nombre de numéros de suivi. 
• Association des numéros de suivi — Asynchrone soumet la demande de traitement en arrière-plan et renvoie un identifiant de tâche qui peut être utilisé pour récupérer l’état et les résultats du traitement plus tard. Cette option est particulièrement adaptée au traitement de lots plus importants 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.

Note :

• Vous devez disposer d’un accès administrateur ou contributeur à votre projet Visibilité intégrée avancée.
• Pour en savoir plus sur la visibilité intégrée avancée et ses fonctionnalités, consultez la page de documentation Visibilité intégrée avancée.

L’API d’abonnement aux numéros de suivi de visibilité intégrée avancée offre les avantages suivants :

• Vous pouvez facilement associer, mettre à jour et gérer les numéros de suivi pour votre projet de webhook de visibilité intégrée avancée en utilisant les points de terminaison de l’API.
• Associez plusieurs numéros de suivi dans une seule demande d’API au lieu de traiter chaque numéro de suivi individuellement.
• Choisissez entre un traitement synchrone pour obtenir des résultats immédiats ou un traitement asynchrone pour des opérations par lots plus importantes.

Utilisez les points de terminaison suivants pour gérer votre projet Visibilité intégrée avancée :

• Association des 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 des numéros de suivi – Asynchrone : vous permet d’associer des numéros de suivi à un webhook et d’utiliser ultérieurement le jobId retourné pour vérifier le statut de la tâche asynchrone ou télécharger les détails à l’aide des points de terminaison associés :  
  • Statut des tâches — Numéros de suivi
  • Détails de la tâche — Numéros de suivi

Ces API sont disponibles dans l’aperçu de votre projet de visibilité intégrée avancée.

Ces API sont accessibles uniquement depuis l’aperçu 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 des numéros de suivi synchrones et asynchrones.
 

Utilisez le point de terminaison synchrone lorsque vous avez besoin d’une confirmation immédiate pour de petits lots de numéros de suivi. Utilisez le point de terminaison asynchrone lors du traitement de lots plus importants 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 de visibilité intégrée avancée 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 les demandes contenant jusqu’à 150 numéros de suivi.

Entrée requise : 

• subscriptionID
• trackingNumber

Avantages

Le point de terminaison synchrone offre les avantages suivants :

• Résultats du traitement immédiats
• Informations détaillées sur les réussites et les échecs dans une seule réponse
• Prise en charge d’un maximum de 150 numéros de suivi par demande
• Validation de la demande et application des règles métier avant le traitement
• Codes d’erreur lisibles par machine et messages d’erreur descriptifs
• Identifiants de transaction pour le suivi des demandes et le dépannage

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

• Nécessite un subscriptionID valide et actif
• Autoriser un seul subscriptionID par demande
• Nécessite un trackingNumber
• S’assure que les numéros de suivi respectent les exigences de formatage de FedEx, y compris la limite maximale de 6 à 22 chiffres pour les numéros de suivi

Les réponses d’erreur suivent une structure uniforme, avec le tableau errors[] contenant un code et un message pour faciliter l’analyse.

« erreurs » : [

{

« code » : « ERROR.CODE »,

« message » : « Message d’erreur descriptif »

}

L’association du numéro de transaction – le point de terminaison synchrone permet des succès partiels. Lorsque certains numéros de suivi échouent, l’API synchrone renvoie tout de même 200 OK et affiche les éléments suivants :

• failedTrackingNumbers
• Un message descriptif

{

« transactionId » :

   « xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx »,

  « output » : {

  « failedTrackingNumbers » :

         [ « XXXXX »,

         « YYYYY »

         ],

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

      }

    }

Consultez les sections sur les règles métier pour obtenir plus de détails et connaître les règles supplémentaires.

Utilisez ce point de terminaison pour soumettre un ou plusieurs numéros de suivi enregistrés afin qu’ils soient traités en arrière-plan.

La demande renvoie un identifiant de tâche que vous pouvez utiliser avec le point de terminaison État de la tâche du numéro de suivi pour surveiller le traitement et avec le point de terminaison Détails de la tâche du numéro de suivi pour télécharger les résultats du traitement une fois la tâche terminée.

Entrée requise :

• Action
• Détails du numéro de suivi

Vous pouvez associer jusqu’à 1 000 numéros de suivi dans une seule demande.

Avantages

Le point de terminaison asynchrone offre les avantages suivants :

• Prise en charge de soumissions par lots importantes pouvant contenir jusqu’à 1 000 numéros de suivi
• Permet le traitement en arrière-plan des demandes de longue durée
• Permet la surveillance de l’état des tâches et le téléchargement des rapports de traitement
• Élimine les problèmes liés aux délais d’expiration des demandes 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 en file d’attente), ou le statut de toutes les tâches soumises.

Les renseignements requis pour cette demande sont les suivants :

• jobID – Indiquez l’identifiant de la tâche dont vous souhaitez récupérer l’état.

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

La réponse positive à cette requête renverra l’identifiant de la tâche (jobID), l’état actuel de la tâche, ainsi que les horodatages de création et de fin de la tâche. La réponse affichera le statut actuel des tâches. Elle contiendra également des messages de réussite, des erreurs ou des avertissements afin que les utilisateurs puissent les consulter et, le cas échéant, résoudre les problèmes.

• Si le statut de la tâche s’affiche comme COMPLETED (TERMINÉ), cela signifie que tous les numéros de suivi ont été validés et traités avec succès.
  • Le statut COMPLETED (TERMINÉ) indique que les numéros de suivi ont été validés et traités correctement, mais cela ne signifie pas que tous les numéros de suivi ont été ajoutés avec succès au projet Visibilité intégrée avancée.
  • Pour les tâches ayant plusieurs numéros de suivi, l’état peut être considéré comme TERMINÉ, même si certains numéros ne s’associent pas au projet et que d’autres réussissent. Pour confirmer l’état de chaque numéro de suivi dans la demande d’association originale, téléchargez le rapport de lot.

Remarque : Si le statut de la tâche s’affiche comme ÉCHOUÉ, cela signifie que, pour diverses raisons ou en raison d’échecs critiques, la demande n’a pas pu être traitée et l’utilisateur devra la soumettre de nouveau.

Le tableau suivant montre les états des tâches et leurs descriptions respectives :

Utilisez ce point de terminaison pour télécharger le rapport JSON d’une tâche asynchrone ayant le statut COMPLETED (TERMINÉE).

Voici les renseignements d’entrée requis pour cette demande :

• jobID – Indiquez l’identifiant de la tâche dont vous souhaitez récupérer l’état. Un ID de tâche est obligatoire pour ce point de terminaison.

Note :

• Vous ne pouvez télécharger qu’un seul rapport de tache asynchrone à la fois.
• Si la tâche n’est pas COMPLETED (TERMINÉE) et que vous tentez de télécharger le rapport, un message d’erreur s’affichera.

La réponse positive à cette requête vous fournira le rapport de la tâche au format JSON.

Règles métier communes

• Il n’y a aucune limite au nombre total de numéros de suivi pouvant être associés à un projet de visibilité intégrée avancée.
• Les numéros de suivi associés à un projet de visibilité intégrée avancée sont dissociés 40 jours après leur association réussie au webhook.
• Les informations de suivi sécurisées, telles que l’adresse du destinataire, la signature du destinataire et les informations sensibles relatives à la livraison, ne sont pas disponibles par l’intermédiaire de l’API d’abonnement aux numéros de suivi.

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

• Maximum de 150 numéros de suivi par demande.
• Tous les numéros de suivi doivent utiliser le même ID d’abonnement.
• L’abonnement spécifié au webhook de visibilité intégrée avancée doit être valide et actif.
• Les demandes sont soumises à un délai d’expiration de 30 secondes.

Règles métier du point de terminaison asynchrone

• Maximum de 1 000 numéros de suivi par demande.
• L’état de la tâche et les détails de la tâche pour une demande asynchrone sont conservés pendant 90 jours après que les numéros de suivi ont été associés avec succès au webhook de Visibilité Intégrée Avancée.