A Tracking Number Subscription API de Visibilidade integrada avançada (AIV) permite que os inscritos na Visibilidade integrada avançada associem números de rastreamento a um projeto com o webhook AIV usando os endpoints da API. O recurso de associação de números de rastreamento é compatível com dois métodos de processamento:

• A Associação de números de rastreamento (síncrona) retorna os resultados do processamento na mesma resposta HTTP. Essa opção é mais adequada para aplicativos que exigem confirmação imediata ao associar uma quantidade menor de números de rastreamento. 
• A Associação de números de rastreamento (assíncrona) envia a solicitação para processamento em segundo plano e retorna um ID de trabalho que pode ser usado posteriormente para recuperar o status e os resultados do processamento. Essa opção é mais adequada para processar lotes maiores de números de rastreamento. 

Escolha o método de processamento mais adequado aos requisitos de desempenho e de carga de trabalho do seu aplicativo.

Observação:

• Você precisa ter acesso de administrador ou colaborador ao projeto de visibilidade integrada avançada.
• Para obter mais informações sobre a Visibilidade integrada avançada e seus recursos, acesse a página de documentação da Visibilidade integrada avançada.

A Tracking Number Subscription API de Visibilidade integrada avançada oferece os seguintes benefícios:

• Você pode associar, atualizar e gerenciar facilmente os números de rastreamento do projeto com o webhook Visibilidade integrada avançada usando os endpoints da API.
• Associe vários números de rastreamento a uma única solicitação de API, em vez de processar cada número de rastreamento separadamente.
• Escolha entre processamento síncrono para resultados imediatos ou processamento assíncrono para operações em lotes maiores.

Use os seguintes endpoints para gerenciar seu projeto de Visibilidade integrada avançada:

• Associação de números de rastreamento (síncrona): permite associar números de rastreamento a um webhook e receber o status final do processamento na mesma resposta HTTP.
• Associação de números de rastreamento (assíncrona): permite associar números de rastreamento a um webhook e usar o jobId retornado posteriormente para verificar o status do trabalho assíncrono ou fazer download dos detalhes usando os endpoints relacionados:    
  • Status do trabalho do número de rastreamento
  • Detalhes do trabalho do número de rastreamento

Essas APIs estão disponíveis na visão geral do projeto de Visibilidade integrada avançada.

É possível acessar essas APIs apenas na visão geral do projeto, como mostrado na captura de tela acima.

A tabela a seguir resume as diferenças entre os endpoints de Associação de números de rastreamento síncrona e assíncrona.
 

Use o endpoint síncrono quando precisar de confirmação imediata para lotes menores de números de rastreamento. Use o endpoint assíncrono para processar lotes maiores que não exigem uma resposta imediata.

Use este endpoint para associar um ou mais números de rastreamento a um projeto com o webhook Visibilidade integrada avançada e receba os resultados do processamento na mesma resposta HTTP.

Este endpoint é destinado a aplicativos que exigem confirmação imediata e aceita solicitações com até 150 números de rastreamento.

Entrada obrigatória: 

• subscriptionID
• trackingNumber

Benefícios

O endpoint síncrono oferece os seguintes benefícios:

• Resultados de processamento imediatos
• Informações detalhadas sobre sucesso e falha em uma única resposta
• Capacidade para até 150 números de rastreamento por solicitação
• Solicitar validação e aplicação de regras de negócios antes do processamento
• Códigos de erro e mensagens de erro descritivas legíveis por máquina
• IDs de transação para rastreamento de solicitações e solução de problemas

O endpoint Associação de números de rastreamento (síncrona) impõe várias regras de validação, incluindo:

• Exigir um subscriptionId válido e ativo
• Permitir apenas um subscriptionId por solicitação
• Exigir um trackingNumber
• Garantir que os números de rastreamento atendam aos requisitos de formatação da FedEx, incluindo o limite máximo de 6 a 22 dígitos para números de rastreamento

As respostas de erro seguem uma estrutura consistente com errors[] contendo o código e a mensagem para facilitar a análise.

"errors": [

{

"code": "ERROR.CODE",

"message": "Descriptive error message"

}

O endpoint Associação de números de rastreamento (síncrona) permite sucessos parciais. Quando há falha em alguns números de rastreamento, a Synchronous API ainda retorna 200 OK e exibe a seguinte informação:

• failedTrackingNumbers
• Uma mensagem descritiva

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Below tracking numbers failed to upload due to validation or system errors"

      }

    }

Consulte as seções de regras de negócios para saber mais detalhes e requisitos.

Use este endpoint para enviar um ou mais números de rastreamento inscritos para processamento em segundo plano.

A solicitação retorna um ID de trabalho que você pode usar com o endpoint Status do trabalho do número de rastreamento para monitorar o processamento e com o endpoint Detalhes do trabalho do número de rastreamento para fazer download dos resultados do processamento após a conclusão do trabalho.

Entrada obrigatória:

• Ação
• Detalhes do número de rastreamento

É possível associar até 1.000 números de rastreamento em uma única solicitação.

Benefícios

O endpoint assíncrono oferece os seguintes benefícios:

• Aceita envios em lote grandes de até 1.000 números de rastreamento
• Permite que solicitações de longa execução sejam processadas em segundo plano
• Permite o monitoramento do status de trabalhos e o download de relatórios de processamento
• Elimina as preocupações com tempo limite de solicitação para grandes cargas de trabalho

Use este endpoint para obter o status de um trabalho assíncrono (uma ou mais solicitações consecutivas na fila) ou o status de todos os trabalhos enviados.

As informações de entrada necessárias para essa solicitação são as seguintes:

• jobID: especifique o ID do trabalho do qual você quer recuperar o status.

Observação: o ID do trabalho é uma entrada opcional para este endpoint. Se ele não for especificado, você receberá o status de todos os trabalhos enviados.

A resposta bem-sucedida a essa solicitação retornará jobID, status atual do trabalho e carimbo de data e hora da criação e da conclusão do trabalho. A resposta exibirá o status atual dos trabalhos. Além disso, a resposta também conterá mensagens de sucesso, erros ou avisos para permitir que os usuários visualizem e solucionem problemas, conforme aplicável.

• Um status de trabalho CONCLUÍDO indica que todos os números de rastreamento foram validados e processados corretamente.
  • O status CONCLUÍDO significa que os números de rastreamento foram validados e processados corretamente, mas não significa que todos os números de rastreamento foram adicionados corretamente ao projeto de visibilidade integrada avançada.
  • Para trabalhos com vários números de rastreamento, o status pode ser considerado CONCLUÍDO mesmo que alguns números não sejam associados ao projeto e outros sejam bem-sucedidos. Para confirmar o status de cada número de rastreamento na solicitação de associação original, faça download do relatório em lote.

Observação: um status de trabalho de FALHA indica que não foi possível processar a solicitação devido a problemas diversos ou falhas no hardware e que o usuário deve tentar novamente.

A seguinte tabela mostra os status dos trabalhos e as respectivas descrições:

Use este endpoint para baixar o relatório JSON de um trabalho assíncrono que tenha o status de CONCLUÍDO.

As informações de entrada necessárias associadas a essa solicitação são as seguintes:

• jobID: especifique o ID do trabalho do qual você quer recuperar o status. O ID do trabalho é obrigatório para este endpoint.

Observação:

• Você pode fazer download apenas de um relatório de trabalho assíncrono por vez.
• Se o trabalho não estiver CONCLUÍDO e você tentar baixar o relatório, uma mensagem de erro será exibida.

A resposta bem-sucedida dessa solicitação gera o relatório do trabalho no formato JSON.

Regras de negócios comuns

• Não existe um limite para o total de números de rastreamento que podem ser associados a um projeto de Visibilidade integrada avançada.
• Os números de rastreamento associados ao projeto de Visibilidade integrada avançada são dissociados 40 dias após a associação bem-sucedida ao webhook.
• A proteção das informações de rastreamento, como endereço e assinatura do destinatário e informações confidenciais de entrega, não está disponível na Tracking Number Subscription API.

Regras de negócios para o endpoint síncrono

• Máximo de 150 números de rastreamento por solicitação.
• Todos os números de rastreamento devem usar o mesmo subscriptionId.
• A inscrição no webhook Visibilidade integrada avançada especificado deve ser válida e estar ativa.
• As solicitações estão sujeitas a um tempo limite de 30 segundos.

Regras de negócios para o endpoint assíncrono

• Máximo de 1.000 números de rastreamento por solicitação.
• O status e os detalhes do trabalho em uma solicitação assíncrona são mantidos por 90 dias após a associação bem-sucedida dos números de rastreamento ao webhook Visibilidade integrada avançada.