VibeFox NZ Post 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.
Acesso à API do NZ Post (somente para tarifas em tempo real): as tarifas em tempo real usam a API ShippingOptions do NZ Post. Solicite o acesso à API no Developer Resource Centre, no site do NZ Post. O NZ Post fornece um Client ID e um Client Secret, primeiro para o ambiente de testes (UAT) e depois para produção, após a checklist de entrada em operação. Para as tarifas dentro da Nova Zelândia, você também precisa de uma conta comercial do NZ Post: o número da conta e o seu auth code (ou site code). Se você usar apenas preços fixos, não precisa de acesso à API.
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_nz_post para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox NZ Post, ou clique em Settings embaixo 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 as tarifas em tempo real, preencha a seção NZ Post API (live rates). Opcionalmente, insira preços fixos, que são usados sem tarifas em tempo real e como alternativa (veja Configuração).
6. Adicione o VibeFox NZ Post a uma zona de entrega 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 NZ Post. 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 que os clientes veem para esta zona. Deixe vazio para usar o Method title geral.
Sempre que você salva as configurações, as tarifas do NZ Post e os tokens de acesso em cache são apagados. Se as tarifas em tempo real não puderem funcionar com os valores salvos (apenas um entre Client ID e Client Secret, sem taxa de conversão NZD, dados incompletos para tarifas nacionais), um aviso aparece acima das configurações.
General
Enable/Disable: ativa ou desativa o método em todas as zonas de uma só vez.
Method title: o nome do método de entrega exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: NZ Post.
Tax status: Taxable adiciona o imposto do WooCommerce ao custo de entrega; None não adiciona. Veja também API prices abaixo.
NZ Post API (tarifas em tempo real) (deixe o Client ID vazio para usar somente preços fixos)
Environment: Production (api.nzpost.co.nz) (padrão) ou Testing / UAT (api.uat.nzpost.co.nz). Use o ambiente para o qual o seu Client ID foi emitido.
Client ID: o ID de cliente OAuth2 do seu aplicativo da API do NZ Post.
Client Secret: o segredo de cliente OAuth2. Ele é trocado por um token de acesso, que fica em cache até expirar.
Account number: o número da sua conta comercial (de cobrança) do NZ Post. É obrigatório para tarifas dentro da Nova Zelândia. Para tarifas internacionais é opcional; com ele, o NZ Post retorna as suas tarifas contratuais.
Auth code: o auth code da conta para tarifas nacionais. Não é necessário se você informar um site code.
Site code: a alternativa ao auth code: o código do seu ponto de coleta do NZ Post.
Ship-from suburb: o bairro do endereço de onde os pacotes são enviados, por exemplo Petone. É necessário para tarifas nacionais.
Ship-from city: a cidade ou localidade de onde os pacotes são enviados, por exemplo Lower Hutt. É necessária para tarifas nacionais.
Ship-from postcode: o código postal neozelandês de 4 dígitos de onde os pacotes são enviados, por exemplo 5012. É necessário para tarifas nacionais.
Services: códigos opcionais de serviço do NZ Post, separados por vírgula, por exemplo CPOLP, ICOU. Somente esses serviços são precificados. Deixe vazio para usar o serviço mais barato retornado pelo NZ Post para o pacote.
API prices: Including GST (padrão) ou Excluding GST. Os preços nacionais do NZ Post incluem 15% de GST; o frete internacional tem alíquota zero. Escolha Excluding GST quando Tax status for Taxable, para que o GST não seja cobrado duas vezes.
NZD → (store currency) rate: os preços do NZ Post são em NZD. Se a moeda da sua loja não for NZD, informe quantas unidades da sua moeda vale um NZD, por exemplo 0.55. Sem esse valor, as tarifas em tempo real não são usadas. A mesma taxa converte o valor do pedido enviado nas solicitações internacionais. Se a moeda da sua loja for NZD, deixe vazio.
Pacote para tarifas em tempo real
O carrinho é enviado ao NZ Post como um único pacote. Pesos e dimensões dos produtos são convertidos das unidades da sua loja para kg e cm. O pacote assume o maior comprimento e a maior largura dos produtos, e sua altura aumenta até caber o volume de todos os itens. Os valores abaixo são usados para produtos sem peso ou dimensões.
Default product weight (kg): usado para cada produto sem peso. Padrão: 0.5.
Default parcel length (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 30.
Default parcel width (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 20.
Default parcel height (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 10.
Preços fixos (usados quando as tarifas em tempo real não estão configuradas ou o NZ Post não retorna uma tarifa)
Os preços estão na moeda da loja.
Country prices: uma linha por país de destino. Clique em + Add country para adicionar uma linha e no X para removê-la. Escolha * Default para uma linha que cubra todos os outros países. Cada linha tem um preço Any weight e colunas de peso opcionais: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg e > 5 kg (peso do carrinho). Uma coluna de peso preenchida substitui Any weight; uma coluna vazia ou com 0 usa Any weight. Um preço Any weight de 0 significa frete grátis para esse país. Tanto "9.99" quanto "9,99" são aceitos. Linhas sem nenhum preço, códigos de país inválidos e preços negativos são removidos ao salvar. Só é mantida uma linha por país.
Fallback cost: usado quando nem a API nem a tabela de países fornecem um preço. Deixe vazio para ocultar o método nesse caso.
Fixed price per: Order cobra o preço uma vez. Item (price × quantity) o multiplica pelo número de itens do carrinho. Isso vale apenas para preços fixos e para o custo de contingência. As tarifas em tempo real são sempre calculadas para o pacote 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: 25 (pacotes de courier do NZ Post pesam até 25 kg). 0 significa sem limite.
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 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 a entrega pelo NZ Post é grátis. Vale somente quando o método tem um preço: um preço por país ou o custo de contingência (então nenhuma solicitação é enviada ao NZ Post), ou uma tarifa em tempo real. Deixe vazio para nunca oferecer frete grátis.
Para essas condições, o peso do carrinho considera os produtos sem peso como 0.
Disponibilidade sem zonas de entrega
Ignore shipping zones: oferece o NZ Post para os países abaixo, mesmo que o método não esteja adicionado a nenhuma zona de entrega.
Countries: os países de destino para este 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-nz-post"). Erros da API são sempre registrados, mesmo com o log de depuração desativado. Credenciais, tokens e endereços de clientes não são registrados. Desative o log quando terminar.
Remove data on uninstall: quando ativado, ao excluir o plugin são removidos suas configurações, os métodos das zonas e as 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: 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 do NZ Post em tempo real, em seguida a tabela de países e, por fim, o custo de contingência. 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 as tarifas em tempo real configuradas, o plugin obtém um token de acesso com o seu Client ID e o seu Client Secret e pede um preço ao NZ Post. Para um endereço na Nova Zelândia, ele envia os dados da sua conta, o endereço de origem, o bairro, a cidade e o código postal do cliente, além do peso e do tamanho do pacote. O WooCommerce não tem campo de bairro: o plugin usa o Address line 2 quando ele contém o nome de um bairro; caso contrário, usa a cidade ou localidade. Uma tarifa nacional só é solicitada depois que o cliente informa uma cidade e um código postal de 4 dígitos. Para outros países, envia o país de destino, o peso e o tamanho do pacote e o valor do pedido em NZD.
É usado o serviço permitido mais barato que tenha preço, incluindo sobretaxas e adicionais obrigatórios. O preço é convertido de NZD para a moeda da sua loja. O serviço com preço é salvo com o pedido como NZ Post service e fica visível na tela do pedido. Cada resposta fica em cache por 1 hora. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere o NZ Post a cada atualização. O tempo limite da API é de 10 segundos. Um token de acesso expirado é renovado automaticamente.
Se o NZ Post não retornar uma tarifa (API não configurada, erro, endereço incompleto, serviço indisponível, sem taxa NZD), o cliente não vê nenhum erro. Usa-se o preço da tabela de países e, depois, o custo de contingência. Se não houver preço fixo, o método fica oculto. O motivo é gravado no log.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin calcula apenas tarifas. Ele não gera etiquetas de envio, não agenda coletas, não gera manifestos, não rastreia pacotes, não valida endereços e não permite que os clientes escolham um ponto de retirada, uma caixa postal (PO Box) ou um armário de encomendas (parcel locker). O carrinho é precificado como um único pacote, e o cliente vê uma tarifa do NZ Post, não uma lista de serviços.
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 NZ 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 novamente, 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 vaga na sua conta na vibefox.net.
Sem uma chave ativa, o NZ Post não é exibido aos clientes na finalização de compra. Os gerentes da loja que estão conectados ainda o veem, marcado 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. Pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
O NZ Post 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á ligado e o país é permitido). Confira os limites de peso, Minimum order amount e Excluded shipping classes. Se o NZ Post não retornar uma tarifa, o método só é exibido com um preço por país ou com um Fallback cost.
As tarifas em tempo real não aparecem: abra WooCommerce > Status > Logs, origem "vfd-nz-post". Os erros da API sempre estão lá. Ative o Debug log para ver detalhes. O log mostra o motivo: Client ID ou Client Secret ausentes, token rejeitado, dados da conta ou do endereço de origem ausentes, cidade ou código postal do cliente ainda não informados, sem taxa NZD ou nenhum serviço com preço. Enquanto você corrige o problema, os preços fixos são usados.
A solicitação de token falha: verifique o Client ID, o Client Secret e o Environment. Credenciais de UAT não funcionam em produção, e vice-versa.
As tarifas nacionais estão ausentes, as internacionais funcionam: as tarifas dentro da Nova Zelândia exigem o Account number, o Auth code ou o Site code, além do endereço de origem completo com código postal de 4 dígitos. O cliente precisa informar uma cidade e um código postal de 4 dígitos. Desenvolvedores podem alterar o bairro enviado para o endereço de entrega com o filtro vfd_nzpt_delivery_suburb.
A minha loja não usa NZD: informe a NZD → (store currency) rate. Os preços fixos são sempre na moeda da loja.
O GST é cobrado duas vezes na entrega: os preços nacionais do NZ Post incluem 15% de GST. Se o Tax status for Taxable, defina o API prices como Excluding GST.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as tarifas e os tokens do NZ Post em cache.
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 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 são sempre removidos. Configurações, métodos de zona, tarifas em cache e tokens de acesso só são removidos se o Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas linhas de entrega.
O NZ Post é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo NZ Post.