La Tracking Number Subscription API de Advanced Integrated Visibility permite a los suscriptores de Advanced Integrated Visibility asociar números de seguimiento a un proyecto de webhook utilizando puntos de conexión de API. La función de vinculación de números de seguimiento admite dos métodos de procesamiento:

• Vinculación de un número de seguimiento – Sincrónico devuelve los resultados de procesamiento en la misma respuesta HTTP. Esta es la mejor opción para las aplicaciones que exigen una confirmación inmediata al asociar una cantidad menor de números de seguimiento. 
• Vinculación de un número de seguimiento – Asincrónico envía la solicitud de procesamiento en segundo plano y devuelve un ID de tarea que se puede utilizar para recuperar el estado y los resultados de procesamiento posteriormente. Esta es la mejor opción para procesar grandes lotes de números de seguimiento. 

Seleccione el método de procesamiento que mejor se adapte al rendimiento de su aplicación y requisitos de carga de trabajo.

Nota:

• Debe tener acceso como administrador o colaborador al proyecto de Advanced Integrated Visibility
• Para obtener más información sobre Advanced Integrated Visibility y todas sus funciones, visite la página Documentación de Advanced Integrated Visibility.

La Tracking Number Subscription API de Advanced Integrated Visibility ofrece las ventajas siguientes:

• Puede vincular, actualizar y gestionar fácilmente los números de seguimiento de su proyecto de webhook de Advanced Integrated Visibility con los puntos de conexión de la API.
• Vincule varios números de seguimiento en una sola solicitud de API en lugar de procesar los números de seguimiento de uno en uno.
• Elija entre procesamiento sincrónico para resultados inmediatos o asincrónico para operaciones con grandes lotes.

Use los siguientes puntos de conexión para gestionar su proyecto de Advanced Integrated Visibility:

• Vinculación de un número de seguimiento – Sincrónico: le permite vincular números de seguimiento con un webhook y recibir el estado de procesamiento final en la misma respuesta HTTP.
• Vinculación de un número de seguimiento – Asincrónico: permite vincular números de seguimiento con un webhook y usar el jobId devuelto posteriormente para consultar el estado de la tarea asincrónica o descargar detalles usando los puntos de conexión relacionados:    
  • Estado de una tarea de un número de seguimiento
  • Detalles de una tarea de un número de seguimiento

Estas API están disponibles en el resumen del proyecto de Advanced Integrated Visibility.

Solo podrá acceder a estas API desde el resumen de proyecto, como se muestra en la captura de pantalla anterior.

La tabla siguiente resume las diferencias entre los puntos de conexión de vinculación de números de seguimiento sincrónicos y asincrónicos.
 

Utilice el punto de conexión sincrónico cuando necesite una confirmación inmediata para lotes más pequeños de números de seguimiento. Utilice el punto de conexión asincrónico cuando tenga que procesar grandes lotes que no exigen una respuesta inmediata.

Utilice este punto de conexión para vincular uno o varios números de seguimiento con un proyecto de webhook de Advanced Integrated Visibility y recibir los resultados del procesamiento en la misma respuesta HTTP.

Este punto de conexión sirve para aplicaciones que exigen una confirmación inmediata y admite solicitudes con hasta 150 números de seguimiento.

Entrada requerida: 

• subscriptionID
• trackingNumber

Ventajas

El punto de conexión sincrónico proporciona las ventajas siguientes:

• Resultados de procesamiento inmediatos
• Información detallada sobre éxitos y fallos en una sola respuesta
• Admite hasta 150 números de seguimiento por solicitud
• Validación de solicitudes y aplicación de normas comerciales antes del procesamiento
• Códigos de error legibles por máquina y mensajes de error descriptivos
• ID de transacción para el seguimiento de solicitudes y la resolución de problemas

El punto de conexión Vinculación de un número de seguimiento – Sincrónico aplica varias normas de validación, entre las que se incluyen las siguientes:

• Se requiere un subscriptionId válido y activo
• Admite solo un subscriptionId por solicitud
• Requiere un trackingNumber
• Garantiza que los números de seguimiento cumplan los requisitos de formato de FedEx, como el límite máximo de números de seguimiento de 6 a 22 dígitos

Las respuestas de error siguen una estructura uniforme en la que errors[] contiene el código y el mensaje para facilitar el análisis.

"errors": [

{

"code": "ERROR.CODE",

"message": "Mensaje de error descriptivo"

}

El punto de conexión Vinculación de un número de transacción – Sincrónico admite éxitos parciales. Si fallan algunos de los números de seguimiento, la Synchronous API sigue devolviendo 200 OK y muestra lo siguiente:

• failedTrackingNumbers
• Un mensaje descriptivo

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Los siguientes números de seguimiento no se han podido subir por errores de validación o del sistema"

      }

    }

Consulte los apartados de normas comerciales para obtener más información y conocer más normas.

Utilice este punto de conexión para enviar uno o varios números de seguimiento suscritos para su procesamiento en segundo plano.

La solicitud devuelve un ID de tarea que puede utilizar con el punto de conexión Estado de la tarea del número de seguimiento para monitorizar el procesamiento y con el punto de conexión Detalles de la tarea del número de seguimiento para descargar los resultados de procesamiento una vez completada la tarea.

Entrada requerida:

• Acción
• Detalles de número de seguimiento

Puede vincular hasta 1.000 números de seguimiento en una sola solicitud.

Ventajas

El punto de conexión asincrónico proporciona las ventajas siguientes:

• Admite envíos de grandes lotes de hasta 1.000 números de seguimiento
• Permite que las solicitudes más prolongadas se procesen en segundo plano
• Permite la monitorización del estado de la tarea y la descarga de informes de procesamiento
• Elimina las dudas relacionadas con el tiempo de espera de la solicitud para grandes cargas de trabajo

Utilice este punto de conexión para averiguar el estado de una tarea asíncrona (con una o varias solicitudes consecutivas en cola) o el estado de todas las tareas enviadas.

Los datos necesarios para esta solicitud son:

• jobID : especifique el ID de la tarea cuyo estado pretende recuperar.

Nota: En este punto de conexión no es obligatorio introducir un ID de tarea. Si no indica ninguno, obtendrá el estado de todas las tareas enviadas.

La respuesta positiva a la solicitud le devolverá el ID de la tarea, su estado actual y la marca temporal de la creación y la finalización de dicha tarea. También le mostrará el estado actual de las tareas. Además, la respuesta también podrá incluir mensajes de confirmación, errores o advertencias para que los usuarios los vean y solucionen los problemas según corresponda.

• Si el estado de la tarea figura como COMPLETADO, significa que se han validado y procesado correctamente todos los números de seguimiento.
  • El estado de COMPLETADO significa que los números de seguimiento se han validado y procesado correctamente. Sin embargo, esto no significa que todos los números de seguimiento se han añadido correctamente al proyecto de Advanced Integrated Visibility.
  • Para tareas con varios números de seguimiento, el estado se puede considerar COMPLETADO, aunque haya números que no se puedan vincular con el proyecto y otros sí. Para confirmar el estado de cada número de seguimiento en la solicitud de vinculación original, descargue el informe del lote.

Nota: Si el estado de la tarea figura como ERROR, significa que, debido a varias razones o errores graves, no se ha podido procesar la solicitud y el usuario tiene que volver a intentarlo.

La tabla siguiente muestra los estados de las tareas y sus respectivas descripciones:

Utilice este punto de conexión para descargar un informe JSON de una tarea asíncrona que tenga un estado de COMPLETADO.

Los datos necesarios asociados a esta solicitud son:

• jobID : especifique el ID de la tarea cuyo estado pretende recuperar. El ID de tarea es obligatorio para este punto de conexión.

Nota:

• Solo puede descargar las tareas asincrónicas de una en una.
• Si la tarea no aparece con el estado de COMPLETADO e intenta descargar el informe, aparecerá un mensaje de error.

La respuesta positiva a esta solicitud le proporcionará el informe de la tarea en formato JSON.

Normas comerciales habituales

• No hay límite en el total de números de seguimiento que se pueden vincular a un proyecto de Advanced Integrated Visibility.
• Los números de seguimiento vinculados a un proyecto de Advanced Integrated Visibility se desvinculan después de 40 días de su correcta vinculación con el webhook.
• La información confidencial de seguimiento, como la dirección del destinatario, su firma y demás datos sensibles, no está disponible a través de la Tracking Number Subscription API.

Normas comerciales para el punto de conexión sincrónico

• 150 números de seguimiento como máximo por solicitud.
• Todos los números de seguimiento deben usar el mismo subscriptionId.
• La suscripción de webhook de Advanced Integrated Visibility debe ser válida y estar activa.
• Las solicitudes se someten a un tiempo de espera de 30 segundos.

Normas comerciales para el punto de conexión asincrónico

• 1.000 números de seguimiento como máximo por solicitud.
• El estado y los detalles de la tarea para una solicitud asincrónica se conservan durante 90 días una vez que los números de seguimiento se vinculan correctamente con el webhook de Advanced Integrated Visibility.