Conectar a USPS: tarifas ao vivo, etiquetas e rastreio
Obtenha seu Consumer Key e Consumer Secret no USPS Developer Portal, cole no Integration, teste, mapeie serviços e comece a cotar e enviar.
O conector da USPS obtém tarifas, compra etiquetas e rastreia envios pelas APIs da USPS. Um par de credenciais OAuth — Consumer Key e Consumer Secret — cobre tarifas e rastreio; comprar etiquetas exige também seus identificadores de conta de pagamento da USPS.
Pré-requisitos#
- Acesso ao USPS Developer Portal (developers.usps.com) e um app em Apps: seu Consumer Key e Consumer Secret ficam nessa página do app.
- Decida primeiro o ambiente: comece pelo ambiente de teste (TEM) antes da produção.
- Tarifas e rastreio só precisam do par OAuth: nenhum campo de conta é necessário.
- Antes de comprar etiquetas, tenha prontos seus identificadores de conta de pagamento da USPS: CRID, MID e EPS. Eles são necessários ao comprar uma etiqueta, não ao criar esta conexão.
Obter credenciais#
- Vá ao USPS Developer Portal (developers.usps.com) → Apps → abra seu app.
- Na página do app, copie o Consumer Key. Ele é usado como OAuth client_id.
- Na mesma página do app, copie o Consumer Secret. Ele é usado como OAuth client_secret.
- Guarde o Consumer Secret em local seguro imediatamente. Se perdê-lo, gere um novo no USPS Developer Portal.
Preencher no Integration#
- Abra Integration → Marketplace → USPS → Nova conexão.
- Consumer Key (client_id), obrigatório: cole o Consumer Key da página do seu app no USPS Developer Portal. No assistente, o campo tem o rótulo “Consumer Key”.
- Consumer Secret (client_secret), obrigatório: cole o Consumer Secret da mesma página do app. É criptografado em repouso e nunca exibido.
- Use sandbox (sandbox), opcional: preencha “true” para usar o ambiente de teste TEM (apis-tem.usps.com). Deixe vazio para produção (apis.usps.com).
- CRID / MID / EPS: não os procure aqui; são identificadores de conta de pagamento para comprar etiquetas, não campos deste assistente de conexão. Tenha-os prontos antes de comprar etiquetas.
Testar a conexão#
Clique em Testar a conexão. O teste só troca seu Consumer Key e Consumer Secret por um token OAuth para verificar se as credenciais funcionam: não cota tarifa, não compra etiqueta nem verifica rastreio. Se passar, chave, segredo e ambiente coincidem; se falhar, anote o erro e veja a FAQ antes de mudar outra coisa.
Mapping / escolher modelo#
A USPS não precisa de mapping de pedidos: trabalha com pacotes, não com pedidos. O que se mapeia aqui são os serviços da transportadora: nas configurações da conexão, vincule cada serviço de envio que você usa internamente ao serviço USPS correspondente e deixe ativos só os serviços com os quais realmente envia, para que a comparação de tarifas só cote serviços que você realmente oferece.
Ativar#
Após ativar, a conexão serve para comparar tarifas e comprar etiquetas ao enviar, e as atualizações de rastreio voltam e são aplicadas ao envio. Antes da primeira etiqueta real, garanta que seus identificadores de conta de pagamento (CRID / MID / EPS) estejam prontos: o teste de conexão não os verifica. Acompanhe os primeiros envios em Runs / Logs antes de confiar sem supervisão.
Perguntas frequentes#
O teste falha com 401
O Consumer Key ou o Consumer Secret está incorreto: os dois valores foram trocados, ou um foi copiado incompleto ou com espaço extra, e a USPS rejeita a troca de token.
Volte ao USPS Developer Portal (developers.usps.com) → Apps → seu app, copie o Consumer Key no campo Consumer Key e o Consumer Secret no campo Consumer Secret exatamente como exibido, e teste novamente.
Ambiente de teste e produção estão misturados
O ambiente e o esperado não coincidem: Use sandbox está “true” e as chamadas vão para o ambiente de teste TEM, mas você está testando como se fosse produção; ou Use sandbox está vazio para produção e você ainda espera comportamento de teste.
Faça o ajuste coincidir com o ambiente que quer testar e teste novamente: para o ambiente de teste preencha Use sandbox com “true”; para produção deixe Use sandbox vazio. Se usar os dois, mantenha conexões separadas.
O teste passa, mas comprar uma etiqueta falha
Isso acontece quando a parte de pagamento não está pronta: o teste só verifica a troca OAuth para tarifas e rastreio, enquanto comprar uma etiqueta exige também seus identificadores de conta de pagamento da USPS: CRID, MID e EPS.
Prepare seu CRID, MID e EPS antes de comprar etiquetas: eles não são campos do assistente de conexão, então um teste aprovado não os cobre. Quando estiverem prontos, tente comprar a etiqueta de novo e, se ainda falhar, veja o erro em Runs / Logs.
Etiqueta comprada, mas o rastreio nunca atualiza
As atualizações de rastreio chegam no ritmo da USPS, não na hora, e uma etiqueta ainda não entregue à USPS não tem movimentação para mostrar.
Confirme se o pacote foi realmente entregue, aguarde e verifique de novo. Se após 24 horas nada chegar, verifique em Runs / Logs os erros de rastreio desse envio.