VibeFox USPS for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Aplicativo no USPS Developer Portal (somente para tarifas em tempo real): entre no USPS Developer Portal (developers.usps.com) com uma conta de negócios gratuita da USPS, crie um aplicativo e copie o Consumer Key e o Consumer Secret. O plugin usa as APIs atuais da USPS com OAuth 2.0. A USPS desativou a API Web Tools antiga (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 único domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_usps para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox USPS, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite o Consumer Key e o Consumer Secret, o Ship from ZIP code de 5 dígitos e escolha os serviços. Se a moeda da sua loja não for USD, digite a USD exchange rate.

6. Adicione o VibeFox USPS a uma zona de entrega em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

7. Opcionalmente, digite preços fixos como alternativa.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox USPS. Elas valem para todas as zonas de entrega. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome desta opção na finalização de compra. Deixe vazio para usar o Name geral.

Sempre que você salvar as configurações, o token da USPS e as tarifas em cache são apagados. Você também pode clicar em Clear cached USPS token and rates na seção USPS API. Os avisos acima das configurações informam quando só uma das chaves está preenchida, quando não há chaves nem preços fixos, quando falta o Ship from ZIP code, quando nenhum serviço está selecionado, quando falta a USD exchange rate ou quando o ambiente de teste está ativado.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.

Name: o nome do método de entrega exibido na finalização de compra. Padrão: USPS.

Tax status: os preços da USPS não incluem impostos. Taxable permite que o WooCommerce adicione o imposto de entrega ao custo, None não adiciona.

USPS API (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.

Test environment: usa o USPS Testing Environment for Mailers. Somente para aplicativos que têm acesso a ele. Deixe desativado para obter preços reais. Padrão: desativado.

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.

USD exchange rate: os preços da USPS são em USD. Se a moeda da sua loja não for USD, digite o preço de 1 USD na moeda da sua loja, 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 quando a moeda da loja é USD.

Origem do envio e encomenda (os preços da USPS dependem do código ZIP de origem, do peso e do tamanho da encomenda)

Ship from ZIP code: o código ZIP de 5 dígitos dos EUA de onde as encomendas são enviadas. Um ZIP+4 é cortado para 5 dígitos. Outros valores são rejeitados com uma mensagem.

Box size: dimensões opcionais da caixa na unidade de medida da sua 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 (kg): o peso 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 da sua loja; usados quando nenhuma chave de API é informada e como alternativa quando a USPS não retorna tarifa: API indisponível, chaves erradas, nenhum serviço ou destino sem código ZIP dos EUA; deixe ambos vazios para ocultar o método 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 X para remover uma. 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 se aplica a qualquer outro país. 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 o método nesse caso.

Fixed price is: Per order cobra o preço uma vez. Per item (each item priced by its own weight x quantity) calcula cada item pelo próprio peso (o peso padrão, se ele não tiver) e multiplica pela quantidade. As tarifas em tempo real da USPS são sempre consultadas para a encomenda inteira.

Condições

Free shipping from: o subtotal do carrinho a partir do qual este método é grátis. Nesse caso, nenhuma consulta é enviada à USPS. Deixe vazio para nunca oferecer entrega grátis.

Minimum subtotal: mostra o método somente quando o subtotal do carrinho é pelo menos este valor. Deixe vazio para sempre mostrar.

Min weight (kg): o peso mínimo do carrinho para este método aparecer. 0 significa sem limite.

Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 30. A USPS aceita até 70 lb (31,7 kg). 0 significa sem limite.

Excluded shipping classes: oculta o método se o carrinho tiver um produto de qualquer uma destas classes de entrega do WooCommerce.

Disponibilidade sem zonas de entrega

Ignore shipping zones: oferece o método para os países abaixo, mesmo sem tê-lo adicionado a uma zona de entrega.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países de entrega da loja. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: registra as requisições à API e o cálculo de tarifas em WooCommerce > Status > Logs, origem vfd-usps. Erros da API são sempre registrados, mesmo com esta opção desativada. Chaves, tokens e endereços de clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações e métodos das zonas. Desativar nunca apaga as configurações.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: peso do carrinho, subtotal mínimo e classes de entrega excluídas. Se a entrega grátis se aplicar, o método é exibido com preço 0 e nenhuma requisição é enviada à USPS.

O plugin obtém um token OAuth da USPS e o mantém até expirar. Um token recusado pela USPS é renovado e a consulta é repetida. Para destinos nos EUA e territórios (incluindo Porto Rico, Ilhas Virgens Americanas e Guam), consulta a Domestic Prices API e precisa do código ZIP de 5 dígitos do cliente. Para outros países, consulta a International Prices API 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 opção com o serviço selecionado mais barato, convertido para a moeda da sua loja.

Cada tarifa fica em cache por 1 hora. Uma consulta com falha é lembrada por 10 minutos. Após 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. Desativar o plugin apaga o token e as tarifas em cache.

Se a USPS não retornar uma tarifa, o preço vem de Country prices e, depois, de Fallback cost. Se nenhum se aplicar, o método fica oculto. O cliente nunca vê textos de erro da USPS.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin apenas calcula tarifas. Não compra franquia postal nem etiquetas de envio, não agenda coletas, não rastreia encomendas e não permite que o cliente escolha uma agência postal ou um ponto de retirada. Ele exibe 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

Para uma tarifa em tempo real, a linha de entrega do pedido guarda o USPS service, por exemplo USPS Ground Advantage. O gerente da loja vê isso na tela de pedido no admin.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox USPS. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a na sua conta em vibefox.net.

Sem uma chave ativa, a USPS não é exibida para os clientes na finalização de compra. Gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente em segundo plano, automaticamente.

Solução de problemas

A USPS não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Confira os limites de peso, o Minimum subtotal e as Excluded shipping classes. Sem chaves válidas da USPS, o método precisa de um preço fixo (Country prices ou Fallback cost).

As tarifas em tempo real não aparecem: verifique os avisos no topo da página de configurações. Ative Debug log e abra WooCommerce > Status > Logs, origem vfd-usps. Chaves erradas, ambiente incorreto e 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. Digite a USD exchange rate. Sem ela, 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 Web Tools antiga foi desativada. Crie um aplicativo no USPS Developer Portal e use o seu Consumer Key e Consumer Secret.

As tarifas parecem desatualizadas após uma mudança: o cache é apagado quando você salva as configurações. Você também pode clicar em Clear cached USPS token and rates.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver usada em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém as configurações e apenas apaga o token e as tarifas em cache. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin, assim como o token e as tarifas em cache, são sempre removidos. Configurações e métodos das zonas são removidos somente se Remove data on uninstall estava ativado. Caso contrário, ficam guardados para uma reinstalação posterior. Pedidos existentes mantêm as suas linhas de entrega.

USPS é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela USPS.