Como usar a API de rastreamento da UPS: guia de configuração passo a passo

Para usar a UPS Tracking API, crie uma conta de desenvolvedor da UPS, registre uma aplicação, obtenha credenciais OAuth 2.0, solicite um token de acesso e envie solicitações de rastreamento autenticadas com um número de rastreamento UPS válido. Os rótulos exatos do portal, as etapas de aprovação e os requisitos da API podem mudar; portanto, confirme as instruções atuais no UPS Developer Portal oficial antes de colocar uma integração em produção.

Este guia é destinado a desenvolvedores e equipes de operações de ecommerce que precisam do status das remessas dentro de uma loja online, sistema de gerenciamento de pedidos, fluxo de trabalho de armazém, ferramenta de atendimento ao cliente ou painel interno. Ele se concentra na sequência de integração, nas decisões que afetam a confiabilidade e nas verificações que evitam falhas comuns de rastreamento.

O que a UPS Tracking API faz

Uma integração de API permite que o software solicite informações sobre remessas à UPS, em vez de exigir que um funcionário ou cliente abra manualmente a página de rastreamento da transportadora. Sua aplicação pode usar a resposta para exibir o status mais recente conhecido, identificar eventos de entrega, dar suporte a investigações do atendimento ao cliente ou acionar um fluxo de trabalho interno.

A API não é o mesmo que uma página de rastreamento. Uma página de rastreamento é projetada para ser lida por uma pessoa. Uma resposta de API é formada por dados estruturados que o software precisa analisar, armazenar e apresentar. Seu sistema continua responsável pela autenticação, pelo tratamento de erros, pela consulta periódica ou coleta de eventos, pela retenção de dados, pelo design da interface do usuário e por quaisquer regras de negócio baseadas nos eventos de entrega.

Antes de começar

Prepare os seguintes itens antes de abrir o portal de desenvolvedores:

• Uma conta de desenvolvedor da UPS ou o tipo de conta exigido pelo processo atual de integração da UPS.
• Uma aplicação registrada e as credenciais emitidas para essa aplicação.
• Um número de rastreamento de teste ou outro método de teste aprovado. Não comece com dados reais de clientes se a documentação da UPS fornecer um ambiente ou procedimento de teste separado.
• Uma decisão clara sobre qual sistema é responsável pelos registros de remessas, eventos de rastreamento e mensagens de status voltadas ao cliente.
• Um local seguro para armazenar as credenciais do cliente e os tokens de acesso. Nunca coloque segredos em código do navegador, repositórios públicos, capturas de tela ou aplicações móveis que possam ser inspecionadas pelos usuários.

Você também deve decidir se sua aplicação precisa apenas de rastreamento ou de uma integração mais ampla com a UPS. Rastreamento, cotação, envio, validação de endereços e serviços de documentos podem ter produtos, permissões, formatos de solicitação e requisitos operacionais diferentes.

Etapa 1: abra o UPS Developer Portal

Comece no UPS Developer Portal oficial. Revise o catálogo atual de APIs, as orientações de autenticação, os requisitos de integração, os termos e as informações sobre ambientes. Procure especificamente a documentação da Tracking API, em vez de presumir que as instruções de outro serviço da UPS também se aplicam ao rastreamento.

O portal é a fonte adequada para os campos atuais das solicitações, escopos de autorização, definições de resposta, limites de uso, códigos de erro e detalhes dos ambientes. Esses detalhes podem mudar, e um exemplo de código de terceiros pode usar uma interface antiga da UPS ou um método de autenticação desatualizado.

Etapa 2: registre uma aplicação

Crie uma aplicação no portal de desenvolvedores e selecione as APIs da UPS de que a aplicação realmente precisa. Para um projeto exclusivamente de rastreamento, solicite apenas a capacidade de rastreamento, a menos que seu fluxo de trabalho exija serviços adicionais. Limitar as permissões reduz a complexidade da configuração e facilita a solução de problemas posteriormente.

Registre o identificador e o segredo da aplicação em um gerenciador de segredos no servidor ou em um sistema protegido de variáveis de ambiente. Trate o segredo como uma senha. Se ele for exposto, faça sua rotação pelo processo fornecido pela UPS e revise os registros em busca de uso não autorizado.

Se o portal solicitar informações de conta, faturamento, empresa ou aplicação, forneça dados precisos. Evite inventar um caso de uso de produção ou usar as informações da conta de outra pessoa apenas para concluir um teste. O acesso a um serviço pode depender da configuração da conta e do processo atual de aprovação da UPS.

Etapa 3: implemente a autenticação OAuth 2.0

A documentação atual para desenvolvedores da UPS usa autenticação baseada em OAuth para suas APIs. Normalmente, seu servidor troca as credenciais da aplicação por meio do fluxo de token documentado e recebe um token de acesso. Em seguida, ele inclui esse token no cabeçalho de autorização de uma solicitação à API.

Mantenha a autenticação separada da lógica de rastreamento. Um design prático tem um componente que obtém e armazena em cache um token válido e outro que chama o endpoint de rastreamento. O componente de token deve:

• Enviar credenciais somente ao endpoint de autorização da UPS documentado.
• Usar o tipo de conteúdo e os parâmetros de concessão especificados na documentação atual da UPS.
• Armazenar o token temporariamente e reutilizá-lo até que expire, em vez de solicitar um novo token para cada número de rastreamento.
• Atualizar ou obter novamente o token quando ocorrer a condição de expiração documentada.
• Ocultar credenciais e tokens nos registros da aplicação, relatórios de erros e chamados de suporte.

Não copie um token de uma sessão do navegador para uma integração permanente. Um serviço de back-end geralmente é um local mais seguro para gerenciar credenciais, pois mantém os segredos longe do código público do cliente.

Etapa 4: crie a solicitação de rastreamento

Use o formato de solicitação mostrado na referência oficial da Tracking API. Uma solicitação típica inclui um número de rastreamento no caminho ou nos parâmetros da solicitação, um token de acesso no cabeçalho de autorização e os cabeçalhos exigidos pela API da UPS. Não presuma que o número de rastreamento é o único valor obrigatório: a referência atual pode especificar cabeçalhos de versão, transação, tipo de conteúdo ou correlação.

Um padrão de solicitação simplificado é semelhante a este:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Este é um exemplo estrutural, não um endpoint para copiar e colar. Use o endpoint, a versão, os cabeçalhos e os nomes de parâmetros publicados na documentação da UPS para sua aplicação. Mantenha o número de rastreamento normalizado de acordo com as regras dos seus próprios dados de pedidos, mas não remova caracteres, a menos que a documentação da transportadora confirme que isso é seguro.

Etapa 5: analise os eventos em seu modelo de dados

As respostas das transportadoras geralmente contêm mais informações do que um único rótulo de status. Antes de programar a página voltada ao cliente, mapeie a resposta para um modelo interno, como identificador da remessa, transportadora, status mais recente, código do evento, descrição do evento, data e hora do evento, localização, informações de entrega estimada e data e hora da entrega, quando disponíveis.

Preserve a resposta original da transportadora quando suas políticas de retenção e privacidade permitirem. Uma resposta bruta pode ajudar a diagnosticar um erro de mapeamento ou explicar por que seu status normalizado difere da redação da transportadora. Ao mesmo tempo, evite exibir códigos técnicos de eventos aos clientes sem uma explicação compreensível.

Não trate todo status como um resultado final de entrega. Por exemplo, um evento de trânsito, uma exceção, uma tentativa de entrega e um evento de entrega concluída não devem ser reduzidos à mesma mensagem para o cliente. Crie mapeamentos explícitos e defina o que acontecerá quando a UPS adicionar um valor de evento que seu código não reconheça.

Etapa 6: adicione novas tentativas, validação e monitoramento

Uma integração de produção precisa de mais do que uma solicitação bem-sucedida em um console de desenvolvimento. Adicione validações e proteções operacionais:

• Validação de entrada: rejeite números de rastreamento vazios, malformados ou obviamente incompletos antes de enviar as solicitações.
• Tempos limite: impeça que uma resposta lenta da transportadora bloqueie todo um fluxo de checkout, atendimento ou operação de armazém.
• Regras de nova tentativa: tente novamente falhas temporárias de rede ou serviço com cuidado e com espera progressiva. Não repita continuamente tentativas para erros de autenticação ou números de rastreamento inválidos.
• Atenção aos limites: siga os limites e as regras de uso da documentação da UPS. Armazene em cache os resultados recentes quando seu processo de negócios permitir.
• Estados desconhecidos: preserve um evento não reconhecido para análise, em vez de classificá-lo incorretamente como entregue ou perdido.
• Observabilidade: registre o tempo da solicitação, a categoria da resposta e as informações de correlação sem registrar segredos ou dados pessoais desnecessários.

Um sistema de rastreamento também deve definir com que frequência atualiza uma remessa. Consultas muito frequentes podem gerar carga evitável e talvez não produzam informações novas. Consultas muito espaçadas podem fazer com que uma página voltada ao cliente pareça desatualizada. Escolha um intervalo com base no volume de remessas, na urgência operacional, nas regras da transportadora e no nível de atualização de que seus usuários realmente precisam.

Etapa 7: teste com cenários realistas

Teste mais do que uma remessa entregue com sucesso. Inclua um número de rastreamento desconhecido, uma remessa em trânsito, uma exceção, uma remessa com vários eventos, um token expirado, um tempo limite, uma falha de autorização e uma resposta contendo campos que seu analisador não espera. Se a UPS fornecer um ambiente ou credenciais de teste separados, siga primeiro esse procedimento.

Verifique o caminho completo, da solicitação à interface do usuário. Confirme que o pedido correto recebe a remessa correta, que as datas e horas são exibidas no fuso horário desejado, que eventos duplicados não criam mensagens duplicadas para o cliente e que uma indisponibilidade da transportadora não substitui um status anteriormente válido por um texto enganoso.

Quando uma Tracking API para várias transportadoras é uma opção melhor

Uma integração direta com a UPS pode ser adequada quando sua operação envia principalmente pela UPS e precisa de controle próximo sobre o fluxo da transportadora. Ela se torna menos conveniente quando os pedidos podem passar por várias transportadoras, marketplaces, operadores postais ou empresas de entrega regionais. Nessa situação, credenciais, formatos de resposta, vocabulários de status e regras de nova tentativa separados podem aumentar o trabalho de manutenção.

Um serviço para várias transportadoras, como a 17TRACK Tracking API, pode oferecer um modelo de integração alternativo para aplicações que precisam de rastreamento em várias transportadoras. A documentação para desenvolvedores deve ser consultada diretamente para verificar transportadoras compatíveis, formatos de solicitação, autenticação, termos de uso e recursos disponíveis. Isso não a torna automaticamente melhor do que uma conexão direta com a UPS: a escolha certa depende da combinação de transportadoras, dos requisitos de dados, do controle sobre a integração e das restrições comerciais ou de conformidade.

Para uma consulta voltada ao consumidor, em vez de uma integração para desenvolvedores, a página de rastreamento da 17TRACK pode ser mais adequada do que criar uma conexão de API. Para uma loja online que precisa de atualizações pós-compra com sua própria marca, analise separadamente a integração relevante da plataforma, em vez de adicionar trabalho de API que a loja não exige.

Erros comuns de implementação

• Usar exemplos antigos: um exemplo de código pode fazer referência a uma versão descontinuada, a um método de autenticação antigo ou a um serviço diferente da UPS.
• Colocar segredos no código do front-end: qualquer conteúdo enviado para um navegador deve ser considerado inspecionável.
• Presumir que um resultado vazio significa que não há remessa: verifique o número de rastreamento, as permissões da conta, o ambiente e a mensagem de resposta antes de tirar uma conclusão de negócio.
• Mapear apenas o texto: as descrições de status podem variar. Use os códigos documentados e preserve valores desconhecidos para análise.
• Ignorar requisitos de conta e uso: o código técnico pode estar correto enquanto a aplicação não está configurada para o serviço solicitado.
• Atualizar sem uma regra de negócio: consultas desnecessárias podem aumentar custos, carga e ruído operacional sem melhorar a experiência do cliente.

Checklist prático para entrar em produção

1. Confirme que a aplicação está usando a documentação atual da UPS e o ambiente aprovado.
2. Verifique se as credenciais estão armazenadas no servidor e podem ser alternadas.
3. Teste falhas de autenticação, erros da transportadora, entradas malformadas e tempos limite.
4. Compare os status normalizados com a resposta original para remessas representativas.
5. Defina uma política de atualização e monitore o volume de solicitações.
6. Defina a responsabilidade por eventos não identificados, atualizações atrasadas e escalonamentos de clientes.
7. Documente a integração para que outro desenvolvedor possa atualizar credenciais, versões de endpoints e mapeamentos de status com segurança.

FAQ

Preciso de uma conta da UPS para usar a Tracking API?

Você deve revisar os requisitos atuais de integração e acesso da UPS no Developer Portal. O acesso à API pode depender do registro da aplicação, das credenciais, da configuração da conta e do serviço específico solicitado. Não presuma que o login público da página de rastreamento seja intercambiável com o acesso à API para desenvolvedores.

A UPS Tracking API é gratuita?

Não presuma que o acesso à API não tenha condições comerciais ou de uso. A UPS publica informações atuais sobre serviços e contas por meio de seus canais oficiais, e alguns requisitos podem depender do produto, da conta ou do contrato. Confirme diretamente os termos aplicáveis antes de planejar um orçamento de produção.

Posso chamar a API da UPS diretamente de JavaScript em um navegador?

Uma chamada baseada no navegador pode expor as credenciais da aplicação e criar problemas de origem cruzada, segurança e controle de uso. Uma integração no servidor geralmente é o padrão mais seguro para armazenar segredos, obter tokens, aplicar regras de nova tentativa e limitar o acesso aos dados das remessas.

Com que frequência minha aplicação deve solicitar atualizações de rastreamento?

Use uma política de atualização baseada nos limites documentados pela transportadora, no volume de remessas, na urgência operacional e no nível de atualização exigido pelos usuários. Armazene resultados recentes em cache quando apropriado, use espera progressiva após falhas temporárias e evite tratar consultas repetidas como substitutas de um evento ou recurso de notificação documentado.

Devo usar uma integração direta com a UPS ou uma API para várias transportadoras?

Uma integração direta com a UPS pode atender a um fluxo de trabalho focado na UPS que exige controle específico da transportadora. Uma API para várias transportadoras pode reduzir o número de integrações quando suas remessas usam várias transportadoras. Compare as transportadoras compatíveis, a autenticação, os campos de dados, os requisitos de confiabilidade, os termos de uso e o esforço de implementação antes de escolher.

Fontes

• UPS Developer Portal — catálogo oficial de APIs, acesso a aplicações, autenticação e documentação para desenvolvedores.
• UPS Technology Integration — informações oficiais sobre a integração da tecnologia da UPS com sistemas empresariais.
• 17TRACK Tracking API — ponto oficial de entrada do produto e dos recursos para desenvolvedores de rastreamento em várias transportadoras.
• 17TRACK API Documentation — documentação oficial da API para autenticação, solicitações e tratamento de respostas.