VibeFox Shippo 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 Shippo: crie uma conta na Shippo, conecte ou ative as transportadoras (USPS, UPS, FedEx, DHL e outras) e copie o token de API em Shippo > Settings > Advanced > API. A Shippo cobra pelas etiquetas compradas, não pelas requisições de tarifas. Contas novas na Shippo podem precisar ser verificadas pela Shippo antes que tarifas em tempo real sejam retornadas. Sem token, somente os preços de contingência são usados.

Produtos: os produtos devem ter peso e dimensões. Produtos sem dimensões usam a caixa padrão.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_shippo para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

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

5. Cole seu token de API da Shippo e preencha o endereço Ship from. O CEP é obrigatório.

6. Escolha a Shippo rate currency (USD se você envia dos EUA) e, se sua loja usa outra moeda, informe a taxa de câmbio.

7. Opcionalmente, informe os preços de contingência na tabela por país e peso.

8. Adicione VibeFox Shippo 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 estão em uma única página: WooCommerce > Settings > Shipping > VibeFox Shippo. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome que o cliente vê para esta zona. Deixe em branco para usar o Name global.

Sempre que você salva as configurações, as tarifas da Shippo em cache são apagadas. Os avisos acima das configurações informam quando o método nunca pode ser exibido ou quando tarifas em tempo real não podem ser usadas: sem token de API, sem CEP ou país de origem, ou sem taxa de câmbio. Um aviso lembra quando um token de teste está definido.

Geral

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

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

Conta Shippo

API token: seu token de API da Shippo. Use o token de produção (shippo_live_...) para tarifas reais na loja em produção, ou um token de teste (shippo_test_...) para as tarifas de teste da Shippo.

Allowed carriers / services: opcional, separado por vírgulas. Informe uma transportadora como a Shippo a nomeia (USPS, UPS, FedEx, DHL Express) ou um token de nível de serviço da Shippo (usps_priority, ups_ground). É mostrada a tarifa permitida mais barata. Deixe em branco para mostrar a tarifa mais barata de qualquer transportadora.

Ship from (o endereço de onde seus pacotes são enviados; campos vazios são preenchidos com o endereço da loja em WooCommerce > Settings > General, quando ele está no mesmo país)

Sender name / company: o nome do remetente. Ele também é usado para assinar a declaração alfandegária.

Street address: a rua do remetente.

City: a cidade do remetente.

State / province: o código do estado com duas letras, por exemplo CA ou NY. Algumas transportadoras exigem.

Postal / ZIP code: obrigatório para tarifas em tempo real.

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

Tarifas

Parcels: como o carrinho é enviado à Shippo.

Default box size: comprimento x largura x altura na unidade de dimensão da sua loja, por exemplo 30 x 20 x 10. A Shippo precisa do tamanho da caixa. Ele é usado quando um produto do carrinho não tem dimensões. Deixe em branco para usar 30 x 20 x 10 cm.

Shippo rate currency: a moeda em que a Shippo cota suas transportadoras, que é a moeda do país de origem: USD (EUA), CAD (Canadá), GBP (Reino Unido), EUR (zona do euro) ou AUD (Austrália). Padrão: USD. Tarifas que a Shippo retorna na moeda da loja são sempre usadas como estão.

Exchange rate: o preço de 1 unidade da Shippo rate currency na moeda da sua loja, por exemplo 0.92. Não é necessário quando as duas são iguais. Sem ele, as tarifas na outra moeda não são usadas e valem os preços de contingência. O plugin não converte moedas automaticamente.

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

Preços de contingência (usados quando não há tarifa em tempo real: sem token de API, Shippo inacessível, token recusado ou nenhuma tarifa de transportadora para o endereço; preços na moeda da loja; deixe os dois campos vazios para ocultar o método nesse caso)

Country prices: uma tabela de preços por país 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 (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Uma faixa vazia ou 0 usa a coluna Price. A linha * Default vale para países sem linha própria. Uma nova linha começa como * Default. Uma linha salva com todas as células vazias cobra 0, por isso exclua as linhas que você não preencher.

Other countries: o preço para países que não estão na tabela acima (quando não há linha * Default). Deixe em branco para ocultar o método para eles.

Condições

Free shipping from: o subtotal do carrinho a partir do qual o envio é gratuito. Nesse caso, nenhuma requisição é feita à Shippo. Deixe em branco para desativar.

Minimum subtotal: mostra o método somente se o subtotal do carrinho for pelo menos este valor. Deixe em branco para exibi-lo sempre.

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

Maximum weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 30. 0 significa sem limite.

Disabled shipping classes: oculta o método se o carrinho contiver um produto de 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 ou não adicionado a uma zona.

Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais a loja envia. Este campo é usado somente quando Ignore shipping zones está ativado. Um método adicionado a uma zona de envio sempre funciona para os países da sua zona.

Avançado

Debug log: registra as requisições à Shippo em WooCommerce > Status > Logs, origem vfd-shippo. Erros da API são sempre registrados, mesmo com esta opção desativada. O token 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 seus métodos nas zonas de envio. 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: peso do carrinho, subtotal mínimo e classes de envio desativadas. Se o envio gratuito se aplicar, o método é exibido com preço 0 e nenhuma requisição é feita à Shippo.

Em seguida, o plugin envia à Shippo o endereço de origem, o endereço do cliente e o pacote. Para países em que o WooCommerce exige CEP, a requisição aguarda até o cliente informá-lo. Em envios internacionais, é adicionada uma declaração alfandegária com nomes, quantidades, pesos e valores dos itens. A Shippo retorna as tarifas das suas transportadoras, e o plugin mostra a tarifa permitida mais barata na moeda da loja, sob o nome do método.

No modo por pedido, os itens são empilhados em uma caixa: o lado mais longo e o lado médio dos maiores itens, e os menores lados de todas as unidades somados. Se algum produto não tiver dimensões, a caixa padrão é usada para todo o pacote. No modo por item, cada produto é tarifado como um pacote próprio e a tarifa é multiplicada pela quantidade.

Cada resposta fica em cache por 1 hora por endereço e pacote. Quando a Shippo responde sem uma tarifa utilizável, o endereço é lembrado por 10 minutos. Após um timeout, um token recusado, um erro do servidor ou um limite de requisições, o plugin pausa as requisições por 5 minutos e usa os preços de contingência. O timeout da requisição é de 10 segundos.

Se não houver tarifa em tempo real, o preço vem da tabela de contingência e, depois, de Other countries. Se nenhum dos dois se aplicar, o método fica oculto. O cliente nunca vê um erro.

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

O plugin calcula apenas tarifas. Ele não compra etiquetas, não rastreia pacotes, não valida endereços e não oferece pontos de retirada ou de entrega, seguro, opções de assinatura ou etiquetas de devolução. Somente a tarifa permitida mais barata é exibida, não uma lista de todos os serviços. Não há empacotamento de caixas além do empilhamento descrito acima, nem markup de tarifa ou taxa de manuseio.

Pedidos

A linha de envio do pedido armazena a Carrier / service escolhida e, para um pacote por pedido, os Estimated delivery days. Você os vê na tela de administração do pedido e pode comprar a etiqueta correspondente na Shippo.

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 Shippo. 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 informar 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 domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta na vibefox.net.

Sem uma chave ativa, a Shippo não é exibida aos clientes na finalização de compra. Os gerentes da loja conectados continuam vendo, 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 automaticamente em segundo plano.

Solução de problemas

A Shippo não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado 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, confira se o país, * Default ou Other countries tem um preço.

As tarifas em tempo real não aparecem: ative Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-shippo. Motivos comuns: sem token de API ou CEP de origem, moeda da loja diferente da Shippo rate currency sem taxa de câmbio, CEP do cliente ainda não informado, nenhuma transportadora da sua conta Shippo atende o endereço ou a conta Shippo ainda não foi verificada.

Testar tarifas na loja em produção: um token de teste (shippo_test_...) retorna tarifas de teste da Shippo. Use o token de produção (shippo_live_...).

Frete grátis para países inesperados: confira a tabela de preços em busca de uma linha vazia, especialmente uma linha * Default vazia. Uma linha com todas as células vazias cobra 0.

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

Para desenvolvedores: os filtros vfd_shpo_shipment_request, vfd_shpo_customs_declaration, vfd_shpo_selected_rate e vfd_shpo_api_url alteram o corpo da requisição, a declaração alfandegária, a tarifa escolhida e a URL da API.

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 estiver acessível, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. 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 as tarifas em cache, são sempre removidos. Configurações e métodos nas zonas só são removidos se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas linhas de envio.

Shippo é uma marca de propriedade de seu respectivo titular. Este plugin não é afiliado à Shippo nem endossado pela Shippo.