VibeFox Canada Post for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
Canada Post Developer Program (somente para tarifas em tempo real): as tarifas em tempo real usam a Rating API da Canada Post. Inscreva-se no Canada Post Developer Program no site da Canada Post e copie a sua chave de API e o seu número de cliente. A chave de API tem o formato usuário:senha, e a Canada Post fornece chaves separadas para os ambientes de desenvolvimento (sandbox) e de produção. Você também precisa 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 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_canada_post para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Canada Post, 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, informe o nome de usuário e a senha da API, o seu número de cliente e o código postal de envio. Se a moeda da sua loja não for CAD, informe a taxa em CAD. Preencha Country prices se quiser preços fixos ou um valor de contingência (veja Configuração).
6. Adicione VibeFox Canada Post às suas zonas 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 Canada Post. 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 exibido ao cliente nesta zona. Deixe vazio para usar o Method title global.
Sempre que você salva as configurações, as tarifas da Canada Post em cache são apagadas. A página também mostra um erro quando as configurações não podem funcionar: apenas um dos campos nome de usuário e senha da API está preenchido, o código postal de envio não é canadense, falta a taxa em CAD para uma loja em outra moeda, ou não há chaves de API nem preços fixos.
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. Padrão: Canada Post. Uma zona pode usar o próprio título.
Tax status: Taxable adiciona o imposto do WooCommerce ao custo de envio; None não adiciona.
API da Canada Post (tarifas em tempo real)
Com o nome de usuário e a senha da API preenchidos, o preço vem da Rating API da Canada Post. Se a API não retornar uma tarifa (API indisponível, código postal errado, serviço não disponível), usa-se o preço fixo de Country prices, ou o método fica oculto se não houver nenhum.
API username: a parte da chave de API antes dos dois-pontos. Use a chave de desenvolvimento com Sandbox e a chave de produção em uma loja real.
API password: a parte da chave de API depois dos dois-pontos. Ela nunca é gravada no log.
Customer number: com um número de cliente, a Canada Post retorna as tarifas comerciais (com desconto) da sua conta. Deixe vazio para as tarifas de balcão.
Contract number: opcional, para clientes com contrato. É usado somente junto com o número de cliente.
Sandbox: usa o ambiente de desenvolvimento da Canada Post, para testar com a chave de API de desenvolvimento. Os preços são dados de teste. Desative em uma loja real.
Ship-from postal code: o código postal canadense de onde os pacotes são enviados, por exemplo K1A 0B1. As tarifas em tempo real precisam dele.
Service in Canada: o serviço para endereços canadenses: Cheapest available, Regular Parcel (padrão), Expedited Parcel, Xpresspost ou Priority.
Service to the USA: Cheapest available (padrão), Expedited Parcel USA, Tracked Packet USA, Small Packet USA Air, Xpresspost USA ou Priority Worldwide parcel USA.
International service: Cheapest available (padrão), International Parcel Surface, International Parcel Air, Tracked Packet International, Small Packet International Surface, Small Packet International Air, Xpresspost International ou Priority Worldwide parcel International.
Se o serviço escolhido não for oferecido para o endereço ou o pacote, usa-se o serviço disponível mais barato.
Canadian sales taxes: usa os preços da Canada Post sem GST/HST/PST. Para endereços canadenses, o preço da Canada Post inclui esses impostos. Ative quando o WooCommerce cobra o imposto sobre o envio (Tax status = Taxable), para que o imposto não seja cobrado duas vezes.
CAD → store currency rate: o nome do campo mostra a moeda da sua loja. Os preços da Canada Post estão em CAD. Se a moeda da sua loja não for CAD, informe quantas unidades da sua moeda vale um CAD, por exemplo 0.68. Sem isso, as tarifas em tempo real não são usadas. Se a moeda da sua loja for CAD, deixe vazio. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Default product weight (kg): enviado à Canada Post para cada produto sem peso. Padrão: 0.5. Pesos e dimensões dos produtos são convertidos a partir das unidades da sua loja, e o carrinho é calculado como um único pacote.
Preços fixos (usados sem credenciais de API e como alternativa quando a API não retorna uma tarifa)
Country prices: uma tabela de países com um preço Base e preços conforme o peso do carrinho na moeda da loja: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou zero usa o preço Base. Clique em Add country para adicionar uma linha e no × para remover uma. A linha * Default (all other countries) define os preços de todos os países sem linha própria. Um país sem linha (e sem *) não tem preço fixo. Um preço base de 0 significa envio grátis para esse país.
Fixed price per: Order cobra o preço uma vez. Item (price × quantity) multiplica-o pelo número de itens no carrinho. Isso vale apenas para preços fixos. As tarifas em tempo real são sempre calculadas para o pacote inteiro.
Condições
Min cart weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite.
Max cart weight (kg): oculta o método acima deste peso do carrinho. Padrão: 25. 0 significa sem limite. Pacotes da Canada Post podem pesar até 30 kg.
Minimum order amount: exibe o método somente quando o subtotal do carrinho atinge este valor. Deixe vazio para exibi-lo sempre.
Excluded shipping classes: oculta o método se algum item do carrinho tiver uma destas classes de envio do WooCommerce.
Free shipping: ativa a entrega grátis a partir do valor abaixo.
Free shipping from: o subtotal do carrinho a partir do qual o envio é grátis. Nesse caso, nenhuma requisição é feita à API.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o método para os países abaixo, independentemente da zona que corresponder.
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: registra os cálculos de tarifas em WooCommerce > Status > Logs, origem vfd-canada-post. Erros da API são sempre registrados, mesmo com esta opção desativada. Chaves de API, números de cliente e códigos postais dos clientes não são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações, métodos das zonas 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 uma tarifa ao plugin. O plugin verifica primeiro as condições: peso do carrinho, valor mínimo do pedido e classes de envio excluídas. Se o envio grátis se aplicar, o cliente recebe uma tarifa grátis e nenhuma requisição é enviada à Canada Post.
Com chaves de API, o plugin envia à Canada Post o código postal de envio, o destino, o peso do pacote e, quando todos os produtos têm dimensões, o tamanho estimado do pacote. Para o Canadá o destino é o código postal, para os EUA o código ZIP, e para os demais países apenas o país. Uma tarifa em tempo real só é solicitada quando um endereço canadense ou americano tem um código postal ou ZIP válido. A Canada Post retorna todos os serviços do pacote; o plugin escolhe o serviço selecionado para o grupo de destino ou o mais barato, remove os impostos sobre vendas canadenses se Canadian sales taxes estiver ativado, e converte o preço em CAD com a sua taxa. O nome do serviço é salvo com o pedido e exibido na tela do pedido no admin como Canada Post service.
Cada resposta fica em cache por 1 hora, então o mesmo carrinho e o mesmo endereço não geram uma nova requisição. Uma requisição com falha fica em cache por 10 minutos, para que uma queda da Canada Post não deixe lenta cada atualização da finalização de compra. O tempo limite da API é de 10 segundos. Pacotes acima de 30 kg não são enviados à API.
Se a API não retornar uma tarifa, usa-se o preço fixo, ou o método fica oculto quando não há preço fixo. O cliente nunca vê os detalhes dos erros da API; eles vão para o log do WooCommerce.
O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalizar compra. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin calcula somente tarifas. Ele não cria envios, não imprime etiquetas, não cria manifestos nem devoluções e não rastreia pacotes. Os clientes não podem escolher uma agência dos correios nem um ponto de retirada. Ele mostra uma única tarifa da Canada Post, sem datas de entrega, seguro ou opções de assinatura. O carrinho é sempre calculado como um único pacote, e as taxas de câmbio não são atualizadas 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 Canada Post. 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 de novo, Change key para inserir 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 do domínio. Libere-a na sua conta vibefox.net.
Sem uma chave ativa, a Canada Post não é exibida aos clientes na finalização de compra. Os gerentes da loja conectados continuam vendo-a, 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. 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 de novo automaticamente em segundo plano.
Solução de problemas
A Canada Post 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). Verifique os limites de peso, Minimum order amount e Excluded shipping classes. Deve existir uma tarifa: com chaves de API, o endereço precisa de um código postal válido (Canadá) ou ZIP (EUA); caso contrário, deve existir um preço fixo para o país ou para *.
As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-canada-post. O log mostra o motivo: nome de usuário ou senha da API ausentes, código postal de envio ou de destino inválido, taxa em CAD ausente, pacote acima de 30 kg, ou a mensagem de erro da Canada Post. Enquanto isso, os clientes recebem o preço fixo, se houver.
A tarifa é diferente da do site da Canada Post: com um número de cliente, você obtém as tarifas comerciais (com desconto) da sua conta; sem ele, as tarifas de balcão. Para endereços canadenses, o preço da Canada Post inclui GST/HST/PST. Os preços são convertidos com a sua taxa CAD.
O imposto é cobrado duas vezes sobre o envio: ative Canadian sales taxes ou defina Tax status como None.
Teste os preços em uma loja real: desative Sandbox e use a chave de API de produção.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as tarifas da Canada Post em cache.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já está em uso em outro domínio, libere uma vaga na sua conta 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 de licença deste plugin são sempre removidos. Configurações, métodos das zonas e tarifas em cache são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos nunca são alterados.
A Canada Post é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Canada Post.