APIs de transportadoras de envio explicadas: UPS, FedEx, USPS, DHL e mais
As APIs de transportadoras são conexões de software que permitem que uma loja, um sistema de armazém, uma plataforma de gerenciamento de pedidos ou uma ferramenta de atendimento ao cliente troque dados de remessa com transportadoras como UPS, FedEx, USPS e DHL. Elas podem oferecer suporte a tarefas como solicitações de tarifas, criação de etiquetas, agendamento de remessas, atualizações de rastreamento, verificações de endereço e notificações de eventos de entrega. A abordagem de API correta depende menos do nome da transportadora do que do fluxo de trabalho que você precisa automatizar, dos países que atende e dos sistemas que já utiliza.
Uma integração com uma única transportadora pode funcionar bem quando o volume de remessas e a área de atendimento são previsíveis. Uma API para várias transportadoras geralmente é mais prática quando uma operação compara serviços, envia remessas internacionalmente ou precisa de um formato de rastreamento único entre várias transportadoras. Este guia explica os principais tipos de API, como as principais transportadoras diferem em termos gerais e o que verificar antes de criar ou comprar uma integração.
O que uma API de transportadora faz
Uma API, ou interface de programação de aplicações, define como dois sistemas de software trocam solicitações e respostas. No transporte, sua aplicação pode enviar detalhes do pacote, endereços de origem e destino, preferências de serviço e informações alfandegárias. A transportadora ou plataforma de envio então retorna uma resposta, como uma tarifa de envio, dados da etiqueta, um número de rastreamento ou uma mensagem de erro.
As APIs de transportadoras normalmente atendem a várias funções distintas:
- Cálculo de tarifas: Solicita uma cobrança de envio estimada ou baseada em contrato para um pacote e serviço.
- Criação de remessas: Envia os detalhes da remessa e recebe um número de rastreamento ou uma confirmação de envio.
- Geração de etiquetas: Produz uma etiqueta imprimível, geralmente como PDF, imagem ou conteúdo de documento.
- Rastreamento: Recupera eventos de remessa, status, locais e informações de entrega quando disponíveis.
- Serviços de endereço: Valida, padroniza ou complementa informações de endereço, dependendo da transportadora e do destino.
- Coleta e manifesto: Oferece suporte a solicitações de coleta ou à documentação de remessas de fim de dia quando a conta e o serviço permitem.
- Notificações: Entrega informações de status por meio de consultas periódicas, webhooks, recursos de e-mail ou outro mecanismo de eventos.
Esses recursos não estão automaticamente incluídos em todas as contas de API de transportadoras. Uma transportadora pode separar os serviços em diferentes produtos, exigir aprovação da conta ou limitar o acesso por país, tipo de serviço, contrato com o cliente ou ambiente técnico. Considere cada recurso como algo que deve ser confirmado na documentação atual da transportadora, e não como algo a ser inferido apenas pela existência de uma API.
APIs diretas de transportadoras versus APIs para várias transportadoras
Existem dois modelos práticos de integração. Uma integração direta com uma transportadora conecta seu software à plataforma de desenvolvimento de uma única transportadora. Uma integração para várias transportadoras conecta seu software a um intermediário que padroniza várias transportadoras por meio de uma única interface.
| Modelo | Vantagens | Desvantagens | Mais adequado para |
|---|---|---|---|
| API direta da transportadora | Acesso direto aos próprios serviços, regras de conta e dados de remessa da transportadora | Credenciais, formatos, testes, tratamento de erros e manutenção separados para cada transportadora | Uma empresa com uma transportadora principal ou um fluxo de trabalho especializado |
| API para várias transportadoras | Uma integração pode simplificar o rastreamento, a seleção de transportadoras e o tratamento padronizado de status | A cobertura, a profundidade dos recursos, os requisitos da conta e os termos comerciais variam conforme o provedor | Comércio eletrônico com várias transportadoras, marketplaces, 3PLs e operações internacionais |
Uma API para várias transportadoras não substitui necessariamente um relacionamento direto com a transportadora. Algumas funções de envio ainda podem exigir uma conta da transportadora, tarifas negociadas, aprovação ou configuração direta. Também vale verificar se o intermediário cria etiquetas, apenas rastreia remessas existentes ou oferece suporte a ambos.
Comparação entre as principais APIs de transportadoras
API da UPS
A UPS oferece recursos para desenvolvedores que conectam aplicações empresariais aos serviços da UPS. Dependendo da conta, da região e do produto, os desenvolvedores podem investigar recursos como cálculo de tarifas, envio, rastreamento, serviços relacionados a endereços e fluxos de trabalho de coleta por meio do ambiente oficial de desenvolvimento da UPS.
A UPS é frequentemente considerada por empresas que possuem uma operação significativa de encomendas, precisam de acesso a serviços específicos da UPS ou já gerenciam uma conta e um contrato com a UPS. A questão prática não é simplesmente saber se a UPS possui uma API. É saber se o serviço específico da UPS, o acordo de cobrança, o destino e o perfil do pacote podem ser usados por meio do produto de API disponível para sua conta.
Antes da implementação, confirme o processo atual de autenticação, a disponibilidade de ambiente de testes, os formatos de solicitação compatíveis, a saída da etiqueta, a elegibilidade de tarifas, o comportamento dos eventos de rastreamento e os requisitos de migração. A documentação e os nomes dos produtos da UPS podem mudar; portanto, use o portal oficial de desenvolvedores da UPS como ponto de partida.
API da FedEx
A FedEx oferece uma plataforma para desenvolvedores de aplicações que precisam trabalhar com serviços de envio e entrega da FedEx. A documentação é a fonte apropriada para verificar as APIs disponíveis, as credenciais, os ambientes de teste, os fluxos de trabalho de remessa, o rastreamento e os requisitos específicos de cada serviço.
A FedEx pode ser uma boa opção quando uma operação depende dos serviços da FedEx ou precisa de controle específico da transportadora sobre os fluxos de trabalho de envio e rastreamento. O esforço de integração pode envolver mais do que enviar um endereço e receber uma etiqueta. Dimensões do pacote, seleção do serviço, detalhes da conta, informações alfandegárias, regras para mercadorias perigosas e documentação internacional podem afetar a solicitação e a resposta.
As equipes devem testar solicitações bem-sucedidas e malsucedidas. Por exemplo, uma aplicação deve saber como lidar com um endereço inválido, um serviço incompatível, uma solicitação de remessa duplicada, um campo alfandegário ausente e uma indisponibilidade temporária da transportadora. Consulte o Portal de desenvolvedores da FedEx para obter a documentação e os requisitos de acesso atuais.
API da USPS
A USPS oferece recursos empresariais e para desenvolvedores que utilizam os serviços da USPS. A USPS é especialmente relevante para fluxos de trabalho de encomendas e correspondências domésticas nos EUA, enquanto os produtos de API exatos e as condições de acesso devem ser verificados na documentação oficial atual.
As integrações com a USPS exigem testes cuidadosos, pois uma empresa pode precisar distinguir entre produtos postais, serviços de encomendas, eventos de rastreamento, dados de endereço e fluxos de trabalho de etiquetas ou postagem. Uma necessidade apenas de rastreamento é significativamente diferente de uma aplicação que precisa comprar postagem ou gerar etiquetas de envio.
Não presuma que uma API da USPS tenha a mesma estrutura de solicitação, vocabulário de eventos, disponibilidade de serviços ou modelo de conta da UPS ou da FedEx. Consulte os recursos para desenvolvedores da USPS e confirme quais produtos estão disponíveis para seu caso de uso, escopo geográfico e configuração de conta. Se sua empresa precisa apenas de uma visualização consistente de rastreamento entre transportadoras, uma API para várias transportadoras focada em rastreamento pode exigir menos lógica personalizada do que várias integrações diretas.
API da DHL
A DHL é um grupo de empresas com diferentes serviços de logística e encomendas; portanto, “a API da DHL” não é um produto universal para todas as remessas. Os recursos para desenvolvedores da DHL abrangem APIs e ferramentas associadas aos seus serviços, mas o produto relevante depende da unidade de negócios da DHL, do destino, do tipo de remessa e do relacionamento com a conta.
A DHL é uma opção natural para envios internacionais, serviços expressos e operações transfronteiriças, mas a integração correta ainda precisa ser compatível com o serviço adquirido. Verifique se a documentação se aplica à DHL Express, aos serviços de encomendas de comércio eletrônico, ao transporte de cargas ou a outra oferta da DHL antes de projetar o fluxo de trabalho.
Verifique os países compatíveis, os campos alfandegários e de fatura comercial, os códigos de serviço, o comportamento do rastreamento, os formatos de etiqueta e os requisitos de abertura de conta no Portal de desenvolvedores da DHL. Para implementações internacionais, inclua um processo para lidar com exceções alfandegárias e documentação incompleta, em vez de tratar o rastreamento como todo o ciclo de vida da remessa.
Outras transportadoras
As empresas também podem precisar de transportadoras regionais ou nacionais, como Canada Post, Royal Mail, Australia Post, DPD, GLS ou Japan Post. Suas APIs diferem em cobertura, integração inicial, nomes de serviços, nível de detalhe dos eventos de rastreamento, formatos de etiqueta e suporte a remessas internacionais. Portanto, “mais transportadoras” não é automaticamente melhor. A cobertura deve ser medida em relação às rotas, aos serviços e aos tipos de remessa que você realmente utiliza.
Para uma transportadora importante para sua operação, consulte primeiro a documentação própria para desenvolvedores. Se a transportadora for compatível por meio de uma plataforma de terceiros, confirme se a integração é direta, se você fornece suas próprias credenciais da transportadora e quais funções estão disponíveis. O suporte ao rastreamento não prova que o cálculo de tarifas, a criação de etiquetas ou o cancelamento de remessas também sejam compatíveis.
API de rastreamento ou API completa de envio?
Muitos projetos usam o termo “API de envio” quando, na verdade, precisam de rastreamento de remessas. Esses são escopos diferentes. Uma API de rastreamento geralmente aceita um número de rastreamento e uma transportadora, e então retorna eventos padronizados ou um status atual. Uma API completa de envio pode abranger tarifas, etiquetas, criação de remessas, documentos alfandegários e rastreamento.
Se seu principal objetivo é mostrar o progresso da entrega em um site de comércio eletrônico, portal do cliente ou ferramenta de suporte, uma integração focada em rastreamento pode ser suficiente. A API de rastreamento da 17TRACK é um exemplo de produto de rastreamento para várias transportadoras; sua documentação deve ser usada para verificar a cobertura atual de transportadoras, os formatos de solicitação, a autenticação e o comportamento dos eventos antes da adoção.
Se você precisa comprar postagem ou criar etiquetas, apenas o rastreamento não concluirá o fluxo de trabalho. Talvez sejam necessárias contas diretas das transportadoras, uma plataforma de envio ou uma API de envio para várias transportadoras com recursos de etiquetas documentados. Separar esses requisitos desde o início evita um erro comum de implementação: selecionar um produto de rastreamento e descobrir mais tarde que ele não pode criar a remessa necessária para o seu armazém.
O que verificar antes de escolher uma API
1. Defina o fluxo de trabalho empresarial
Escreva a ação exata que o sistema deve executar. Exemplos incluem “mostrar eventos de rastreamento após o envio de um pedido”, “selecionar o serviço elegível de menor custo”, “criar uma etiqueta no armazém” ou “notificar um cliente quando a entrega atrasar”. Cada ação tem diferentes requisitos de dados, tratamento de erros e operação.
2. Relacione as transportadoras às rotas e aos serviços
Liste os países de origem, os países de destino, os tipos de pacote, os níveis de serviço, os fluxos de devolução e quaisquer mercadorias restritas. Uma transportadora pode ter suporte técnico e ainda assim ser inadequada para determinada rota ou serviço. Para remessas internacionais, inclua dados alfandegários, tarifas, impostos e documentação comercial nos requisitos.
3. Confirme o acesso e os pré-requisitos comerciais
Verifique se a API exige uma conta da transportadora, configuração de cobrança, aprovação, tarifas negociadas, um token de aplicação ou uma revisão de produção. As credenciais de teste e de produção podem ser diferentes. Nunca coloque segredos de produção no código do navegador ou em repositórios públicos; use uma integração segura no lado do servidor e altere as credenciais de acordo com sua política de segurança.
4. Compare a qualidade dos dados, não apenas a quantidade de endpoints
Pergunte como a API representa o status da remessa, a entrega estimada, as exceções de entrega, o comprovante de entrega, as leituras, as devoluções e as remessas com vários pacotes. Uma lista longa de endpoints não garante detalhes úteis dos eventos. Decida como sua aplicação normalizará status como etiqueta criada, em trânsito, saiu para entrega, entregue, exceção e devolvida.
5. Teste cenários de falha e alteração
Uma integração pronta para produção deve lidar com tempos limite, limites de frequência, solicitações duplicadas, endereços inválidos, leituras ausentes, indisponibilidade das transportadoras, números de rastreamento alterados e eventos atrasados ou fora de ordem. Use idempotência quando a API oferecer suporte, registre identificadores de solicitação e torne as novas tentativas seguras. Os sistemas de rastreamento também devem tolerar períodos sem novas leituras, em vez de tratar todo período de silêncio como uma falha.
6. Avalie o custo de manutenção
As APIs de transportadoras mudam. Atualizações de versão, alterações de certificados, mudanças de códigos de serviço, novos campos alfandegários e endpoints descontinuados podem afetar as operações. Pergunte quem monitora as alterações na documentação, quem é responsável pela resposta a incidentes e com que rapidez a integração pode ser atualizada. Um provedor para várias transportadoras pode reduzir o número de integrações mantidas pela sua equipe, mas introduz uma dependência que deve ser avaliada quanto à continuidade do serviço e à qualidade do suporte.
Uma estrutura prática para a decisão
Escolha uma API direta de transportadora quando uma única transportadora dominar suas remessas, você precisar de funções específicas dela e sua equipe puder manter a integração. Escolha uma API de envio para várias transportadoras quando precisar de tarifas, etiquetas e criação de remessas entre várias transportadoras por meio de um único fluxo de trabalho, desde que os serviços necessários sejam realmente compatíveis.
Escolha uma API de rastreamento para várias transportadoras quando o principal requisito for uma experiência de rastreamento consistente entre transportadoras, canais ou países. Isso pode ser útil para equipes de comércio eletrônico que desejam um modelo compartilhado de status pós-compra sem criar analisadores de rastreamento separados para cada transportadora. Se precisar de criação de etiquetas e rastreamento, verifique se um provedor oferece suporte a ambos ou planeje uma arquitetura em duas partes.
Para um novo projeto, comece com uma prova de conceito pequena. Teste uma remessa doméstica, uma remessa internacional se for relevante, uma solicitação malsucedida, um evento de exceção e um cenário de devolução ou cancelamento. Compare os dados retornados com a página de rastreamento voltada ao cliente da transportadora e com suas expectativas operacionais. Só então você deverá se comprometer com uma implementação mais ampla.
Perguntas frequentes
Uma API de uma única transportadora pode fornecer tarifas, etiquetas e rastreamento?
Às vezes, mas isso não deve ser presumido. Essas funções podem ser produtos separados ou exigir permissões de conta diferentes. Confirme cada recurso, serviço, país e requisito de credencial na documentação atual da transportadora.
Uma API para várias transportadoras é sempre melhor do que uma integração direta?
Não. Uma API para várias transportadoras pode reduzir o trabalho de engenharia quando você precisa de fluxos de trabalho comuns entre várias transportadoras, mas uma integração direta pode oferecer melhor acesso a recursos específicos da transportadora ou controles da conta. A melhor escolha depende das funções necessárias e do custo de manutenção que você consegue sustentar.
Preciso de uma conta da transportadora para usar uma API de envio?
Frequentemente, especialmente para criação de etiquetas, postagem, cobrança ou tarifas negociadas. Os requisitos variam conforme a transportadora, o produto, o país e o provedor. Confirme as regras comerciais e técnicas de integração inicial antes de criar a integração.
Qual é a diferença entre números de rastreamento e IDs de remessa?
Um número de rastreamento é o identificador usado para acompanhar uma encomenda na rede de uma transportadora. Um ID de remessa pode identificar uma transação, um grupo de pacotes, uma solicitação de etiqueta ou um registro interno. Uma remessa pode conter vários pacotes; portanto, seu modelo de dados não deve presumir que um pedido sempre corresponda a um único número de rastreamento.
Como uma equipe deve escolher entre UPS, FedEx, USPS e DHL?
Comece pelas rotas, pelos serviços, pelos perfis dos pacotes, pelos termos da conta e pelas funções de API necessárias, em vez de escolher apenas pela marca. Em seguida, teste a documentação e as respostas reais da transportadora para seus cenários domésticos e internacionais mais comuns.
