VibeFox PostNord 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 PostNord (para o seletor de ponto de serviço): crie uma conta gratuita em developer.postnord.com, adicione um aplicativo e copie a chave de API dele. Sem a chave, o método de envio continua funcionando, mas os clientes não conseguem escolher um ponto de serviço.

Contrato com a PostNord: para enviar encomendas, você precisa do seu contrato de cliente PostNord habitual, por exemplo MyPack Collect ou MyPack Home.

Chave de licença VibeFox: adquirida 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_postnord-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_postnord.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. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_postnord-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então 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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox PostNord e clique em Install (o botão verde +).

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

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

5. Ative Enable/Disable (entrega em ponto de serviço) e/ou Home delivery, cole a API key da PostNord, escolha o Agreement country, preencha os Country prices ou um Fallback cost (veja Configuração) e clique em Save.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_postnord.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 PostNord, 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 e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da PostNord 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 PostNord > Edit. As seções aparecem à esquerda. Um botão Save na parte inferior salva a página inteira sem recarregá-la. Cada salvamento também limpa as listas de pontos de serviço em cache. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.

Se um valor estiver incorreto, nada é salvo e a página mostra o motivo: um nome vazio, com mais de 64 caracteres ou que contém < > ; = # { }, uma ordem de classificação que não é um número inteiro, um status de imposto ou uma zona geográfica inválidos, ou um Min weight (kg) maior que o Max weight (kg). Um campo numérico com valor que não seja um número igual ou maior que 0 é salvo vazio, com uma mensagem. Uma célula da tabela de preços que não seja um número igual ou maior que 0 é salva como 0, com uma mensagem.

Acima das configurações, a página avisa quando ainda não há chave de API, quando ainda não há nenhum preço e quando a loja não tem a classe de peso "kg".

Geral

As duas opções de entrega são oferecidas na zona geográfica definida em Availability, ou para os países de Ignore shipping zones.

Enable/Disable: ativa ou desativa a entrega PostNord em um ponto de serviço ou em um armário de encomendas. O cliente escolhe o ponto na finalização de compra. Padrão: desativado.

Name: o nome da opção de ponto de serviço na finalização de compra, por exemplo "PostNord MyPack Collect". Padrão: PostNord. Obrigatório, até 64 caracteres, sem < > ; = # { }.

Home delivery: oferece também a entrega domiciliar PostNord, uma segunda opção sem ponto de serviço. Padrão: desativado.

Home delivery name: o nome da opção de entrega domiciliar na finalização de compra, por exemplo "PostNord MyPack Home". Padrão: PostNord Home delivery. Mesmas regras de Name.

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

Tax status: None (the prices are final) (padrão), ou uma classe de imposto: nesse caso o OpenCart soma aos preços o imposto de envio dessa classe. Vale para as duas opções.

API PostNord (seletor de ponto de serviço)

API key: a chave de API do seu aplicativo em developer.postnord.com. Ela é enviada à PostNord apenas a partir do seu servidor, nunca ao navegador, e nunca é gravada no log. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um novo valor somente se quiser alterá-la.

Remove the saved API key: marque a caixa e clique em Save para excluir a chave salva.

Test mode: usa o ambiente de teste da PostNord (atapi2.postnord.com). Somente para chaves emitidas para o ambiente de teste.

Agreement country: o país do seu contrato de cliente PostNord: Suécia, Dinamarca, Noruega ou Finlândia. Ele determina quais pontos de serviço são oferecidos. Same as the delivery country (padrão) usa o país do cliente.

Preços

O título da seção mostra a moeda padrão da sua loja. Os preços estão nessa moeda, sem impostos, e são iguais para as duas opções. A PostNord não tem uma API pública de preços, então você define os seus, normalmente os preços do seu contrato com a PostNord. A ordem é: limite para frete grátis, depois a tabela por país e, por último, o custo de reserva.

Calculation type: Per order (padrão) cobra o preço uma vez. Per item (price x number of items) multiplica o preço pela quantidade de itens no carrinho.

Country prices: um preço por país de destino e peso do carrinho. Clique em Add country para adicionar uma linha e no botão × para removê-la. Cada linha tem uma coluna Price e colunas de peso: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 5 kg. Uma coluna de peso com 0 usa a coluna Price, e um Price de 0 significa frete grátis. O país * All other countries cobre todos os países que não têm linha própria. Decimais com vírgula ou ponto (9,99 ou 9.99). Uma nova linha começa como * All other countries com todos os preços em 0. Escolha o país e informe os preços antes de salvar, ou remova a linha. Uma célula vazia é salva como 0.

Fallback cost: usado quando a tabela de países não tem linha para o destino nem linha *. Deixe vazio para ocultar a PostNord para esses países.

Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após o cupom, sem impostos) a partir do qual a PostNord é gratuita. Ele é verificado antes da tabela por país, então vale também para um país sem linha de preço. Deixe vazio para nunca oferecer frete grátis.

Disponibilidade

Min weight (kg): oculta a PostNord quando o carrinho pesa menos. Os pesos dos produtos são convertidos a partir da classe de peso deles. Padrão: 0, que significa sem limite.

Max weight (kg): oculta a PostNord quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite. Verifique o limite de peso do seu serviço PostNord: os armários de encomendas aceitam menos que os pontos de serviço.

Minimum subtotal: mostra a PostNord somente se o subtotal do carrinho (produtos que precisam de envio, após o cupom, sem impostos) for pelo menos este valor. Deixe vazio para mostrar sempre.

Geo zone: oferece a PostNord somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usada enquanto Ignore shipping zones estiver ativado.

Ignore shipping zones: quando ativado, a zona geográfica não é verificada e a PostNord é oferecida para os países abaixo. Quando desativado, ela é oferecida somente na zona geográfica.

Countries (Ignore shipping zones): 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.

Avançado

Debug log: grava os cálculos de taxas e as chamadas de API em storage/logs/vfd_ptnd_debug.log.php. O arquivo não pode ser lido pela web. Erros de API são sempre registrados. A chave de API nunca é registrada. 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, ao desinstalar a extensão são excluídas as configurações da PostNord e o log. As listas de pontos de serviço em cache são sempre removidas. Os pontos de serviço salvos nos pedidos são sempre mantidos.

Importação / Exportação

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

Import: cole o 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 mostra os métodos de envio, ele pede à extensão o preço de cada opção PostNord. Só contam os produtos com Requires Shipping definido como Yes: os demais não somam peso nem entram no subtotal. A extensão verifica a zona geográfica ou a lista de países, o peso do carrinho e o subtotal mínimo. Se o frete grátis se aplicar, o preço é 0. Caso contrário, o preço vem da tabela por país e, depois, do custo de reserva. Se não houver preço, a opção fica oculta. O preço é calculado na moeda padrão e mostrado ao cliente na moeda dele, com o imposto do Tax status selecionado. O cálculo do preço nunca contata a PostNord.

Para a opção de ponto de serviço e um endereço de entrega na Suécia, Dinamarca, Noruega ou Finlândia, seu servidor pede à API Business Location da PostNord os 10 pontos de serviço mais próximos do CEP de entrega. Ele envia o país e o CEP de entrega e o país do contrato. O tempo limite da API é de 10 segundos. As listas ficam em cache por 6 horas por CEP, e as respostas "sem pontos" por 1 hora. Erros da API ficam em cache por 5 minutos, para que uma falha da PostNord não deixe lenta cada atualização da finalização de compra. O cache é guardado na tabela de banco de dados própria da extensão. A etapa de entrega nunca espera pela PostNord: se a lista ainda não estiver em cache, ela é carregada quando o cliente seleciona a opção.

Para outros destinos, as opções ainda podem ser oferecidas com os seus preços, sem seletor. A opção de entrega domiciliar nunca mostra um seletor.

A extensão não solicita preços em tempo real da PostNord e não cria etiquetas de envio, não agenda envios (EDI), não fornece números de rastreamento nem envia e-mails de rastreamento. Não há visualização em mapa. Para os envios, use o PostNord Portal, o Skicka Direkt Business ou uma ferramenta de etiquetas; essas ferramentas precisam do ID do ponto de serviço 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 PostNord 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á na Suécia, Dinamarca, Noruega ou Finlândia, aparece uma lista PostNord service point abaixo da opção de ponto de serviço, com os pontos mais próximos, agrupados por cidade, cada um com endereço e distância. Antes de o CEP ser informado, o cliente vê "Informe seu CEP para escolher um ponto de serviço PostNord." A escolha é salva imediatamente para a finalização de compra.

Quando a lista está carregada, um ponto é obrigatório. Sem um ponto, Continue na etapa do método de entrega é interrompido com "Selecione um ponto de serviço PostNord." O ponto escolhido é verificado no servidor contra a lista da PostNord para o endereço de entrega. Um ponto escolhido para outro CEP não é usado.

O seletor nunca bloqueia uma venda. Se a lista não puder ser carregada (chave de API ainda não informada, API da PostNord indisponível, nenhum ponto perto do CEP), o cliente vê uma nota e pode fazer o pedido mesmo assim. A PostNord então entrega no ponto de serviço mais próximo do endereço.

Páginas de pedido, e-mails e fatura: o ponto é adicionado ao método de envio do pedido, por exemplo "PostNord: nome, endereço (ID 12345)" (o nome da opção e depois o ponto). Se o texto ultrapassar 128 caracteres, o endereço é omitido (no OpenCart 4 não há esse limite, e o endereço é sempre mantido). Ele aparece em todos os lugares onde o OpenCart mostra o método de envio: no histórico de pedidos do cliente, nos e-mails de pedido, na fatura e em Sales > Orders. Um pedido sem ponto mantém o nome simples do método.

Página de pedido do administrador: em Sales > Orders, a página do pedido mostra acima do histórico um painel PostNord service point com o nome, o endereço e o Service point ID. Se nenhum ponto foi escolhido, ele indica "não selecionado - a PostNord entrega no ponto de serviço mais próximo do endereço de envio".

No OpenCart 4 a lista de pontos de serviço aparece na janela Shipping method options, abaixo da opção de ponto de serviço, 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 da lista, com a mesma mensagem. Se o cliente clicar nele enquanto a lista ainda está carregando, a janela espera pela lista sem mensagem e depois clica em Continue novamente sozinha. Uma lista indisponível também não bloqueia o pedido. 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 de serviço 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 PostNord é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox PostNord > 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-postnord 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 nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, as opções de envio PostNord não são mostradas 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 PostNord não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable (ou Home delivery) está ativado. Verifique a Geo zone ou a lista Countries quando Ignore shipping zones estiver ativado. Confira se há um preço definido para o país (linha do país, linha * ou Fallback cost), os limites de peso e o Minimum subtotal. Confira se os produtos têm Requires Shipping definido como Yes.

O seletor indica que os pontos de serviço não podem ser carregados: verifique a API key e a configuração Test mode. Uma chave de produção não funciona no ambiente de teste, e vice-versa. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. O pedido pode ser feito mesmo assim; a PostNord então entrega no ponto de serviço mais próximo.

Pontos de serviço inesperados: verifique o Agreement country. Ele determina quais pontos de serviço são oferecidos.

O frete está grátis por engano: verifique as Country prices em busca de linhas com Price 0, especialmente uma linha * adicionada com Add country e deixada sem preencher, e verifique o Free shipping from.

Os pontos de serviço parecem desatualizados após uma mudança: clique em Save na página da extensão. Isso limpa as listas em cache.

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

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

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

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox PostNord. 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, a Sort order, o Tax status e a Geo zone. As listas de pontos de serviço em cache são sempre removidas. Se Remove data on uninstall estiver ativado, também são excluídos as configurações da PostNord, o log de depuração e os pontos de serviço de finalizações de compra que nunca se tornaram pedido. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os pedidos existentes mantêm o método de envio, o custo e o ponto de serviço 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 PostNord na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A PostNord é uma marca comercial de seu respectivo proprietário. Esta extensão não é afiliada à PostNord nem endossada por ela.