La API de suscripción de número de rastreo de visibilidad integrada avanzada permite a los suscriptores de la visibilidad integrada avanzada asociar números de rastreo con un proyecto de webhook utilizando los puntos finales de la API. La capacidad de asociación de números de rastreo admite dos métodos de procesamiento:

• Asociación de números de rastreo – sincrónico: devuelve los resultados del procesamiento dentro de la misma respuesta HTTP. Esta opción es más adecuada para aplicaciones que requieren una confirmación inmediata al asociar una cantidad menor de números de rastreo. 
• Asociación de números de rastreo – asincrónico: envía la solicitud de procesamiento en segundo plano y devuelve un ID de trabajo que se puede utilizar para obtener el estado de procesamiento y los resultados más tarde. Esta opción es más adecuada para procesar lotes más grandes de números de rastreo. 

Elige el método de procesamiento que mejor se adapte a los requisitos de rendimiento y carga de trabajo de tu aplicación.

Nota:

• Debes tener acceso de administrador o colaborador para tu proyecto de visibilidad integrada avanzada
• Para obtener más información sobre la visibilidad integrada avanzada y sus funciones, visita la página Documentación sobre visibilidad integrada avanzada.

La Advanced Integrated Visibility Tracking Number Subscription API brinda los siguientes beneficios:

• Puedes usar los puntos finales de la API para asociar, actualizar y gestionar números de rastreo de manera sencilla para tu proyecto de webhook de visibilidad integrada avanzada.
• Asocia varios números de rastreo en una sola solicitud de la API en lugar de procesar cada número de rastreo de forma individual.
• Elige entre el procesamiento sincrónico para obtener resultados inmediatos o el procesamiento asincrónico para operaciones de lotes más grandes.

Usa los siguientes puntos finales para gestionar tu proyecto de visibilidad integrada avanzada:

• Asociación de números de rastreo – sincrónico: te permite asociar números de rastreo a un webhook y recibir el estado final de procesamiento dentro de la misma respuesta HTTP.
• Asociación de números de rastreo – asincrónico : te permite asociar números de rastreo a un webhook y usar el jobId devuelto más tarde para verificar el estado del trabajo asincrónico o descargar los detalles con los puntos finales relacionados:    
  • Número de rastreo Estado del trabajo
  • Detalles del trabajo del número de rastreo

Estas API están disponibles en la descripción general del proyecto de visibilidad integrada avanzada.

Solo se puede acceder a estas API a través de la descripción general de tu proyecto, como se muestra en la captura de pantalla anterior.

La siguiente tabla resume las diferencias entre los puntos finales de asociación de números de rastreo sincrónicos y asincrónicos.
 

Usa el punto final sincrónico cuando necesitas una confirmación inmediata para lotes más pequeños de números de rastreo. Usa el punto final asincrónico cuando proceses lotes más grandes que no requieran una respuesta inmediata.

Usa este punto final para asociar uno o más números de rastreo a un proyecto de webhook de visibilidad integrada avanzada y recibir los resultados del procesamiento dentro de la misma respuesta HTTP.

Este punto final está destinado a aplicaciones que requieren una confirmación inmediata y admite solicitudes de hasta 150 números de rastreo.

Entrada requerida: 

• subscriptionID
• trackingNumber

Beneficios

El punto final sincrónico brinda los siguientes beneficios:

• Resultados de procesamiento inmediatos
• Información detallada sobre éxitos y fallos en una sola respuesta
• Soporte para hasta 150 números de rastreo por solicitud
• Validación de solicitud 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 rastreo de solicitudes y resolución de problemas

El punto final de asociación de números de rastreo sincrónico aplica múltiples reglas de validación, entre las que se incluyen:

• Requerir un subscriptionId válido y activo
• Permitir solo un subscriptionId por solicitud
• Requerir un trackingNumber
• Garantizar que los números de rastreo cumplan con los requisitos de formato de FedEx, incluido el límite máximo de números de rastreo de 6 a 22 dígitos

Las respuestas de error siguen una estructura consistente con errores[] que contienen el código y el mensaje para facilitar el análisis.

"errors": [

{

"code": "ERROR.CODE",

"message": "Mensaje de error descriptivo"

}

El punto final de asociación de números de rastreo – sincrónico permite éxitos parciales. Cuando algunos números de rastreo fallan, la API sincrónica igualmente devuelve 200 OK y muestra lo siguiente:

• failedTrackingNumbers
• Un mensaje descriptivo

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Los números de rastreo a continuación no se pudieron cargar debido a errores de validación o de sistema"

      }

    }

Consulta la sección de normas comerciales para ver detalles y reglas adicionales.

Usa este punto final para enviar uno o más números de rastreo suscritos para el procesamiento en segundo plano.

La solicitud devuelve un ID de trabajo que puedes usar con el punto final Estado de trabajo del número de rastreo para monitorear el procesamiento y con el punto final Detalles de trabajo del número de rastreo para descargar los resultados del procesamiento una vez que se complete el trabajo.

Entrada requerida:

• Acción
• Detalles del número de rastreo

Puedes asociar hasta 1000 números de rastreo en una sola solicitud.

Beneficios

El punto final asincrónico brinda los siguientes beneficios:

• Admite envíos de lotes grandes de hasta 1000 números de rastreo
• Permite que las solicitudes de larga duración se procesen en segundo plano
• Habilita el monitoreo del estado del trabajo y los informes de procesamiento descargables
• Elimina las preocupaciones por el tiempo de espera de las solicitudes en las cargas de trabajo grandes

Utiliza este punto final para obtener el estado de un trabajo asincrónico (una o más solicitudes consecutivas en cola) o el estado de todos los trabajos enviados.

La información de entrada requerida para esta solicitud es:

• jobID: especifica el ID de trabajo cuyo estado deseas obtener.

Nota: El ID de trabajo es una entrada opcional para este punto final. Si no especificas el ID de trabajo, obtendrás el estado de todos los trabajos enviados.

Una respuesta exitosa a esta solicitud arrojará el ID del trabajo, el estado actual del trabajo y la marca de tiempo de creación y finalización del trabajo. La respuesta mostrará el estado actual de los trabajos. Además, la respuesta también contendrá mensajes de éxito, errores o advertencias para que los usuarios los vean y solucionen los problemas según corresponda.

• Si el estado del trabajo se muestra como COMPLETADO, significa que todos los números de rastreo se validaron y procesaron exitosamente.
  • El estado COMPLETADO implica que los números de rastreo se validaron y procesaron correctamente. No implica que todos los números de rastreo se hayan agregado correctamente al proyecto de visibilidad integrada avanzada.
  • Para trabajos con varios números de rastreo, el estado se puede considerar COMPLETADO incluso si algunos números no pueden asociarse al proyecto y otros sí. Para confirmar el estado de cada número de rastreo en la solicitud de asociación original, descarga el informe de lotes.

Nota: Si el estado del trabajo aparece como FALLIDO, esto implica que debido a diversos motivos o fallas graves, la solicitud no se pudo procesar, y el usuario debe volver a intentarlo.

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

Utiliza este punto final para descargar el informe JSON de un trabajo asincrónico que esté en estado COMPLETADO.

La información que debe ingresarse en relación con esta solicitud es:

• jobID: especifica el ID de trabajo cuyo estado deseas obtener. Un ID de trabajo es obligatorio para este punto final.

Nota:

• Solo puedes descargar un informe de trabajo asincrónico a la vez.
• Si el trabajo no está COMPLETADO e intentas descargar el informe, se mostrará un mensaje de error.

La respuesta exitosa a esta solicitud te proporciona el informe del trabajo en formato JSON.

Normas comerciales comunes

• No hay límite en la cantidad total de números de rastreo que pueden asociarse a un proyecto de visibilidad integrada avanzada.
• Los números de rastreo asociados a un proyecto de visibilidad integrada avanzada dejan de estar asociados 40 días después de que se hayan asociado correctamente con el webhook.
• La información de rastreo segura, como la dirección y la firma del destinatario, y la información de entrega confidencial, no está disponible mediante la Tracking Number Subscription API.

Normas comerciales para el punto final sincrónico

• Máximo de 150 números de rastreo por solicitud.
• Todos los números de rastreo deben usar el mismo subscriptionId.
• La suscripción al webhook de visibilidad integrada avanzada especificada debe ser válida y estar activa.
• Los solicitudes están sujetas a un tiempo de espera de 30 segundos.

Normas comerciales para el punto final asincrónico

• Máximo de 1000 números de rastreo por solicitud.
• El estado y los detalles de trabajo en una solicitud asincrónica se conservan durante 90 días luego de que los números de rastreo se hayan asociado correctamente al webhook de visibilidad integrada avanzada.