VibeFox PostNL for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x, tema Classic ou Hummingbird (ou um tema baseado neles).

PHP: 8.0 ou superior. O módulo recusa a instalação em versões mais antigas do PHP.

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 em Mijn PostNL, em My account > API beheren. O sandbox da PostNL precisa de uma chave de sandbox separada. A transportadora de entrega em domicílio não precisa de chave.

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.

2. Quando o envio terminar, clique em Configure, ou encontre depois VibeFox PostNL na lista de módulos e clique em Configure.

3. Insira sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).

4. 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). Clique em Save.

Na instalação, o módulo cria duas transportadoras: PostNL pickup point, com o texto de prazo Delivery to a PostNL pickup point, e PostNL, com PostNL delivery to the home address. Ambas estão vinculadas às zonas dos Países Baixos e da Bélgica e a todos os grupos de clientes. Você pode adicionar zonas e alterar grupos de clientes, prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox PostNL > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. No WooCommerce, um método é adicionado duas vezes a uma zona, uma para cada tipo de entrega. No PrestaShop, cada tipo de entrega é uma transportadora própria, com nome, status e zonas próprios.

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, a última requisição à PostNL que falhou com data e erro, uma unidade de peso da loja que o módulo não reconhece e uma transportadora excluída.

Geral

PostNL pickup point: liga ou desliga a transportadora de ponto de retirada. O cliente precisa escolher um ponto da PostNL na finalização de compra. Ela é oferecida apenas para endereços nos Países Baixos e na Bélgica, e somente com chave de API. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Pickup point carrier name: o nome que o cliente vê na finalização de compra. Padrão: PostNL pickup point. Obrigatório.

PostNL home address: liga ou desliga a transportadora de entrega em domicílio. Nenhum ponto é escolhido. Ela funciona para qualquer país com preço. Mesmo interruptor do status da transportadora.

Home delivery carrier name: o nome que o cliente vê na finalização de compra. Padrão: PostNL. Obrigatório.

Tax status: a regra de imposto das duas transportadoras. Uma regra Taxable acrescenta aos preços o imposto de entrega dessa regra. None significa que os preços são finais.

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

API key: sua chave de API da PostNL, obtida em Mijn PostNL (My account > API beheren). Ela é enviada à PostNL no cabeçalho "apikey" e nunca é mostrada aos clientes nem gravada no log. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um novo valor apenas para alterá-lo.

Remove the saved API key: marque a caixa e clique em Save para excluir a chave salva. A transportadora de ponto de retirada deixa de ser oferecida.

Sandbox: usa o sandbox da PostNL (api-sandbox.postnl.nl) com uma chave de API de sandbox. Os clientes veem então 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, Netherlands ou Belgium. Padrão: Netherlands. 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 Shop Parameters > Contact > Stores quando a loja estiver no mesmo país. Um código postal inválido é salvo vazio com um aviso. 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 e o último erro da API são apagados.

Preços (na moeda padrão da loja, sem impostos)

Os preços valem para as duas transportadoras. A PostNL não tem uma API pública de tarifas, por isso o módulo não consulta tarifas em tempo real. Para um cliente que paga em outra moeda, o PrestaShop converte o preço com a taxa de câmbio da sua loja.

Price per country: uma linha por país de destino. Clique em + Add country para adicionar uma linha e no ícone de lixeira para removê-la. 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-o vazio para usar o Price. Um Price de 0 significa entrega grátis. São aceitos "6.95", "6,95" e valores com separador de milhar, como "1.234,50" ou "1,234.50". 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 um aviso.

Calculation: Per order cobra o preço uma vez. Per item (price x quantity) multiplica pelo número de itens que precisam de entrega.

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

Condições

Free shipping from: o subtotal do carrinho (produtos que precisam de entrega, sem impostos, após descontos) a partir do qual a entrega é grátis. Aplica-se apenas onde um preço é encontrado. Deixe vazio para nunca oferecer entrega grátis.

Minimum subtotal: mostra as transportadoras somente quando o subtotal do carrinho for pelo menos este valor. Deixe vazio para sempre mostrá-las.

Minimum weight (kg): oculta as transportadoras quando o carrinho pesa menos. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. Deixe vazio para não ter limite.

Maximum weight (kg): oculta as transportadoras para carrinhos mais pesados. Padrão: 30 (pacotes da PostNL vão até 30 kg no Benelux). 0 significa sem limite. Se deixar vazio, 30 kg valem nas zonas das transportadoras, e sem limite vale apenas para os países alcançados por Ignore zones. Um peso mínimo acima do máximo é recusado com um erro, porque as transportadoras nunca seriam mostradas.

Todos os valores e pesos aceitam vírgula decimal, também com separador de milhar. Um número inválido ou negativo é ignorado com um aviso, e o campo é salvo vazio.

Disponibilidade sem zonas de entrega

Normalmente, as transportadoras são oferecidas nas zonas de entrega às quais estão vinculadas em Shipping > Carriers.

Ignore zones: oferece também a PostNL nos países abaixo, que as zonas dela não incluem. As transportadoras passam então a ser vinculadas a todas as zonas ativas, inclusive às que você criar depois. Ao desligar novamente, as transportadoras voltam às zonas que tinham antes.

Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Este campo só é usado quando Ignore zones está ativado. Nesses países, as duas transportadoras podem ser oferecidas; a de ponto de retirada, porém, apenas para os Países Baixos e a Bélgica.

Avançado

Debug log: grava mensagens de depuração em logs/vfd_ptnl_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados. Nenhuma chave de API nem dado de cliente é gravado. Desative o log quando terminar.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações e as transportadoras da PostNL. Quando desativado, desinstalar apenas desativa as transportadoras. Os pontos de retirada salvos nos pedidos são sempre mantidos.

Como funciona na finalização de compra

Na etapa de entrega, o PrestaShop pede ao módulo o preço de cada transportadora da PostNL. Só contam produtos físicos: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica as condições: peso do carrinho e subtotal mínimo. Em seguida, 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, a transportadora é ocultada. Se o subtotal do carrinho atingir Free shipping from, o preço é 0.

A transportadora de ponto de retirada só é oferecida para endereços nos Países Baixos e na Bélgica, e somente com chave de API. Quando o endereço de entrega tem um código postal válido, o módulo consulta a PostNL Checkout API pelos três 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 seu endereço de envio. Nada é enviado para a transportadora de entrega em domicílio. Se a PostNL não puder ser acessada ou não tiver pontos para o endereço, a transportadora de ponto de retirada é ocultada e a de entrega em domicílio continua disponível. 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 instabilidade não deixe lenta cada atualização da finalização de compra. O último erro aparece na página do módulo.

Se você editar uma transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.

O módulo não consulta tarifas da PostNL em tempo real e não cria etiquetas de envio, códigos de barras, track and trace, devoluções nem pré-avisos. Não tem opções de entrega em dia específico, à 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 a transportadora de ponto de retirada, aparece abaixo dela uma lista PostNL pickup point com os três pontos mais próximos: nome da empresa, endereço e distância. A página nunca espera pela PostNL: se a lista ainda não estiver em cache, ela é carregada assim que a transportadora é selecionada. Antes de um código postal completo ser digitado, o cliente vê "Digite seu código postal (por exemplo 1234 AB) para ver os pontos de retirada da PostNL." (4 dígitos para a Bélgica). O ponto escolhido é salvo no carrinho e mantido quando a finalização de compra é atualizada.

O ponto é obrigatório. Sem ele, o cliente não pode continuar e vê "Escolha um ponto de retirada da PostNL." Quando o cliente clica em Continue, o servidor confere o ponto com a lista da PostNL para o endereço de entrega. Se ele não estiver na lista, o cliente vê "O ponto de retirada da PostNL escolhido não está disponível para este endereço. Escolha-o novamente." Se a PostNL não puder ser acessada, o cliente vê "Os pontos de retirada da PostNL não podem ser carregados agora. Tente novamente em alguns minutos ou escolha outro método de entrega." Um ponto escolhido para outro endereço nunca é usado no pedido. O nome e o endereço salvos com o pedido vêm da PostNL, e não do navegador.

Página do pedido no administrativo: um bloco PostNL pickup point com nome e endereço, o Location code e o Partner ID.

Páginas de confirmação e de detalhes do pedido: PostNL pickup point com nome e endereço.

E-mails de pedido: o nome e o endereço do ponto são acrescentados ao nome da transportadora no e-mail de confirmação do pedido. O e-mail de novo pedido da loja (módulo Mail alerts) também mostra o código de localização.

Chave de licença

O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox PostNL é o primeiro bloco de Modules > Module Manager > VibeFox PostNL > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-shipping-postnl e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, as transportadoras da PostNL não são mostradas aos clientes na finalização de compra e nenhuma tarifa de envio é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então as transportadoras também ficam ocultas para você: você pode configurar o módulo antes de comprar uma chave, mas não pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar o módulo sempre remove a chave de licença e o status da licença. A redefinição deste módulo não apaga dados, então a chave e o status são mantidos.

Solução de problemas

A PostNL não aparece na finalização de compra: verifique se a licença está ativa e se o interruptor da transportadora está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou se Ignore zones está ativado e o país é permitido). Verifique se há um preço definido para o país, os limites de peso e o Minimum subtotal. Os produtos também podem ser limitados a certas transportadoras na página do produto.

A transportadora de ponto de retirada não aparece: ela só é mostrada para endereços holandeses e belgas, somente com chave de API, código postal de envio e preço, e somente quando a PostNL retorna pontos para o código postal do cliente. Confira os avisos no topo da página do módulo e o campo Log. Os erros são sempre registrados; ative o Debug log para ver detalhes.

"PostNL pickup points cannot be loaded right now": a PostNL não pôde ser acessada, rejeitou a chave de API ou o código postal de envio está ausente. A página do módulo mostra o último erro. Uma chave de sandbox funciona somente com o Sandbox ativado, e uma chave de produção somente com ele desativado.

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

Os pesos dos produtos parecem errados: se a página do módulo avisar que a unidade de peso da loja não é conhecida, defina uma unidade padrão (kg, g, lb ou oz) em International > Localization, em Local units. Até lá, os pesos dos produtos são lidos como kg.

A página diz que uma transportadora da PostNL não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente. A redefinição mantém suas configurações e o status das transportadoras.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox PostNL e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As listas de pontos de retirada em cache e o último erro da API são sempre removidos. Se Remove data on uninstall estiver ativado, as transportadoras são excluídas (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, as transportadoras apenas são desativadas e todas as configurações são mantidas. Instalar o módulo novamente devolve às transportadoras o status que tinham. Os pedidos existentes mantêm suas linhas de entrega e o ponto de retirada salvo.

A PostNL é marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela PostNL.