VibeFox DHL Africa for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior com a extensão cURL. O módulo não é instalado em versões anteriores do PHP nem sem cURL. Os DHL XML Services também exigem a extensão SimpleXML do PHP.
Conta DHL Express (somente para tarifas em tempo real): as tarifas em tempo real usam a MyDHL API. Você precisa do número da sua conta DHL Express e das credenciais da MyDHL API: uma chave da API e um segredo da API. Solicite-as no DHL Developer Portal (MyDHL API, "Get access") ou com o seu gerente de conta DHL Express. Contas que ainda têm credenciais dos DHL XML Services (Site ID e senha) podem usá-las no lugar. Se você usa apenas preços alternativos, não precisa de credenciais da DHL.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, acesse 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 VibeFox DHL Africa depois na lista de módulos e clique em Configure.
3. Insira a 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. Escolha a DHL API, insira a API key, a API secret e o número da sua conta DHL. Mantenha Test mode ativado enquanto usar credenciais de teste. Preencha o endereço Ship from. Se a sua conta DHL não for faturada na moeda padrão da loja, defina DHL quote currency e Exchange rate. Opcionalmente, defina preços por país e um custo alternativo (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora DHL Express com o texto de prazo de entrega DHL Express courier. A transportadora é atribuída a todas as zonas e a todos os grupos de clientes. 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 Africa > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as cotações da DHL em cache. Preços e pesos aceitam vírgula ou ponto decimal.
Os avisos no topo da página informam quando as tarifas em tempo real estão desativadas porque faltam a API key, a API secret ou o número da conta (ou, com XML Services, o Site ID ou a senha), quando faltam o país ou a cidade de origem, quando os XML Services estão selecionados (a DHL está desativando-os), quando uma moeda de cotação está definida sem taxa de câmbio, e quando a unidade de peso ou de dimensão da loja em International > Localization (Local units) não é conhecida pelo módulo (nesse caso é lida como kg ou cm). Se um valor não for válido ao salvar (um nome vazio ou com mais de 64 caracteres, um número inválido ou negativo, uma taxa de câmbio de 0, um peso mínimo maior que o peso máximo, a moeda de cotação, o país de origem ou a regra de imposto), um erro indica o campo, o valor anterior desse campo é mantido e as demais configurações são salvas.
Geral
Enable DHL Express Africa: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado ao cliente na finalização de compra. Padrão: DHL Express. Obrigatório, até 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. Com uma regra de imposto (e impostos ativados na loja), a tarifa DHL é aplicada sem o imposto cotado pela DHL, e o PrestaShop adiciona o próprio imposto. Com No tax, a tarifa DHL é cobrada como cotada, com o imposto incluído.
Conta DHL Express (necessária apenas para tarifas em tempo real)
DHL API: qual interface da DHL é usada. Somente os campos da API escolhida são mostrados.
API key: o seu nome de usuário da MyDHL API (chave da API).
API secret: a sua senha da MyDHL API (segredo da API). Depois de salvar, os campos API key e API secret ficam vazios e mostram Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.
Remove the saved API key and API secret: aparece somente quando uma chave ou um segredo está salvo. Ative-o e clique em Save para excluir os dois.
XML Site ID: o seu Site ID dos DHL XML Services (somente para a API legada). Esvaziá-lo também remove a senha XML salva.
XML password: a sua senha dos DHL XML Services (somente para a API legada). Como o API secret, não é mostrada novamente após salvar.
DHL account number: o número da sua conta DHL Express (9 dígitos). A MyDHL API exige. Com os XML Services, ele retorna as tarifas da sua conta em vez das tarifas públicas.
Test mode: usa o ambiente de teste da DHL. Ativado por padrão. Credenciais de teste funcionam apenas no ambiente de teste, e as de produção apenas em produção. Desative quando for para produção.
Ship from
O endereço de onde a DHL retira as encomendas. A tarifa depende dele.
Origin country: o país de onde você envia.
Origin city: a cidade de onde você envia, por exemplo Johannesburg. A MyDHL API exige.
Origin postcode: deixe vazio para países sem CEP (por exemplo Quênia, Nigéria, Gana).
Tarifas
Todos os preços estão na moeda padrão da sua loja, sem impostos. A tarifa em tempo real é o produto DHL Express mais barato para a encomenda. Se a DHL não estiver configurada, falhar ou não tiver serviço para a rota, usa-se o preço do país e depois o custo alternativo. Sem nenhum dos dois, a transportadora fica oculta.
DHL quote currency: a DHL cota na moeda do país da sua conta DHL (por exemplo ZAR, NGN ou KES). Se a DHL não retornar um valor na moeda padrão da sua loja, a tarifa em tempo real é convertida a partir dessa moeda com a taxa de câmbio abaixo. Caso contrário, não é usada. Padrão: — None —.
Exchange rate: quanto vale 1 unidade da moeda de cotação da DHL na moeda padrão da sua loja, por exemplo 1 ZAR = 0.05. Deve ser maior que 0. Deixe vazio se não quiser conversão. A taxa de câmbio é uma configuração manual.
Fallback cost: um custo fixo quando não há tarifa em tempo real nem preço por país. Deixe vazio para ocultar a transportadora nesse caso.
Country prices: um preço alternativo por país de destino, um por linha: CC:Price, por exemplo ZA:25.00. Usado quando não há tarifa em tempo real. Linhas em outro formato são ignoradas, e um aviso ao salvar as lista.
Fallback price basis: Per order cobra o preço uma única vez. Per item (multiplied by the cart quantity) multiplica pelo número de itens. Aplica-se apenas ao preço por país e ao custo alternativo. A tarifa DHL em tempo real sempre se refere à encomenda inteira.
Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) a partir do qual esta transportadora é gratuita. A DHL não é consultada. Deixe vazio para que nunca seja gratuita.
Condições
Minimum weight: oculta a transportadora abaixo deste peso do carrinho, em kg. 0 significa sem limite. Não pode ser maior que Maximum weight.
Maximum weight: oculta a transportadora acima deste peso do carrinho, em kg. Padrão: 70 (também usado quando o campo está vazio). 0 significa sem limite.
Minimum subtotal: mostra a transportadora somente se o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para sempre mostrá-la.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece a transportadora sem que você precise atribuir zonas a ela. A transportadora recebe todas as zonas, inclusive as que você criar depois, e os países abaixo decidem. Desativá-la devolve à transportadora as suas próprias zonas.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países para os quais você envia. Usado somente com Ignore shipping zones.
Avançado
Debug log: grava os cálculos de tarifas em logs/vfd_dhla_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da DHL são sempre registrados, mesmo com esta opção desativada. Credenciais e endereços de clientes nunca são registrados.
Log: mostra o tamanho e as entradas mais recentes do registro de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, ao desinstalar o módulo são excluídos as configurações, a transportadora, os produtos DHL salvos dos pedidos e o registro. 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 Express. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: os países de Ignore shipping zones, o peso do carrinho e o subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à DHL.
Caso contrário, o módulo envia à DHL a origem e o destino (país, cidade, CEP), o peso do carrinho convertido em kg (no mínimo 0,5 kg) e uma caixa montada a partir das dimensões dos produtos em cm: o maior comprimento, a maior largura e as alturas empilhadas. Produtos sem dimensões não acrescentam nada. Se nenhum produto tiver dimensões, usa-se uma caixa de 10 x 10 x 10 cm. Envios para outro país são declarados na alfândega, com o subtotal do carrinho como valor declarado. Envios nacionais não são declarados. A data de coleta é hoje, ou segunda-feira nos fins de semana. Uma tarifa em tempo real só é solicitada depois que o cliente informa uma cidade (com XML Services, uma cidade ou um CEP). Antes disso, aplicam-se os preços alternativos.
O produto DHL Express mais barato é mostrado como um único preço com o nome da sua transportadora. O cliente não vê o produto DHL. O preço é calculado na moeda padrão, arredondado e depois exibido na moeda do carrinho do cliente.
Cada cotação fica em cache por 1 hora por encomenda e rota. Uma requisição com falha fica em cache por 10 minutos, para que a finalização de compra não espere a DHL a cada atualização. O tempo limite da API é de 12 segundos. Se a DHL retornar um erro, não tiver serviço ou responder em uma moeda inutilizável, o cliente não vê erro algum: usa-se o preço alternativo ou a transportadora fica oculta. O motivo é gravado no registro de depuração.
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 calcula apenas tarifas. Ele não cria envios DHL, não imprime etiquetas ou faturas comerciais, não agenda coletas, não rastreia encomendas, não oferece pontos de serviço da DHL, não deixa o cliente escolher entre produtos DHL, não empacota várias caixas, não adiciona seguro e não calcula taxas aduaneiras e impostos. A cotação é apenas para o frete. Taxas e impostos de importação são pagos pelo destinatário.
Pedidos
Quando o pedido é feito, o módulo guarda a tarifa calculada para o carrinho. A página do pedido no back office então exibe um bloco DHL Express Africa, para que você saiba o que reservar com a DHL:
DHL product: o produto DHL Express da tarifa em tempo real, por exemplo "EXPRESS WORLDWIDE (P)". Exibido somente para tarifas em tempo real.
Price source: Live DHL rate, Fallback price (no live rate) ou Free shipping threshold.
Calculated price (excl. tax): o preço na moeda padrão da loja.
Recálculos posteriores do carrinho, por exemplo quando o pedido é editado no back office, não alteram esses valores. As tarifas de carrinhos que nunca se tornaram pedidos são removidas após 30 dias.
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 Africa é o primeiro bloco da página Modules > Module Manager > VibeFox DHL Africa > Configure, acima das configurações. Insira 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-africa e o link Manage licenses and domains in your account, que abre a 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 Express não é mostrada 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 ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
DHL Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable DHL Express Africa está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou ative Ignore shipping zones e confira Countries). Verifique os limites de peso e Minimum subtotal. Sem tarifa em tempo real, a transportadora só aparece se houver um preço por país ou um custo alternativo definido. Os produtos também podem estar limitados a certas transportadoras na página do produto.
As tarifas em tempo real não aparecem: verifique os avisos no topo da página do módulo (credenciais ou origem ausentes). Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Erros da DHL, como um erro HTTP da MyDHL API, ausência de produtos para a rota ou problema de moeda, são sempre registrados. Verifique se o Test mode corresponde às suas credenciais e se o endereço do cliente tem uma cidade.
A DHL retorna a tarifa em ZAR, NGN ou KES, mas a minha loja usa outra moeda: o registro diz DHL quote not usable. Defina DHL quote currency com essa moeda e informe o Exchange rate. Sem isso, a tarifa em tempo real não é usada e os preços alternativos se aplicam.
Tenho credenciais antigas dos DHL XML Services: escolha XML Services (legacy) em DHL API. Mude para a MyDHL API quando receber as credenciais MyDHL.
O frete está sendo tributado duas vezes: defina uma regra de imposto em Tax para que a tarifa DHL seja aplicada sem o IVA da DHL, ou escolha No tax para cobrar o valor da DHL como cotado.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as cotações da DHL em cache.
A página informa que a transportadora DHL Express não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Para desenvolvedores, o módulo oferece os hooks actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest e actionVfdDhlaXmlRequest para alterar o endereço da API, a declaração aduaneira, a caixa e as requisições à DHL.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox DHL Africa e escolha Uninstall. A chave de licença, o status da licença e as cotações da DHL em cache 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, os produtos DHL salvos dos pedidos e o registro são removidos. Se estiver desativado, a transportadora apenas é desativada, e as configurações e os produtos DHL dos pedidos realizados são mantidos. Instalar o módulo novamente restaura o status que a transportadora tinha antes.
DHL é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela DHL.