VibeFox USPS for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões mais antigas do PHP.
Aplicativo no USPS Developer Portal (somente para tarifas em tempo real): faça login no USPS Developer Portal (developers.usps.com) com uma conta comercial gratuita da USPS, crie um aplicativo e copie o seu Consumer Key e o seu Consumer Secret. O módulo usa as APIs atuais da USPS com OAuth 2.0. A USPS desativou a API antiga Web Tools (User ID e XML) em 25 de janeiro de 2026, por isso um Web Tools User ID não funciona mais. Sem chaves, são usados apenas os preços fixos.
Ship-from ZIP code: as tarifas em tempo real exigem o código ZIP de 5 dígitos dos EUA de onde as encomendas são enviadas.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure ou encontre depois o VibeFox USPS na lista de módulos e clique em Configure.
3. Informe a chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Informe o Consumer Key e o Consumer Secret, o Ship from ZIP code de 5 dígitos e escolha os serviços. Se a moeda padrão da loja não for USD, informe o USD exchange rate. Opcionalmente, informe preços fixos como alternativa. Clique em Save.
Ao instalar, o módulo cria a transportadora USPS com o texto de prazo de entrega Delivery by USPS. A transportadora é atribuída a todas as zonas e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox USPS > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa o token da USPS e as tarifas em cache.
Um valor inválido não é salvo: o valor anterior permanece e um erro indica o campo, enquanto os demais campos são salvos. Os avisos no topo da página informam quando apenas uma das chaves está preenchida, quando não há chaves nem preços fixos (nesse caso a transportadora nunca aparece), quando falta o código ZIP de origem, quando nenhum serviço está selecionado, quando falta o câmbio do USD, quando o ambiente de teste está ativo, quando a unidade de peso ou de dimensão da loja é desconhecida (defina em International > Localization, Local units) ou quando a transportadora USPS foi excluída.
Geral
Enable USPS shipping: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora exibido ao cliente no checkout. Padrão: USPS. Obrigatório, até 64 caracteres.
Tax status: a regra de imposto da transportadora. Os preços da USPS não incluem impostos. Escolha uma regra de imposto para adicionar imposto sobre o frete, ou None se o frete não for tributado.
API da USPS (tarifas em tempo real)
Consumer Key: o Consumer Key (client_id) do seu aplicativo de desenvolvedor da USPS.
Consumer Secret: o Consumer Secret (client_secret) do mesmo aplicativo. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo. Limpar o Consumer Key também remove o segredo salvo.
Test environment: usa o USPS Testing Environment for Mailers (apis-tem.usps.com). Somente para aplicativos que têm acesso a ele. Deixe desligado para preços reais (apis.usps.com). Padrão: desligado.
Prices: quais preços da USPS são usados.
Services: os serviços da USPS que podem ser oferecidos. É exibido o serviço selecionado mais barato que a USPS oferece para a encomenda. Os preços Flat Rate, Cubic, Hold for Pickup e Sunday nunca são usados. Padrão: USPS Ground Advantage, Priority Mail e First-Class Package International Service. Se nenhum serviço for selecionado, as tarifas em tempo real não são usadas.
USD exchange rate: os preços da USPS são em USD. Se a moeda padrão da loja não for USD, informe o preço de 1 USD nessa moeda, por exemplo 0.92. Sem ele, as tarifas em tempo real não são usadas e valem os preços fixos. Não é necessário se a moeda padrão for USD. Deve ser maior que 0.
Cache: o botão Clear cached USPS token and rates esvazia o cache imediatamente. As tarifas ficam em cache por 1 hora e uma tarifa com falha, por 10 minutos. Após um timeout, erro do servidor, limite de requisições ou chaves recusadas, a USPS não é consultada por 5 minutos.
Envio e encomenda (os preços da USPS dependem do código ZIP de origem, do peso e do tamanho da encomenda; o carrinho é cotado como uma única encomenda, e encomendas acima de 70 lb usam os preços fixos)
Ship from ZIP code: o código ZIP de 5 dígitos dos EUA de onde as encomendas são enviadas. Um ZIP+4 é reduzido para 5 dígitos. Outros valores são recusados com uma mensagem.
Box size: dimensões opcionais da caixa na unidade de dimensão da loja, por exemplo 30x20x15. Deixe vazio para montar o tamanho a partir das dimensões dos produtos: o maior comprimento, a maior largura e as alturas empilhadas. Se um produto não tiver dimensões, é usada uma caixa de 10 x 8 x 4 polegadas.
Default product weight: o peso em kg usado para produtos sem peso, nas tarifas da USPS, nos limites de peso e nas faixas de peso. Padrão: 0.5.
Preços fixos (preços na moeda padrão da loja, sem impostos; usados quando nenhuma chave de API é informada e como alternativa quando a USPS não retorna nenhuma tarifa: API indisponível, chaves erradas, nenhum serviço ou destino sem código ZIP dos EUA; deixe os dois campos vazios para ocultar a transportadora nesse caso)
Country prices: preços por país de destino e peso do carrinho. Clique em Add country para adicionar uma linha e no ícone de lixeira para removê-la. As colunas são Price e as faixas de peso XS (até 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) e XL (acima de 5 kg). Uma faixa vazia ou 0 usa Price. A linha * Default (any other country) vale para qualquer outro país. Uma linha de país sem nenhum preço envia esse país para Fallback cost. Valores que não são números são apagados com uma mensagem.
Fallback cost: um preço fixo quando nenhum preço por país corresponde. Deixe vazio para ocultar a transportadora nesse caso.
Fixed price is: Per order cobra o preço uma vez, pelo peso de todo o carrinho. Per item (each item priced by its own weight x quantity) calcula cada produto pelo peso de uma unidade (o peso padrão, se ele não tiver peso) e multiplica pela quantidade. As tarifas em tempo real da USPS são sempre cotadas para a encomenda inteira.
Condições
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual esta transportadora é grátis. Nenhuma requisição é enviada à USPS nesse caso. Deixe vazio para nunca oferecer frete grátis.
Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho é pelo menos esse valor. Deixe vazio para exibi-la sempre.
Min weight: o peso mínimo do carrinho em kg para que esta transportadora apareça. 0 significa sem limite.
Max weight: a transportadora fica oculta acima deste peso do carrinho em kg. Padrão: 30. A USPS aceita até 70 lb (31,7 kg). 0 significa sem limite. Se Min weight for maior que Max weight, é exibido um erro e os limites anteriores são mantidos.
Disponibilidade sem zonas de entrega
Ignore shipping zones: oferece a transportadora em todas as zonas para os países abaixo. Ao salvar, a transportadora é vinculada a todas as zonas da loja, inclusive às criadas depois. Desligando, a transportadora recupera suas zonas anteriores.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países para os quais a loja envia. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra as requisições à API e o cálculo das tarifas em logs/vfd_usps_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo com esta opção desligada. Chaves, tokens e endereços dos clientes nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ligado, desinstalar o módulo apaga as configurações da USPS, a transportadora, os serviços salvos dos pedidos, as tarifas em cache e os logs. Quando desligado, tudo é mantido para uma reinstalação.
Como funciona no checkout
Na etapa de entrega, o PrestaShop pede ao módulo o preço da USPS. Só produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à USPS.
O módulo obtém da USPS um token OAuth e o mantém até pouco antes de expirar. Um token recusado pela USPS é renovado e a cotação é repetida. Para destinos nos EUA e seus territórios (Porto Rico, Ilhas Virgens Americanas, Guam, Samoa Americana, Ilhas Marianas do Norte, Estados Federados da Micronésia, Ilhas Marshall e Palau), ele consulta a API Domestic Prices e precisa do código ZIP de 5 dígitos do cliente. Para os demais países, consulta a API International Prices com o país e o código postal.
A requisição contém o código ZIP de origem, o peso do carrinho em libras, o tamanho da encomenda em polegadas e o tipo de preço. Encomendas acima de 70 lb recebem os preços fixos. O cliente vê uma única opção com o serviço selecionado mais barato, convertida de USD para a moeda padrão da sua loja e exibida na moeda do carrinho do cliente.
Cada cotação fica em cache por 1 hora. Uma cotação com falha é lembrada por 10 minutos. Após um timeout, erro do servidor, limite de requisições ou chaves recusadas, a USPS não é consultada por 5 minutos. O timeout HTTP é de 10 segundos.
Se a USPS não retornar uma tarifa, o preço vem de Country prices e, depois, de Fallback cost. Se nenhum se aplicar, a transportadora fica oculta. O cliente nunca vê os textos de erro da USPS. O motivo é registrado no log.
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo passa a seguir a nova versão automaticamente.
O módulo apenas calcula tarifas. Não compra franquia postal nem etiquetas de envio, não agenda coletas, não rastreia encomendas e não permite ao cliente escolher uma agência postal ou um ponto de retirada. Ele mostra uma única opção, não vários serviços da USPS. Não há embalagem em caixas: o carrinho é cotado como uma única encomenda. Seguro e outros serviços extras não estão incluídos.
Pedidos
Quando um pedido é feito com a transportadora USPS, o módulo salva como o preço do frete foi obtido. A página do pedido no back office mostra um bloco USPS com o USPS service (para uma tarifa em tempo real, por exemplo USPS Ground Advantage) e o Price source: USPS live rate, Fixed price ou Free shipping.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox USPS é o primeiro bloco da página Modules > Module Manager > VibeFox USPS > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-usps e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on com uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere-a na sua conta vibefox.net.
Sem uma chave ativa, a transportadora USPS não é exibida aos clientes no checkout e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é necessário cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A USPS não aparece no checkout: verifique se a licença está ativa e se Enable USPS shipping está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ligue Ignore shipping zones e confira Countries. Confira os limites de peso e o Minimum subtotal. Sem chaves da USPS funcionando, a transportadora precisa de um preço fixo (Country prices ou Fallback cost). Os produtos também podem ser limitados a certas transportadoras na página do produto.
As tarifas em tempo real não aparecem: confira os avisos no topo da página do módulo. Ligue o Debug log, recarregue o checkout e veja o campo Log. Chaves erradas, o ambiente errado e as mensagens de erro da USPS são registrados ali. Tarifas nacionais exigem o código ZIP de 5 dígitos do cliente.
Minha loja não está em USD: a USPS cota apenas em USD. Informe o USD exchange rate. Sem ele, a tarifa em tempo real não é usada e o preço fixo é exibido no lugar.
Um Web Tools User ID não funciona: a API antiga Web Tools foi desativada. Crie um aplicativo no USPS Developer Portal e use o seu Consumer Key e o seu Consumer Secret.
As tarifas parecem desatualizadas após uma alteração: o cache é limpo quando você salva as configurações. Você também pode clicar em Clear cached USPS token and rates.
A página diz que a transportadora USPS não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox USPS e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O token e as tarifas em cache também são sempre removidos. Se Remove data on uninstall estiver ligado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações, os serviços salvos dos pedidos e o log são removidos. Se estiver desligado, a transportadora apenas é desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, ou com Reset, a transportadora salva recupera o status anterior: uma transportadora ativa volta a ficar ativa, e uma desativada continua desativada.
A USPS é uma marca de seu respectivo titular. Este módulo não é afiliado nem endossado pela USPS.