VibeFox DHL Packstation for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posteriores (testado na 4.1.0.3). O seletor de pontos de retirada funciona com o checkout padrão do OpenCart.

PHP: 8.0 ou superior.

Chave de API da DHL: a lista de pontos vem da API gratuita DHL Location Finder. Cadastre-se no portal de desenvolvedores da DHL (developer.dhl.com), crie um aplicativo, adicione a API "Location Finder - Unified" e copie a chave de API do aplicativo. Essa API não exige contrato comercial com a DHL. Sem a chave, o método fica oculto no checkout. Considere o limite de requisições do seu aplicativo DHL: cada nova pesquisa por CEP ou cidade é uma requisição à API.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_dhl_packstation-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_dhl_packstation.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No administrador, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_dhl_packstation-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 instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox DHL Packstation 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. Insira a 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. Cole a chave de API da DHL, clique em Save e depois em Test API key. Escolha os tipos de ponto de retirada e informe os preços por país (veja Configuration). Ative Enable/Disable e clique em Save.

OpenCart 4

1. No administrador, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_dhl_packstation.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. Localize VibeFox DHL Packstation, clique em Install (o botão verde +) e depois em Edit (o botão com 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 campos são os mesmos nas duas versões.

Depois da instalação, o método fica desativado até que você ative Enable/Disable e salve. A tabela de preços padrão tem preços para a Alemanha e a Áustria e um preço para os demais países. Se você instalar a extensão novamente após uma desinstalação, as configurações 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 DHL Packstation > Edit. As seções são listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento limpa o cache de pontos. Se um campo tiver um erro (um nome inválido ou com mais de 64 caracteres, um raio ou número de resultados que não seja um número inteiro, um número inválido ou negativo, Min weight (kg) maior que Max weight (kg), uma ordem de classificação que não seja um número inteiro, uma classe de imposto ou uma zona geográfica desconhecidos), nada é salvo e o erro é exibido. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.

Os avisos no topo da página informam quando a chave de API da DHL está vazia, quando nenhum tipo de ponto de retirada está ativado (nos dois casos o método não aparece no checkout), quando as entradas de preço por país não estão no formato CC:PRICE (essas entradas são ignoradas), e quando não existe uma classe de peso com a unidade kg em System > Localisation > Weight Classes (os pesos dos produtos são então lidos pelo nome da unidade da classe deles: kg, g, lb ou oz; unidades desconhecidas são tratadas como kg).

Geral

As configurações se aplicam a todas as zonas geográficas.

Enable/Disable: ativa o DHL Packstation no checkout. Padrão: off.

Name: o nome do método de envio exibido ao cliente. Padrão: DHL Packstation. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.

Tax Class: a classe de imposto do custo de envio, ou --- None --- (padrão). O OpenCart adiciona este imposto sobre os preços abaixo. Com --- None ---, os preços são finais.

Sort Order: a posição do DHL Packstation entre os métodos de envio. Um número inteiro.

API DHL Location Finder

DHL API key: a "API Key" do seu aplicativo em developer.dhl.com. Sem ela, o método fica oculto no checkout. 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: aparece quando uma chave está salva. Marque esta caixa e salve para excluir a chave armazenada.

Connection test: o botão Test API key pesquisa os pontos próximos a 53113 Bonn com a chave salva e limpa o cache de pontos. Salve as configurações primeiro. Ele mostra quantos pontos foram encontrados (Connected: … DHL locations found near 53113 Bonn.), que a DHL rejeitou a chave (401/403) ou que a API não respondeu corretamente (detalhes no log de depuração).

Pontos de retirada

No checkout, o cliente vê os pontos próximos ao CEP de entrega dele e pode pesquisar outro CEP ou outra cidade.

Location types: quais pontos DHL o cliente pode escolher: Packstation (parcel locker), Post Office (Postfiliale) e DHL Parcel Shop (Paketshop). Os três vêm ativados por padrão. Se nenhum for selecionado, o método fica oculto. Para uma Packstation, o cliente deve informar o seu DHL Postnummer.

Search radius (meters): o raio em torno do CEP ou da cidade pesquisados. Padrão: 5000. Um número inteiro; valores abaixo de 100 ou acima de 25000 m (o máximo da DHL) são ajustados para esse limite.

Max results: o número máximo de pontos exibidos por pesquisa. Padrão: 20. Um número inteiro; a DHL permite até 50, valores maiores são reduzidos para 50.

Shipping address: usa o ponto escolhido como endereço de entrega do pedido. Ativado por padrão. A linha 1 do endereço passa a ser, por exemplo, "Packstation 105" (ou "Postfiliale 502" para uma agência ou um DHL Parcel Shop), a linha 2 "Postnummer" com o número, além do CEP, da cidade e do país do ponto, para que as etiquetas impressas a partir do pedido cheguem ao lugar certo. Nome, empresa e telefone vêm do endereço do cliente. A região é esvaziada. A libreta de endereços do cliente não é alterada.

Preços (o título da seção mostra a moeda padrão da sua loja)

Country prices: o preço por país de destino na moeda padrão da sua loja, sem impostos, no formato CC:PRICE, separados por vírgulas ou quebras de linha. Padrão: DE:4.99, AT:5.99. A vírgula decimal também funciona (DE:4,99).

Other countries: o preço para um país de destino que não está em Country prices. Padrão: 5.99. Deixe vazio para ocultar o método para esses países.

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

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual este envio é grátis. Deixe vazio para nunca ser grátis.

Disponibilidade

Min weight (kg): o peso mínimo do carrinho. Os pesos dos produtos são convertidos a partir da classe de peso deles. 0 significa sem limite (padrão).

Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 31.5, porque uma Packstation aceita pacotes de até 31,5 kg. 0 significa sem limite.

Minimum subtotal: mostra o método somente se o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrá-lo sempre.

Geo Zone: ofereça o método somente 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 é usado com Ignore shipping zones.

Ignore shipping zones: quando ativado, o método é oferecido para os países abaixo (todos os países, se a lista estiver vazia), independentemente da zona geográfica do endereço.

Countries (ignore zones): os países de destino para esse modo. Usado somente com Ignore shipping zones.

Avançado

Debug log: grava as requisições à API e as etapas do checkout em storage/logs/vfd_dhlp_debug.log.php (no OpenCart 4, system/storage/logs/vfd_dhlp_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo quando esta opção está desativada. A chave de API, o Postnummer e os endereços dos clientes nunca são gravados. Quando o arquivo chega a 5 MB, ele é movido para vfd_dhlp_debug.old.log.php e um novo log é iniciado.

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

Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações, as pesquisas em cache, o log e os pontos dos checkouts não concluídos. Os pontos escolhidos permanecem nos pedidos. Quando desativado (padrão), tudo é mantido para uma reinstalação.

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 no checkout

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço do DHL Packstation. Se uma Geo Zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Somente 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 se há uma chave de API e pelo menos um tipo de ponto, os países permitidos (com Ignore shipping zones), o peso do carrinho e o subtotal mínimo. Em seguida, usa o preço do país de destino (ou o preço para os demais países) e aplica o frete grátis se o subtotal for alto o bastante. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. O preço não depende do ponto de retirada, e nenhuma requisição é enviada à DHL para calculá-lo. Ele é calculado na moeda padrão e exibido ao cliente na moeda dele, com o imposto da Tax Class selecionada.

A extensão não cria envios da DHL, não imprime etiquetas e não rastreia encomendas. Use o portal de clientes corporativos da DHL ou uma ferramenta de etiquetas: com Shipping address ativado, o pedido já contém o endereço da Packstation e o Postnummer. A extensão não calcula tarifas DHL em tempo real e não mostra mapa. Não há entrada manual de número de Packstation.

Pontos de retirada

Quando o cliente seleciona o DHL Packstation na etapa de método de envio, aparece um seletor logo abaixo do método. Os pontos DHL próximos ao CEP e à cidade de entrega são carregados. O cliente pode digitar outro CEP ou outra cidade e clicar em Search. Os pontos são agrupados por tipo (Packstation, Post Office, Parcel Shop) e ordenados por distância. Se nada for encontrado, o cliente vê No DHL locations found near "…". Try another postcode or city.

Para uma Packstation, o cliente deve informar o DHL Postnummer, o número de cliente DHL dele de 6 a 12 dígitos, do aplicativo DHL ou da conta DHL. Para os demais pontos, é opcional. A escolha é salva assim que é feita. Ao clicar em Continue, o servidor a verifica novamente: o ponto deve estar entre os resultados de pesquisa da DHL no país de entrega. Sem ponto, o cliente vê Please choose a DHL Packstation or post office for delivery. e não consegue continuar. Um Postnummer ausente para uma Packstation mostra Please enter your DHL Postnummer - it is required for delivery to a Packstation., e um inválido mostra The DHL Postnummer must consist of 6 to 12 digits.

Os resultados de pesquisa ficam em cache por 12 horas. Uma pesquisa vazia ou com falha fica em cache por 10 minutos, para que o checkout não espere pela DHL a cada atualização. Com o cache de arquivos padrão do OpenCart, as entradas duram no máximo o tempo de vida do cache da loja (1 hora por padrão), então a lista é atualizada uma vez por hora. O tempo limite da API é de 12 segundos. Se a API da DHL não puder ser acessada, o cliente vê DHL locations cannot be loaded right now. Please try again later or choose another shipping method. Um ponto que o cliente já havia escolhido continua sendo aceito.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de checkout e escolhe o DHL Packstation na janela Shipping method options. O seletor aparece nessa janela, abaixo do método, e funciona como descrito acima. O botão Continue da janela não avança sem um ponto válido ou, para uma Packstation, sem o Postnummer, com as mesmas mensagens.

Quando o pedido é feito, o ponto (ID, tipo, número, nome, endereço) e o Postnummer são salvos com o pedido. O ponto é adicionado ao método de envio do pedido como DHL pickup location: e DHL Postnummer:, para que apareça em todos os lugares onde o OpenCart exibe o método de envio: na página do pedido do cliente, nos e-mails do pedido e na nota fiscal. Se Shipping address estiver ativado, o endereço de entrega do pedido é substituído pelo endereço do ponto.

No OpenCart 4, o checkout mantém um único pedido, que é atualizado sempre que o cliente confirma de novo. Com ele são atualizados o ponto, o texto do método de envio e o endereço do pedido.

Pedidos

Abra o pedido em Sales > Orders. O painel DHL pickup location acima do histórico do pedido mostra o ponto, o tipo e o ID dele, e o Postnummer, também depois que a extensão é desativada. Um pedido sem ponto mostra No DHL location was selected for this order.

Clique em Change, pesquise por CEP ou cidade, escolha outro ponto na lista da DHL, altere o Postnummer se necessário e clique em Save location. Você também pode alterar apenas o Postnummer. O texto do método de envio do pedido é atualizado. Se Shipping address estiver ativado, o endereço de entrega do pedido também é atualizado, partindo novamente do endereço original do cliente. Cada alteração adiciona ao histórico do pedido uma entrada DHL pickup location changed to: …, com o status atual do pedido e sem notificar o cliente. Alterar o ponto exige a permissão de modificação de pedidos; não é necessário acesso às configurações da extensão.

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 DHL Packstation é o primeiro bloco na página Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit, acima das configurações. Cole 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-dhl-packstation e o link Manage licenses and domains in your account, que abre a sua conta 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 administrador (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 de alterar o endereço da loja ou de liberar um slot 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 domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera o slot de domínio dela. Libere o slot na sua conta vibefox.net.

Sem uma chave ativa, o método de envio DHL Packstation não é mostrado aos clientes no checkout e nenhuma tarifa é calculada. Um usuário administrador que esteja conectado ao administrador no mesmo navegador ainda vê o método na loja, marcado com (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 administrador, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. 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 administrador 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 um cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O DHL Packstation não aparece no checkout: verifique se a licença está ativa e se Enable/Disable está ativado. Verifique a Geo Zone (ou ative Ignore shipping zones e verifique Countries (ignore zones)). Verifique se a DHL API key está preenchida, se pelo menos um tipo de ponto está selecionado, se o país de destino tem um preço (ou se Other countries está definido), e se as regras de peso e subtotal não o estão ocultando. Verifique se os produtos têm Requires Shipping definido como Yes.

Nenhum ponto é exibido: clique em Test API key. Se a DHL rejeitar a chave (401/403), verifique a chave e se o seu aplicativo tem a API "Location Finder - Unified". Ative Debug log, recarregue o checkout e veja o campo Log na página da extensão. Verifique se o limite de requisições do seu aplicativo DHL não foi atingido.

Nenhum ponto perto de um endereço: aumente o Search radius (meters) ou o Max results, ou deixe o cliente pesquisar outro CEP ou outra cidade. Uma Packstation sem número nos dados da DHL não é listada.

O cliente vê "Enter your postcode or city to see DHL locations near you.": o endereço de entrega não tem CEP nem cidade. O cliente pode digitar um deles no campo de pesquisa.

Change na página do pedido no administrador diz "Please choose a DHL location of the search - nothing was changed.": pesquise por CEP ou cidade e escolha um ponto entre os resultados. Se o pedido ainda não tiver ponto, é preciso escolher um antes de salvar o Postnummer.

O painel DHL pickup location não aparece na página do pedido: o painel só é exibido para pedidos enviados com DHL Packstation (ele permanece mesmo com a extensão desativada).

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

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox DHL Packstation. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort Order, Tax Class e Geo Zone. O cache de pontos e os eventos da extensão são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações, o log e os pontos dos checkouts não concluídos também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas ao instalar a extensão novamente. Os pontos escolhidos permanecem sempre nos pedidos, e os pedidos existentes mantêm o método de envio, o custo e o endereço.

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

DHL e Packstation são marcas registradas de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pela DHL.