A Advanced Integrated Visibility Tracking Number Subscription API permite aos subscritores da Visibilidade Integrada Avançada associar números de rastreio a um projeto de webhook através dos pontos finais da API. A funcionalidade de associação de números de rastreio suporta dois métodos de processamento:

• Associação de números de rastreio – Síncrono devolve os resultados do processamento na mesma resposta HTTP. Esta opção é mais adequada para aplicações que exigem confirmação imediata ao associar um menor número de números de rastreio. 
• Associação de números de rastreio – Assíncrono envia o pedido para processamento em segundo plano e devolve um ID de tarefa que pode ser utilizado para obter o estado e os resultados do processamento posteriormente. Esta opção é mais adequada para processar lotes maiores de números de rastreio. 

Escolha o método de processamento que melhor satisfaz os requisitos de desempenho e carga de trabalho da sua aplicação.

Nota:

• Tem de ter acesso de administrador ou contribuidor para o seu projeto de Visibilidade integrada avançada
• Para obter mais informações sobre a Visibilidade Integrada Avançada e as respetivas funcionalidades, aceda à página de documentação da Visibilidade Integrada Avançada.

A Advanced Integrated Visibility Tracking Number Subscription API oferece as seguintes vantagens:

• Pode associar, atualizar e gerir facilmente os números de rastreio do seu projeto de webhook de Visibilidade Integrada Avançada através dos pontos finais da API.
• Associe vários números de rastreio num único pedido de API, em vez de processar cada número de rastreio individualmente.
• Escolha entre o processamento síncrono para resultados imediatos ou o processamento assíncrono para operações em lotes maiores.

Utilize os seguintes pontos finais para gerir o seu projeto de Visibilidade Integrada Avançada:

• Associação de números de rastreio – Síncrono: permite-lhe associar números de rastreio a um webhook e receber o estado final do processamento na mesma resposta HTTP.
• Associação de números de rastreio – Assíncrono: permite-lhe associar os números de rastreio a um webhook e utilizar o jobId devolvido posteriormente para verificar o estado da tarefa assíncrona ou transferir detalhes através de pontos finais relacionados:    
  • Estado da tarefa do número de Rastreio
  • Detalhes da tarefa do número de Rastreio

Estas APIs estão disponíveis a partir da descrição geral do projeto de Visibilidade Integrada Avançada.

Só é possível aceder a estas APIs através da descrição geral do seu projeto, conforme indicado na captura de ecrã acima.

A seguinte tabela resume as diferenças entre os pontos finais de associação de números de rastreio síncronos e assíncronos.
 

Utilize o ponto final síncrono quando precisar de confirmação imediata para lotes menores de números de rastreio. Utilize o ponto final assíncrono quando processar lotes maiores que não exigem uma resposta imediata.

Utilize este ponto final para associar um ou mais números de rastreio a um projeto de webhook de Visibilidade Integrada Avançada e receber os resultados do processamento na mesma resposta HTTP.

Este ponto final destina-se a aplicações que exigem confirmação imediata e suporta pedidos com até 150 números de rastreio.

Entrada obrigatória: 

• subscriptionID
• trackingNumber

Vantagens

O ponto final síncrono oferece as seguintes vantagens:

• Resultados do processamento imediatos
• Informações detalhadas sobre o sucesso e insucesso numa única resposta
• Suporta até 150 números de rastreio por pedido
• Exige validação e a aplicação de regras empresariais antes do processamento
• Códigos de erros e mensagens de erro descritivas legíveis por máquinas
• IDs de transação para rastreio de pedidos e resolução de problemas

O ponto final Associação de números de rastreio – Síncrono aplica várias regras de validação, incluindo:

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

As respostas de erro seguem uma estrutura consistente com erros[] que contém código e mensagem para fácil interpretação.

"errors": [

{

"code": "ERROR.CODE",

"message": "Mensagem de erro descritiva"

}

O ponto final Associação de números de rastreio – Síncrono permite sucessos parciais. Quando alguns números de rastreio falham, a Synchronous API continua a devolver 200 OK e mostra o seguinte:

• failedTrackingNumbers
• Uma mensagem descritiva

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "O carregamento dos números de rastreio abaixo falhou devido a erros de validação ou do sistema"

      }

    }

Veja as secções de regras empresariais para obter mais detalhes e regras.

Utilize este ponto final para enviar um ou mais números de rastreio subscritos para processamento em segundo plano.

O pedido devolve um ID de tarefa que pode utilizar com o ponto final Estado da tarefa do número de rastreio para monitorizar o processamento e com o ponto final Detalhes da tarefa do número de rastreio para transferir os resultados após a conclusão da tarefa.

Entrada obrigatória:

• Acção
• Detalhes do número de rastreio

Pode associar até 1000 números de rastreio num único pedido.

Vantagens

O ponto final assíncrono oferece as seguintes vantagens:

• Suporta envios de grandes lotes de até 1000 números de rastreio
• Permite que os pedidos de longa duração sejam processados em segundo plano
• Ativa a monitorização do estado das tarefas e os relatórios de processamento transferíveis
• Elimina as preocupações relativas ao tempo limite do pedido para grandes cargas de trabalho

Utilize este ponto final para obter o estado de uma tarefa assíncrona (um ou mais pedidos consecutivos em fila) ou o estado de todas as tarefas enviadas.

As informações de introdução obrigatória deste pedido são:

• jobID – especifique o ID da tarefa da qual pretende obter o estado.

Nota: o ID da tarefa é uma entrada opcional para este ponto final. Se não especificar o ID da tarefa, irá obter os estados de todas as tarefas enviadas.

A resposta bem-sucedida a este pedido irá devolver o jobID, o estado da tarefa atual e o registo de data/hora da criação da tarefa e da conclusão da tarefa. A resposta irá apresentar o estado atual das tarefas. Além disso, a resposta também irá conter mensagens de sucesso, erros ou avisos para os utilizadores verem e resolverem os respetivos problemas, conforme aplicável.

• Se o estado da tarefa for apresentado como CONCLUÍDA, significa que todos os números de Rastreio foram validados e processados com sucesso.
  • O estado CONCLUÍDA indica que os números de Rastreio foram validados e processados com sucesso. Não indica que todos os números de Rastreio foram adicionados com sucesso ao projeto de Visibilidade integrada avançada.
  • Para tarefas com vários números de rastreio, o estado pode ser considerado CONCLUÍDO, mesmo que alguns números não sejam associados ao projeto e outros sejam. Para confirmar o estado de cada número de rastreio no pedido de associação original, transfira o relatório de lote.

Nota: se o estado da tarefa for apresentado como FALHA, significa que, devido a vários motivos/falhas graves, não foi possível processar o pedido e o utilizador tem de tentar novamente.

A seguinte tabela mostra os estados da tarefa e as respetivas descrições:

Utilize este ponto final para transferir o relatório JSON para uma tarefa assíncrona que está com o estado CONCLUÍDA.

As informações de introdução obrigatória associadas a este pedido são:

• jobID – especifique o ID da tarefa da qual pretende obter o estado. O ID da tarefa é obrigatório para este ponto final.

Nota:

• Só pode transferir um relatório de tarefa assíncrona de cada vez.
• Se a tarefa não estiver CONCLUÍDA e tentar transferir o relatório, é apresentada uma mensagem de erro.

A resposta bem-sucedida a este pedido fornece-lhe o relatório da tarefa no formato JSON.

Regras empresariais comuns

• Não existe um limite para o máximo de números de rastreio que podem ser associados a um projeto de Visibilidade Integrada Avançada.
• Os números de rastreio associados a um projeto de Visibilidade Integrada Avançada são dissociados 40 dias após terem sido associados ao webhook.
• As informações de rastreio protegidas, como o endereço do destinatário, a assinatura do destinatário e informações de entrega confidenciais, não estão disponíveis através da Tracking Number Subscription API.

Regras empresariais para o ponto final síncrono

• Máximo de 150 números de rastreio por pedido.
• Todos os números de rastreio têm de utilizar o mesmo subscriptionId.
• A subscrição de webhook de Visibilidade Integrada Avançada especificada tem de ser válida e ativa.
• Os pedidos estão sujeitos a um tempo limite de 30 segundos.

Regras empresariais para o ponto final assíncrono

• Máximo de 1000 números de rastreio por pedido.
• O estado e os detalhes da tarefa de um pedido assíncrono são retidos durante 90 dias após os números de rastreio serem associados com sucesso ao webhook de Visibilidade Integrada Avançada.