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

Chave de API da PostNL (somente para pontos de retirada): os pontos de retirada são carregados pela PostNL Checkout API. Os clientes empresariais da PostNL encontram a chave de API no Mijn PostNL em My account > API beheren. O sandbox da PostNL precisa de uma chave de sandbox separada. Os métodos de entrega em domicílio não precisam de chave.

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox PostNL, 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. Preencha os preços. Para os pontos de retirada, informe também a API key da PostNL e o Ship from (postcode) (veja Configuração).

6. Adicione o VibeFox PostNL a uma zona de entrega em WooCommerce > Settings > Shipping > Shipping zones, por exemplo Países Baixos e Bélgica. Na zona, defina o Title e o Delivery to. Adicione o método uma segunda vez para o outro tipo de entrega.

Configuração

Todas as configurações, exceto o título e o tipo de entrega, ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox PostNL. Elas valem para todas as zonas de entrega. Ao adicionar o método a uma zona, a janela da zona tem dois campos:

Title (zone): o nome que o cliente vê para este método da zona. Deixe vazio para usar o Name global.

Delivery to (zone): As in the global settings (padrão), PostNL pickup point (customer chooses a point) ou Home address. Adicione o método duas vezes a uma zona para oferecer os dois.

Acima das configurações, a página mostra avisos: chave de API ou código postal de envio ausente para os pontos de retirada, sandbox ativado, nenhum preço definido e a última requisição com falha à PostNL, com data e erro.

Geral

Enable/Disable: liga ou desliga a entrega pela PostNL em todas as zonas de uma vez.

Name: o nome do método de entrega exibido na finalização de compra. Um Title definido na zona o substitui. Padrão: PostNL.

Delivery to: o tipo de entrega padrão para os métodos de zona que usam As in the global settings, e para o modo Ignore zones.

Tax status: Taxable adiciona o imposto do WooCommerce ao custo da entrega, None não adiciona.

API PostNL (pontos de retirada) (não necessária para entrega em domicílio)

API key: sua chave de API da PostNL, obtida no Mijn PostNL (My account > API beheren). Ela é enviada à PostNL no cabeçalho "apikey", armazenada no banco de dados do WordPress e nunca exibida aos clientes nem gravada no log.

Sandbox: usa o sandbox da PostNL (api-sandbox.postnl.nl) com uma chave de API de sandbox. Os clientes passam a ver pontos de retirada de teste. Mantenha desativado em uma loja em produção.

Ship from (country): o país de onde você entrega seus pacotes à PostNL, Países Baixos ou Bélgica. Por padrão, é o país da sua loja. A PostNL usa o endereço do remetente para a data de coleta.

Ship from (postcode): o código postal do remetente, por exemplo 1234AB nos Países Baixos ou 1000 na Bélgica. Deixe vazio para usar o código postal da loja em WooCommerce > Settings > General quando a loja estiver no mesmo país. Um código postal inválido é recusado com uma mensagem. Ao alterar a chave de API, a configuração do sandbox ou o endereço de envio, as listas de pontos de retirada em cache são apagadas.

Preços (na moeda da loja)

A PostNL não tem uma API pública de tarifas, por isso o plugin não consulta tarifas em tempo real e nunca converte preços.

Price per country: uma linha por país de destino. Clique em + Add country para adicionar uma linha e no X para remover uma. Escolha * All other countries para uma linha que cobre todos os países sem linha própria. Cada linha tem um Price e faixas de peso opcionais pelo peso do carrinho: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 5 kg. Um preço de faixa de peso substitui o Price; deixe vazio para usar o Price. Um Price de 0 significa entrega grátis. Tanto "6.95" quanto "6,95" são aceitos. Linhas vazias e códigos de país inválidos são removidos ao salvar. Se um país aparecer duas vezes, a primeira linha é mantida. Preços inválidos são ignorados com uma mensagem.

Calculation: Per order cobra o preço uma única vez. Per item (price x quantity) multiplica pelo número de itens enviáveis no carrinho.

Price for other countries: usado quando a tabela não tem o país nem uma linha *. Deixe vazio para ocultar o método ali.

Condições

Free shipping from: o subtotal do carrinho a partir do qual a entrega é grátis. Vale somente onde um preço for encontrado. Deixe vazio para nunca oferecer entrega grátis.

Minimum subtotal: exibe o método somente quando o subtotal do carrinho for pelo menos este valor. Deixe vazio para exibi-lo sempre.

Minimum weight (kg): oculta o método quando o carrinho pesa menos. Os pesos dos produtos são convertidos a partir da unidade da sua loja. Deixe vazio para nenhum limite.

Maximum weight (kg): oculta o método para carrinhos mais pesados. Padrão: 30 (pacotes da PostNL chegam a 30 kg no Benelux). Deixe vazio para nenhum limite.

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

Todos os valores e pesos aceitam vírgula decimal, também com separador de milhar (1.234,50 ou 1,234.50). Um número inválido é ignorado com uma mensagem.

Disponibilidade sem zonas de entrega

Ignore zones: oferece também a PostNL nos países abaixo quando nenhuma zona a adiciona. As zonas que contêm o método continuam funcionando normalmente. Este modo usa o Name e o Delivery to globais.

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

Avançado

Debug log: grava mensagens de depuração em WooCommerce > Status > Logs (origem "vfd-postnl"). Erros da API são sempre registrados. Nenhuma chave de API ou dado do cliente é gravado. Desative o log quando terminar.

Remove data on uninstall: se ativado, excluir o plugin remove as configurações da PostNL e os métodos de zona. Desativar o plugin nunca apaga as configurações. Os pontos de retirada salvos nos pedidos são sempre mantidos.

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 as condições: peso do carrinho, subtotal mínimo e classes de entrega. Depois pega o preço da tabela para o país e a faixa de peso, ou o preço para outros países. Se não houver preço, o método fica oculto. Se o subtotal do carrinho atingir o Free shipping from, o preço é 0.

Um método com ponto de retirada só é oferecido para endereços nos Países Baixos e na Bélgica e somente com uma chave de API. Assim que o cliente informa um código postal válido, o plugin consulta a PostNL Checkout API pelos pontos de retirada mais próximos. Ele envia o código postal, a rua, o número, a cidade e o país do cliente, além do endereço de envio da sua loja. Nada é enviado para os métodos de entrega em domicílio. Se a PostNL não puder ser acessada ou não retornar pontos para o endereço, o método com ponto de retirada fica oculto e os seus outros métodos continuam disponíveis. O tempo limite da API é de 12 segundos.

As listas de pontos ficam em cache por 6 horas por código postal, e as respostas "sem pontos" por 1 hora. Requisições com falha ficam em cache por 10 minutos, para que uma indisponibilidade não deixe lenta cada atualização da finalização de compra. O último erro aparece na tela de configurações.

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 não consulta tarifas em tempo real da PostNL e não cria etiquetas de envio, códigos de barras, track and trace, devoluções nem pré-alertas. Não há opções de dia de entrega, entrega à noite ou pela manhã. Crie o envio no Mijn PostNL ou em outra ferramenta da PostNL usando o ponto de retirada salvo.

Pontos de retirada

Quando o cliente seleciona um método com ponto de retirada, aparece uma lista de PostNL pickup point abaixo dele com os três pontos mais próximos: nome da empresa, endereço e distância. Antes de informar um código postal, o cliente vê a mensagem "Informe seu código postal (por exemplo 1234 AB) para ver os pontos de retirada da PostNL." (4 dígitos para a Bélgica). A escolha é lembrada quando a finalização de compra é atualizada.

O ponto é obrigatório. Sem um ponto, a finalização de compra para com a mensagem "Escolha um ponto de retirada da PostNL." O servidor confere o ponto com a lista da PostNL para o endereço de entrega. Se ele não estiver na lista, a finalização de compra para com a mensagem "O ponto de retirada da PostNL escolhido não está disponível para este endereço. Escolha-o novamente." O nome e o endereço salvos com o pedido vêm da PostNL, não do navegador.

Tela do pedido no administrativo: PostNL pickup point com o nome, o endereço e o Location code, abaixo do endereço de entrega.

Página de agradecimento e visualização do pedido em Minha conta: PostNL pickup point com o nome e o endereço.

E-mails de pedido: o nome e o endereço do ponto nos e-mails em HTML e em texto simples.

No banco de dados, o ponto é salvo nos metadados do pedido _vfd_ptnl_servicepoint_id (código de localização da PostNL), _vfd_ptnl_servicepoint_name (nome e endereço) e _vfd_ptnl_servicepoint (ID do parceiro, empresa, rua, número, código postal, cidade, país).

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

Sem uma chave ativa, a PostNL não é exibida aos clientes na finalização de compra. Os administradores da loja logados 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 de forma automática em segundo plano.

Solução de problemas

A PostNL não aparece na finalização de compra: verifique se a licença está ativa, se o Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se o Ignore zones está ligado e o país é permitido). Confira se há um preço definido para o país, os limites de peso, o Minimum subtotal e o Hide for shipping classes.

O método com ponto de retirada não aparece: ele só é exibido para endereços holandeses e belgas, somente com uma chave de API, um código postal de envio e um preço, e somente quando a PostNL retorna pontos para o código postal do cliente. Confira os avisos no topo da tela de configurações e em WooCommerce > Status > Logs, origem "vfd-postnl". Os erros são sempre registrados; ative o Debug log para ver detalhes.

"Os pontos de retirada da PostNL não podem ser carregados agora": a PostNL não pôde ser acessada, rejeitou a chave de API ou o código postal de envio está ausente. A tela de configurações mostra o último erro. Uma chave de sandbox só funciona com o Sandbox ligado, e uma chave de produção só com ele desligado.

Os clientes veem pontos de retirada de teste: desligue o Sandbox.

Filtros para desenvolvedores: vfd_ptnl_number_of_locations (padrão 3), vfd_ptnl_checkout_request (corpo da requisição) e vfd_ptnl_api_url.

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 da 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 as listas de pontos de retirada em cache. 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, junto com as listas de pontos em cache e o último erro da API. Configurações e métodos de zona são removidos somente se o Remove data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas linhas de entrega e o ponto de retirada salvo.

A PostNL é uma marca registrada do respectivo titular. Este plugin não é afiliado nem endossado pela PostNL.