VibeFox PostNL for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superiores (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Chave de API da PostNL (somente para pontos de retirada): os pontos de retirada são carregados pela API Checkout da PostNL. Clientes business 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. A opção de entrega em domicílio não precisa de chave.

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

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 vfd_postnl-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_postnl.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. Nopainel de administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_postnl-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, por isso você não precisa atualizar Extensions > Modifications. Em vez do Installer, você pode copiar o conteúdo da pasta upload do pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox PostNL e clique em Install (o botão verde +).

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações.

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

5. Ative PostNL pickup point e/ou PostNL home address e 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.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_postnl.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox PostNL, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença e as configurações como nos passos 4 e 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Após a instalação, as duas opções ficam desativadas até que você ative uma delas e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da PostNL que você manteve voltam a ser usadas.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox PostNL > Edit. As seções ficam listadas à esquerda. Um único botão Save na parte inferior salva a página inteira sem recarregá-la. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

Se um valor estiver errado, nada é salvo e a página mostra o motivo: um nome de opção vazio, com mais de 64 caracteres ou contendo < > ; = # { }; uma ordem de exibição que não é um número inteiro; um peso mínimo acima do peso máximo; ou uma classe de imposto ou zona geográfica inválida. Problemas menores são salvos com uma observação: um número inválido ou negativo deixa o seu campo vazio, um CEP de envio inválido é salvo vazio e um preço inválido na tabela é ignorado.

Acima das configurações, a página mostra avisos: chave de API ou CEP de envio ausente para os pontos de retirada, sandbox ativado, nenhum preço definido, a última requisição à PostNL que falhou com a data e o erro, ou uma loja sem uma classe de peso "kg".

Geral

Cada tipo de entrega é uma opção própria na finalização de compra. As configurações desta página valem para as duas.

PostNL pickup point: ativa ou desativa a opção de ponto de retirada. O cliente precisa escolher um ponto da PostNL na finalização de compra. Ela só é oferecida para endereços dos Países Baixos e da Bélgica e somente com uma chave de API. Padrão: desativado.

Pickup point option name: o nome que o cliente vê na finalização de compra. Padrão: PostNL pickup point. Obrigatório, até 64 caracteres, sem < > ; = # { }.

PostNL home address: ativa ou desativa a opção de entrega em domicílio. Nenhum ponto é escolhido. Ela funciona para todos os países com um preço. Padrão: desativado.

Home delivery option name: o nome que o cliente vê na finalização de compra. Padrão: PostNL. Mesmas regras do nome do ponto de retirada.

Sort order: a posição da PostNL entre os métodos de envio na finalização de compra. Um número inteiro.

Tax class: a classe de imposto das duas opções. Com uma classe de imposto, o OpenCart acrescenta o seu imposto aos preços. No tax significa que os preços são finais.

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

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

Remove the saved API key: marque a caixa e clique em Save para excluir a chave salva. A opção 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 passam a ver pontos de retirada de teste. Mantenha-o desativado em uma loja em produção.

Ship from (country): o país em que você entrega as suas encomendas à PostNL: Países Baixos ou Bélgica. A PostNL usa o endereço do remetente para a data de coleta. Na instalação, ele é definido como o país da loja, se for Países Baixos ou Bélgica; caso contrário, como Países Baixos.

Ship from (postcode): o CEP do remetente, por exemplo 1234AB nos Países Baixos ou 1000 na Bélgica. Obrigatório para os pontos de retirada: o OpenCart não tem um CEP da loja, por isso ele não é obtido do endereço da loja. Um CEP 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 opções. A PostNL não tem uma API pública de tarifas, por isso a extensão não solicita tarifas em tempo real. Para um cliente que paga em outra moeda, o OpenCart 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 botão × para removê-la. Escolha * All other countries para uma linha que abranja todos os países sem linha própria. Cada linha tem um Price e classes de peso opcionais conforme o 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. O preço de uma classe de peso substitui o Price; deixe-o vazio para usar o Price. Um Price de 0 significa frete grátis. "6.95" e "6,95" são aceitos. As linhas sem preços são removidas 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) o multiplica pelo número de itens que precisam de envio.

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

Condições

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

Minimum subtotal: mostra as opções somente quando o subtotal do carrinho chega a pelo menos este valor. Deixe vazio para sempre mostrá-las.

Minimum weight (kg): oculta as opções quando o carrinho pesa menos. Os pesos dos produtos são convertidos a partir da classe de peso. Deixe vazio para não ter limite.

Maximum weight (kg): oculta as opções para carrinhos mais pesados. As encomendas da PostNL chegam até 30 kg no Benelux. 0 significa sem limite. Se deixar vazio, valem 30 kg, ou sem limite quando Ignore shipping zones está ativado.

Todos os valores e pesos aceitam a vírgula decimal.

Disponibilidade

Geo zone: oferece a PostNL somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. A zona geográfica não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Ignore shipping zones: quando ativado, a zona geográfica não é verificada e a PostNL é oferecida para os países selecionados abaixo (todos os países se a lista estiver vazia). Quando desativado, só a zona geográfica conta.

Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativado. A opção de ponto de retirada continua sendo oferecida somente para os Países Baixos e a Bélgica.

Avançado

Debug log: grava mensagens de depuração em storage/logs/vfd_ptnl_debug.log.php (no OpenCart 4 system/storage/logs/vfd_ptnl_debug.log.php). O arquivo não pode ser lido pela web. Erros da API e pedidos sem um ponto de retirada válido são sempre registrados. Nenhuma chave de API nem dado de cliente é gravado. Desative o log quando terminar. Quando o arquivo chega a 5 MB, um novo log é iniciado.

Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para limpá-lo.

Remove data on uninstall: quando ativado, a desinstalação da extensão apaga as configurações da PostNL e o log. As listas de pontos em cache são sempre removidas. Os pontos de retirada salvos nos pedidos são sempre mantidos.

Importação / Exportação

Exportação: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API não é exportada.

Importação: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. A chave de API salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço de cada opção da PostNL. Se Ignore shipping zones estiver ativado, a PostNL só é oferecida para um país permitido, independentemente da zona geográfica. Caso contrário, se houver uma Geo zone definida, o endereço precisa estar nela. Somente os produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no subtotal. A extensão verifica o peso do carrinho e o subtotal mínimo. Depois, pega o preço da tabela para o país e a classe de peso, ou o preço para outros países. Se não houver preço, a opção fica oculta. Se o subtotal do carrinho alcançar Free shipping from, o preço é 0. O preço é exibido ao cliente em sua moeda, com o imposto da Tax class selecionada.

A opção de ponto de retirada só é oferecida para endereços dos Países Baixos e da Bélgica, e somente com uma chave de API. Quando o endereço de entrega tem um CEP completo, a extensão pede à API Checkout da PostNL os três pontos de retirada mais próximos. Ela envia o CEP do cliente, a rua e o número, a cidade e o país, além do endereço de envio da sua loja. Nada é enviado para a opção de entrega em domicílio. Se a PostNL não puder ser acessada ou não tiver pontos para o endereço, a opção de ponto de retirada fica oculta e a 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 endereço, e as respostas "sem pontos" por 1 hora. As requisições que falham ficam em cache por 10 minutos, para que uma indisponibilidade não deixe lenta cada atualização da finalização de compra. O cache é mantido na tabela de banco de dados própria da extensão. O último erro é exibido na página da extensão até a próxima requisição bem-sucedida.

A extensão não solicita tarifas da PostNL em tempo real e não cria etiquetas de envio, códigos de barras, rastreamento, devoluções nem pré-avisos. Não há opções de entrega no dia, à noite ou pela manhã. Crie a remessa no Mijn PostNL ou em outra ferramenta da PostNL usando o ponto de retirada salvo.

No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe uma opção da PostNL na janela Shipping method options. Os preços são os mesmos do OpenCart 3.

Pontos de retirada

Quando o endereço de entrega está nos Países Baixos ou na Bélgica, aparece uma lista PostNL pickup point abaixo da opção de ponto de retirada com os três pontos mais próximos: nome da empresa, endereço e distância, do mais próximo para o mais distante. A página nunca espera pela PostNL: se a lista ainda não estiver em cache, ela é carregada assim que a opção é selecionada. Antes de o CEP completo ser informado, o cliente vê "Enter your postcode (for example 1234 AB) to see PostNL pickup points." (4 dígitos para a Bélgica). O ponto escolhido é salvo imediatamente para a finalização de compra.

O ponto é obrigatório. Quando o cliente clica em Continue na etapa de método de envio, o servidor confere o ponto com a lista da PostNL para o endereço de entrega. Sem um ponto, o cliente vê "Please choose a PostNL pickup point." Se o ponto não estiver na lista, o cliente vê "The chosen PostNL pickup point is not available for this address. Please choose it again." Se a PostNL não puder ser acessada, o cliente vê "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method." 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, não do navegador.

Páginas do pedido, e-mails e nota fiscal: o ponto é adicionado ao método de envio do pedido, por exemplo "PostNL pickup point: nome, endereço" (o nome da opção de ponto de retirada e, depois, o ponto) (até 128 caracteres, no OpenCart 4 até 255). Ele aparece em todos os lugares onde o OpenCart exibe o método de envio: o histórico de pedidos do cliente, os e-mails do pedido, a nota fiscal e Sales > Orders.

Página do pedido na administração: em Sales > Orders, a página do pedido mostra acima do histórico um painel PostNL pickup point com o ponto, o Location code e o Partner ID. Ele aparece somente para pedidos com um ponto salvo, inclusive depois que a extensão é desativada.

No OpenCart 4 a lista de pontos aparece na janela Shipping method options, abaixo da opção PostNL pickup point, e é carregada de novo sempre que a janela é aberta, porque o endereço pode mudar na finalização de compra em uma única página. O botão Continue da janela não avança sem um ponto válido, com as mesmas mensagens. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo, e o ponto do pedido é atualizado junto.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox PostNL é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox PostNL > Edit, 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 ficam a linha Product: opencart-shipping-postnl e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 com 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, as opções de envio da PostNL não são exibidas aos clientes na finalização de compra e nenhum preço de envio é calculado. Um usuário administrador conectado ao admin no mesmo navegador ainda vê as opções na loja, marcadas como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login do admin, então, sem uma chave ativa, as opções ficam ocultas para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do admin ou a página Edit: 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 a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A PostNL não aparece na finalização de compra: confira se a licença está ativa e se PostNL pickup point ou PostNL home address está ativado. Confira a Geo zone (ou se Ignore shipping zones está ativado e o país é permitido), se há um preço definido para o país, os limites de peso e o Minimum subtotal. Confira se os produtos têm Requires Shipping definido como Yes.

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

"PostNL pickup points cannot be loaded right now": a PostNL não pôde ser acessada, recusou a chave de API ou o CEP de envio está faltando. A página da extensão mostra o último erro. Uma chave de sandbox só funciona com o Sandbox ativado, e uma chave de produção só com ele desativado.

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

Os pesos dos produtos parecem errados: se a página da extensão avisar que a loja não tem uma classe de peso "kg", confira em System > Localisation > Weight Classes. Os pesos dos produtos são convertidos pelo nome da unidade da sua classe, e unidades desconhecidas são lidas como kg.

A página mostra "Warning: You do not have permission to modify VibeFox PostNL!": o seu grupo de usuários administradores só pode visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_postnl (OpenCart 3) ou extension/vfd_postnl/shipping/vfd_postnl (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API da PostNL pode ser substituído pela configuração vfd_ptnl_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox PostNL. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine o status da extensão, Sort order, Tax class e Geo zone. As listas de pontos em cache e o último erro da API são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da PostNL, o log de depuração e os pontos das finalizações de compra que nunca se tornaram pedidos também são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas ao reinstalar a extensão. Os pedidos existentes mantêm o método de envio, o custo e o ponto de retirada salvo.

No OpenCart 4, para remover também os arquivos da extensão, depois da desinstalação acesse Extensions > Installer e clique em Uninstall (o botão laranja −) ao lado de VibeFox PostNL na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A PostNL é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela PostNL.