VibeFox Purolator for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

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

PHP: 8.0 ou superior. A extensão SOAP do PHP não é necessária.

Purolator E-Ship Web Services (somente para tarifas em tempo real): cadastre-se no E-Ship Web Services no Purolator E-Ship Resource Centre, no site da Purolator. A Purolator fornece chaves e senhas separadas para os ambientes de desenvolvimento e de produção. Você também precisa do número da sua conta de faturamento Purolator e do código postal canadense de onde envia. Se usar apenas preços fixos, não precisa de chaves de API.

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_purolator para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

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

5. Para tarifas em tempo real, preencha a seção Purolator API (live rates). Para testes, ative Development environment com a chave de desenvolvimento. Preencha Country prices ou Fallback price se quiser preços fixos ou um preço alternativo (veja Configuração).

6. Adicione VibeFox Purolator 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 Purolator. 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 que o cliente vê nesta zona. Deixe vazio para usar o Method title global.

Sempre que você salvar as configurações, as tarifas da Purolator em cache são apagadas. Se as tarifas em tempo real não puderem funcionar com os valores salvos (chave, senha ou conta ausentes, nenhum código postal canadense de envio, nenhuma taxa de CAD), ou se não houver credenciais de API nem preços fixos, um aviso aparece acima das configurações.

Geral

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

Method title: o nome do método de envio exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: Purolator.

Tax status: Taxable adiciona o imposto do WooCommerce ao custo do envio, None não adiciona. Veja também Canadian sales taxes abaixo.

API da Purolator (tarifas em tempo real)

Com a chave de API, a senha e a conta de faturamento preenchidas, o preço vem do serviço web Purolator E-Ship Estimating. Se a Purolator não retornar uma tarifa, usa-se o preço fixo, ou o método fica oculto se não houver nenhum.

API key: a sua chave do E-Ship Web Services para o ambiente selecionado.

API password: a senha correspondente à chave.

Billing account number: o número da sua conta Purolator. As estimativas usam as tarifas desta conta. O ambiente de desenvolvimento aceita a conta de teste da documentação da Purolator.

Development environment: usa o ambiente de desenvolvimento da Purolator (devwebservices.purolator.com) com a chave de desenvolvimento. Os preços são dados de teste. Desative em uma loja em produção.

Ship-from postal code: o código postal canadense de onde os pacotes são enviados, por exemplo L4W 5M8.

Service in Canada: Cheapest available (padrão), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM ou Purolator Express Evening.

Service to the USA: Cheapest available (padrão), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM ou Purolator Express U.S. 12:00.

International service: Cheapest available (padrão), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM ou Purolator Express International 12:00.

Se o serviço escolhido não for oferecido para o endereço, usa-se o mais barato disponível.

Canadian sales taxes: para endereços canadenses, o total da Purolator inclui GST/HST/PST/QST. Ative Use Purolator prices without GST/HST/PST/QST quando Tax status estiver em Taxable, para que o imposto não seja cobrado duas vezes.

CAD → (store currency) rate: os preços da Purolator são em CAD. Se a moeda da sua loja não for CAD, informe quantas unidades da sua moeda equivalem a 1 CAD, por exemplo 0.68. Sem esse valor, as tarifas em tempo real não são usadas. Se a moeda da loja for CAD, deixe vazio.

Default product weight (kg): usado para cada produto sem peso. Padrão: 0.5. Os pesos são convertidos da unidade da loja e enviados à Purolator como peso total em libras inteiras, arredondado para cima.

Preços fixos (usados sem credenciais de API e como alternativa quando a API não retorna tarifa)

Country prices: um preço por país e peso do carrinho na moeda da loja. Clique em + Add country para adicionar uma linha e no X para remover uma. Escolha * Default (all other countries) para uma linha que cobre todos os países sem linha própria. Cada linha tem um preço Base e colunas de tamanho: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg e XL acima de 5 kg. Um preço de tamanho vazio ou zero usa Base. Um Base de 0, ou um Base vazio, significa frete grátis para os pesos sem preço de tamanho próprio. Linhas sem nenhum preço e códigos de país inválidos são removidos ao salvar. Só uma linha por país é mantida.

Fallback price: o preço para um país que não tem linha em Country prices nem linha *. Deixe vazio para ocultar o método nesses países.

Fixed price per: Order cobra o preço uma vez. Item (price × quantity) multiplica pelo número de itens do carrinho. Isso vale só para preços fixos. As tarifas em tempo real são sempre calculadas para o envio inteiro.

Condições

Min cart weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.

Max cart weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite.

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

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

Free shipping from: o subtotal do carrinho a partir do qual o envio é grátis. Vale apenas onde o método tem preço: um preço por país ou o preço alternativo (então nenhuma solicitação é enviada à Purolator), ou uma tarifa em tempo real. Deixe vazio para nunca oferecer envio grátis.

O peso do carrinho para estas condições conta produtos sem peso como 0. Preços e pesos aceitam vírgula ou ponto como separador decimal.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece a Purolator para os países abaixo, mesmo que o método não esteja adicionado a nenhuma zona de envio.

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

Avançado

Debug log: grava os cálculos de tarifas em WooCommerce > Status > Logs (origem "vfd-purolator"). Erros da API são sempre registrados, mesmo com o log de depuração desativado. Chaves de API, conta de faturamento e códigos postais dos clientes não são registrados. Desative o log quando terminar.

Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações, métodos de zona e tarifas em cache. Desativar o plugin nunca apaga nada.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede ao plugin uma tarifa. O plugin verifica primeiro as condições: país de entrega, peso do carrinho, valor mínimo do pedido e classes de envio excluídas. Depois procura um preço: a tarifa em tempo real da Purolator, depois a tabela por país e, por fim, o preço alternativo. Se não houver preço, o método fica oculto. Se o frete grátis se aplicar, o cliente vê o método sem custo.

Com credenciais de API, o plugin envia à Purolator uma solicitação Quick Estimate: a sua conta de faturamento, o código postal de origem, a cidade, província ou estado do cliente, o país e o código postal, e o peso total do carrinho em libras inteiras. Para o Canadá é preciso um código postal válido; para os EUA, um ZIP code válido; os demais países são enviados com o código postal como foi digitado. Dimensões (peso dimensional) não são enviadas. A Purolator retorna os preços de todos os serviços; o plugin usa o serviço que você escolheu ou o mais barato, remove os impostos sobre vendas canadenses se configurado e converte o preço de CAD. O serviço é salvo com o pedido como Purolator service e aparece na tela do pedido no admin.

Cada resposta fica em cache por 1 hora. Uma solicitação com falha fica em cache por 10 minutos, para que uma queda da Purolator não deixe lenta cada atualização da finalização de compra. O tempo limite da API é de 10 segundos.

Se a Purolator não retornar uma tarifa (API indisponível, credenciais ou código postal incorretos, serviço indisponível, nenhuma taxa de CAD), o cliente não vê erro. Usa-se o preço fixo, ou o método fica oculto se não houver preço fixo. O motivo é gravado no log.

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 High-Performance Order Storage (HPOS) do WooCommerce.

O plugin calcula apenas tarifas. Ele não cria envios Purolator, não imprime etiquetas, não agenda coletas, não trata devoluções e não rastreia pacotes. Não usa o Full Estimate (dimensões, várias peças, opções como assinatura ou mercadorias perigosas), não mostra datas de entrega, não exibe vários serviços como tarifas separadas e não busca taxas de câmbio automaticamente.

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 Purolator. 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 em vibefox.net.

Uma chave funciona em um 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 Purolator não é exibida aos clientes na finalização de compra. Os 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 Purolator 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 order amount e Excluded shipping classes. Se a Purolator não retornar tarifa, o método só é exibido com um preço por país, uma linha * ou um Fallback price.

As tarifas em tempo real não aparecem: abra WooCommerce > Status > Logs, origem "vfd-purolator". Erros da API sempre aparecem ali. Ative o Debug log para ver os detalhes. Com chaves de API, o endereço precisa ter um código postal válido (Canadá) ou um ZIP code válido (EUA).

HTTP 401 no log: a chave ou a senha da API não corresponde ao ambiente selecionado. Chaves de desenvolvimento funcionam apenas com Development environment ativado; chaves de produção, somente com ele desativado.

A tarifa é diferente da do site da Purolator: o Quick Estimate usa as tarifas da sua conta de faturamento e o peso total arredondado para cima em libras inteiras, sem peso dimensional. Para endereços canadenses, o total inclui impostos sobre vendas; use Canadian sales taxes se o WooCommerce adicionar imposto sobre o envio. Os preços são convertidos com a sua CAD → (store currency) rate.

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

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 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 todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. Configurações, métodos de zona e tarifas em cache só são removidos se Remove data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas linhas de envio.

A Purolator é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Purolator.