VibeFox EasyPost 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.

Conta EasyPost (somente para tarifas em tempo real): crie uma conta no site da EasyPost, conecte as contas das suas transportadoras (USPS, UPS, FedEx e outras) no painel da EasyPost e copie a chave de API em EasyPost Dashboard > Account Settings > API Keys. A EasyPost cobra pelas etiquetas compradas, não pelas consultas de tarifas. Se você usa apenas as tarifas de contingência, não precisa de uma conta EasyPost.

Produtos: os produtos precisam ter peso e, de preferência, dimensões.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

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

2. Clique em Activate.

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

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

5. Cole sua chave de API da EasyPost e preencha o endereço Ship from. O CEP é obrigatório para as tarifas em tempo real.

6. Se a moeda da sua loja não for USD, digite a USD exchange rate. Opcionalmente, digite as tarifas de contingência (veja Configuração).

7. Adicione VibeFox EasyPost a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox EasyPost. Elas valem para todas as zonas de envio. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome do método de envio que os clientes veem nesta zona. Deixe vazio para usar o Name geral.

No topo da página, o plugin mostra avisos quando as tarifas em tempo real não podem ser usadas: falta a chave de API, falta o CEP ou o país de origem, ou a moeda da loja é diferente de USD sem taxa de câmbio. Uma nota também aparece quando uma chave de API de teste está definida. Sempre que você salva as configurações, as tarifas da EasyPost em cache são apagadas.

Geral

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

Name: o nome do método de envio exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo pelo próprio Title. Padrão: EasyPost Shipping.

Conta EasyPost

API key: sua chave de API da EasyPost, em EasyPost Dashboard > Account Settings > API Keys. Uma chave de produção (começa com EZAK) retorna tarifas reais. Uma chave de teste (começa com EZTK) retorna tarifas de teste da EasyPost; use-a somente para testes.

Allowed carriers / services: opcional, separado por vírgulas. Digite uma transportadora (USPS) ou uma transportadora e um serviço (USPS:Priority, UPS:Ground), como a EasyPost os nomeia. A tarifa permitida mais barata é mostrada. Deixe vazio para mostrar a tarifa mais barata de qualquer transportadora.

Origem do envio

O endereço de onde os seus pacotes são enviados. Se o Country for o país da sua loja, os campos vazios são preenchidos com o endereço da loja em WooCommerce > Settings > General (e o nome do remetente, com o título do site).

Sender name / company: o nome do remetente ou da empresa.

Street address: a rua do endereço de envio.

City: a cidade de envio.

State: o código do estado com duas letras, por exemplo CA ou NY.

ZIP code: o CEP ou código postal de envio. Obrigatório para as tarifas em tempo real.

Country: o país de onde você envia. Padrão: United States.

Tarifas

Parcels: como o carrinho é enviado à EasyPost.

Os pesos são convertidos da unidade de peso da loja para onças (mínimo 1 oz), e as dimensões para polegadas. Se algum produto não tiver dimensões, o pacote é tarifado apenas pelo peso.

USD exchange rate: as tarifas da EasyPost estão em USD. Digite o preço de 1 USD na moeda da sua loja, por exemplo 0.92. Sem esse valor, as tarifas em tempo real não são usadas, somente as de contingência. Não é necessário se a moeda da loja for USD. Lojas em USD e CAD pedem à EasyPost que cote na moeda delas. Tanto o ponto quanto a vírgula são aceitos como separador decimal.

Tax status: Taxable permite que o WooCommerce cobre imposto sobre o envio conforme as suas regras fiscais; None não cobra. As tarifas da EasyPost não incluem imposto sobre vendas. Padrão: Taxable.

Tarifas de contingência

Usadas quando não há tarifa em tempo real: falta a chave de API, a EasyPost não pode ser acessada, a chave é recusada ou nenhuma transportadora tem tarifa para o endereço. Os preços são na moeda da loja. Deixe os dois campos vazios para ocultar o método nesse caso.

Country prices: uma linha por país: código do país com duas letras, dois-pontos e o preço, por exemplo US:9.99. Linhas em outro formato são ignoradas e listadas em uma mensagem de erro ao salvar.

Other countries: o preço para os países que não estão na lista acima. Deixe vazio para ocultar o método para eles.

Condições

Free shipping from: o subtotal do carrinho a partir do qual o envio é grátis. Nesse caso, nenhuma requisição é feita à EasyPost. Deixe vazio para desativar.

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

Minimum weight: oculta o método quando o carrinho pesa menos, na unidade de peso da loja. 0 significa sem limite.

Maximum weight: oculta o método quando o carrinho pesa mais, na unidade de peso da loja. 0 significa sem limite.

Disabled shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de envio do WooCommerce.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método para os países abaixo, esteja ele ou não adicionado a uma zona.

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

Avançado

Debug log: grava as requisições à EasyPost em WooCommerce > Status > Logs, origem vfd-easypost. Erros de API são sempre registrados, mesmo com esta opção desativada. A chave de API e os endereços dos clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações e os métodos nas zonas. Desativar o plugin 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: país de entrega, peso do carrinho, subtotal mínimo e classes de envio desativadas. Se o frete grátis se aplicar, o método é exibido com valor zero e nenhuma requisição é feita à EasyPost.

Caso contrário, o plugin envia à EasyPost o endereço de origem, o endereço de entrega e o pacote, e recebe as tarifas de todas as suas contas de transportadoras. Ele escolhe a tarifa permitida mais barata, converte para a moeda da loja e a exibe com o nome do seu método. Para países que exigem CEP, a requisição só é feita depois que o cliente o informa.

Cada resposta fica em cache por 1 hora para o mesmo endereço e o mesmo pacote. Um endereço sem tarifas utilizáveis é lembrado por 10 minutos. Após um tempo limite, uma chave recusada, um limite de requisições (rate limit) ou um erro do servidor da EasyPost, nenhuma requisição é feita por 5 minutos. O tempo limite da API é de 10 segundos. Em todos esses casos, o cliente não vê nenhum erro: usa-se a tarifa de contingência, ou o método fica oculto se não houver tarifa de contingência.

A transportadora e o serviço escolhidos e, no modo de um pacote, os dias de entrega estimados são salvos na linha de envio do pedido. Você os vê na tela do pedido no admin.

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

O plugin calcula apenas tarifas. Ele não compra etiquetas, não rastreia pacotes, não valida endereços, não oferece pontos de retirada ou postagem e não adiciona opções de seguro ou assinatura. Mostra uma opção (a tarifa permitida mais barata), não uma lista de serviços. Não há embalagem em caixas além de empilhar os itens em um pacote, nem acréscimo sobre a tarifa ou taxa de manuseio.

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 EasyPost. 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 na 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 vaga na sua conta na vibefox.net.

Sem uma chave ativa, a EasyPost não é exibida aos clientes na finalização de compra. Os gerentes da loja conectados ainda a veem, marcada com (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. Os 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 de forma automática em segundo plano.

Solução de problemas

A EasyPost 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, Minimum subtotal e Disabled shipping classes. Sem tarifa em tempo real, o método precisa de uma tarifa de contingência para o país ou para Other countries.

As tarifas em tempo real não aparecem: leia os avisos no topo da página de configurações, depois ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-easypost. Motivos comuns: falta a chave de API ou o CEP de origem, loja que não está em USD sem USD exchange rate, o cliente ainda não informou um CEP, nenhuma transportadora da sua conta EasyPost atende o endereço, ou os filtros de Allowed carriers / services excluem todas as tarifas.

As tarifas parecem preços de teste: uma chave de teste (EZTK...) está definida. Use uma chave de produção (EZAK...) na loja ativa.

As tarifas pararam por alguns minutos: após um tempo limite, uma chave recusada ou um erro do servidor da EasyPost, o plugin pausa as requisições por 5 minutos e usa as tarifas de contingência. Verifique a chave de API e o log.

O imposto está incluído? As tarifas da EasyPost não incluem imposto sobre vendas. Com o Tax status em Taxable, o WooCommerce cobra imposto sobre o envio conforme as suas configurações fiscais.

As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa o cache de tarifas da EasyPost.

Hooks para desenvolvedores: os filtros vfd_ep_shipment_request (corpo da requisição), vfd_ep_selected_rate (tarifa escolhida), vfd_ep_api_url (URL base da API) e woocommerce_shipping_vfd_easypost_is_available ajustam o plugin.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na 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 todas as configurações e apenas limpa o cache de tarifas. 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, o cache de tarifas e os arquivos de log antigos são sempre removidos. Configurações e métodos de zona são removidos somente se Remove data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas linhas de envio.

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