VibeFox DHL Packstation for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x. Os temas Classic e Hummingbird são suportados.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

DHL API key: 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. Para essa API não é necessário contrato comercial com a DHL. Sem a chave, a transportadora fica oculta na finalização de compra. Atenção ao limite de requisições do seu aplicativo DHL: cada nova pesquisa por CEP ou cidade é uma requisição à API.

VibeFox license key: comprada 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 upload terminar, clique em Configure, ou encontre depois VibeFox DHL Packstation na lista de módulos e clique em Configure.

3. Informe 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. Cole a chave de API da DHL, clique em Save e depois em Test API key. Escolha os tipos de ponto e informe os preços por país (veja Configuração).

Na instalação, o módulo cria a transportadora DHL Packstation com o texto de prazo de entrega Delivery to a DHL Packstation or post office. A transportadora fica ativada, atribuída a todos os grupos de clientes e às zonas da Alemanha e da Áustria (os países da tabela de preços padrão). Você pode alterar zonas, 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 DHL Packstation > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Se um campo tiver erro (número inválido ou negativo, Min weight (kg) maior que Max weight (kg), nome com mais de 64 caracteres), nada é salvo e o erro aparece no topo. Cada salvamento limpa o cache de pontos.

Os avisos acima das configurações informam quando a transportadora não foi encontrada, quando a unidade de peso da loja (International > Localization, Local units) não é conhecida pelo módulo (os pesos são então lidos em kg; use kg, g, lb ou oz), quando a chave de API da DHL está vazia, quando nenhum tipo de ponto está ativo e quando as entradas de preço por país não estão no formato CC:PRICE (essas entradas são ignoradas).

Geral

Grupos de clientes, zonas e limites de tamanho da transportadora são definidos em Shipping > Carriers. As configurações abaixo valem para todas as zonas.

Enable/Disable: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Name: o nome da transportadora exibido ao cliente. Padrão: DHL Packstation. Obrigatório, no máximo 64 caracteres.

Tax: a regra de imposto da transportadora, ou No tax. O PrestaShop adiciona este imposto aos preços abaixo. Com No tax, os preços são finais.

DHL Location Finder API

DHL API key: a “API Key” do seu aplicativo em developer.dhl.com. Sem ela, a transportadora fica oculta na finalização de compra. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um valor novo apenas para alterá-lo.

Remove the saved API key: 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 antes. Ele mostra quantos pontos foram encontrados, se a DHL rejeitou a chave (401/403) ou se a API não respondeu corretamente (detalhes no log de depuração).

Pontos de retirada

Na finalização de compra, o cliente vê os pontos próximos ao CEP de entrega e pode pesquisar outro CEP ou cidade.

Location types: quais pontos DHL o cliente pode escolher: Packstation (parcel locker), Post Office (Postfiliale) e DHL Parcel Shop (Paketshop). Todos os três por padrão. Se nenhum for selecionado, a transportadora fica oculta. Para uma Packstation, o cliente deve informar seu DHL Postnummer.

Search radius (meters): o raio em torno do CEP ou da cidade pesquisados. Padrão: 5000. 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. 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 de endereço 1 passa a ser, por exemplo, “Packstation 105” (ou “Postfiliale 502” para um Post Office ou 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. O novo endereço é usado somente pelo pedido e não aparece na lista de endereços do cliente.

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 loja, sem impostos, 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 a transportadora nesses países.

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

Free shipping from: o subtotal do carrinho (produtos que precisam de entrega, após descontos, antes dos impostos) a partir do qual esta entrega é 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 unidade de peso da loja. 0 significa sem limite.

Max weight (kg): a transportadora fica oculta 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: mostrar a transportadora somente se o subtotal do carrinho (produtos que precisam de entrega, após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrar sempre.

Ignore shipping zones: quando ativado, a transportadora fica vinculada a todas as zonas ativas (também às criadas depois) e é oferecida para os países abaixo, ou para todos os países se a lista estiver vazia. Ao desativar novamente, a transportadora recupera as zonas que tinha antes.

Countries (ignore zones): os países de destino para esse modo. Ctrl/Cmd + clique para selecionar vários países. Usado somente com Ignore shipping zones.

Avançado

Debug log: grava requisições à API e etapas da finalização de compra em logs/vfd_dhlp_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo quando isto está desativado. A chave de API, o Postnummer e os endereços dos clientes nunca são gravados.

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

Remove data on uninstall: quando ativado, desinstalar o módulo exclui as configurações, a transportadora, as pesquisas em cache e os logs. Os pontos escolhidos permanecem nos pedidos. Quando desativado, tudo é mantido para uma reinstalação.

Como funciona na finalização de compra

Na etapa de entrega, o PrestaShop pede ao módulo o preço da DHL Packstation. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica se a chave de API e pelo menos um tipo de ponto estão definidos, os países permitidos (com Ignore shipping zones), o peso do carrinho e o subtotal mínimo. Em seguida, pega o preço do país de destino (ou o preço dos demais países) e aplica a entrega grátis se o subtotal for alto o bastante. O preço é calculado na moeda padrão da loja e exibido na moeda do carrinho do cliente.

Se você editar a 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 cria envios 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. O módulo não calcula tarifas DHL em tempo real e não mostra mapa. Não há digitação manual do número da Packstation.

Pontos de retirada

Quando o cliente seleciona DHL Packstation, um seletor aparece abaixo da transportadora. Os pontos DHL próximos ao CEP e à cidade de entrega são carregados. A DHL é consultada apenas para a transportadora selecionada. O cliente pode digitar outro CEP ou 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, seu número de cliente DHL de 6-12 dígitos, do aplicativo ou da conta DHL. Para os outros pontos, é opcional. A escolha é salva no carrinho assim que é feita. Ao clicar em Continue, o servidor verifica novamente: o ponto deve ser um dos 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 pode continuar. Um Postnummer ausente ou inválido é informado da mesma forma.

Os resultados de pesquisa ficam em cache por 12 horas. Uma pesquisa vazia ou com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela DHL a cada atualização. 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á tenha escolhido continua sendo aceito.

Quando o pedido é feito, o ponto (ID, tipo, número, nome, endereço) e o Postnummer são salvos com o pedido. Se Shipping address estiver ativado, o endereço de entrega do pedido é substituído pelo endereço do ponto. O ponto aparece na página de confirmação do pedido, em Order history and details da conta do cliente, e no e-mail de confirmação do pedido e no e-mail de novo pedido do módulo Mail alerts, com os rótulos DHL pickup location e DHL Postnummer acrescentados ao nome da transportadora.

Na página do pedido no back office, o bloco DHL pickup location mostra o ponto, seu tipo e ID, e o Postnummer. Clique em Change, pesquise por CEP ou cidade, escolha outro ponto, altere o Postnummer e clique em Save location. Você também pode alterar só o Postnummer. Cada alteração adiciona ao pedido uma mensagem privada DHL pickup location changed to: …. Se Shipping address estiver ativado, o endereço de entrega do pedido também é atualizado. Alterar o ponto exige permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Se vários pedidos foram criados a partir de um mesmo carrinho, o ponto pertence apenas ao primeiro pedido; Change em outro pedido desse carrinho mostra The DHL location of this cart belongs to another order of the same cart - nothing was changed.

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 DHL Packstation é o primeiro bloco da página Modules > Module Manager > VibeFox DHL Packstation > 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 ficam a linha Product: presta-shipping-dhl-packstation e o link Manage licenses and domains in your account, que abre sua conta vibefox.net. Somente funcionários com a permissão Configure do 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, inclusive em uma configuração multiloja. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a transportadora DHL Packstation não é exibida aos clientes na finalização de compra, e nenhuma tarifa é calculada. O front office do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não 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 é preciso nenhum cron job. Desinstalar o módulo sempre remove a chave de licença e o status da licença. O Reset deste módulo não exclui dados, então a chave e o status são mantidos.

Solução de problemas

DHL Packstation não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou ligue 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 preço (ou se Other countries está definido) e se as regras de peso e subtotal não a ocultam. Os produtos também podem estar limitados a certas transportadoras na página do produto.

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 o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Verifique se o limite de requisições do seu aplicativo DHL não foi atingido.

Nenhum ponto perto de um endereço: aumente Search radius (meters) ou Max results, ou deixe o cliente pesquisar outro CEP ou 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 exibe “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 um ponto, é preciso escolher um antes de salvar o Postnummer.

A página informa que a transportadora DHL Packstation não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo com Reset em Modules > Module Manager para criá-la novamente. O Reset mantém o status ligado/desligado de uma transportadora existente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox DHL Packstation e escolha Uninstall. A chave de licença, o status da licença e o cache de pontos são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e os pontos de carrinhos sem pedido são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Instalar o módulo novamente restaura o status da transportadora que ela tinha antes. Os pontos escolhidos permanecem sempre nos pedidos.

DHL e Packstation são marcas comerciais de seus respectivos proprietários. Este módulo não é afiliado nem endossado pela DHL.