VibeFox DHL Africa for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).
PHP: 8.0 ou superior com a extensão cURL. O DHL XML Services também exige a extensão SimpleXML do PHP.
Conta DHL Express (apenas para tarifas em tempo real): as tarifas em tempo real usam a API MyDHL. Você precisa do seu número de conta DHL Express e das credenciais da API MyDHL: uma API key e um API secret. Solicite-as no portal de desenvolvedores da DHL (MyDHL API, "Get access") ou com o seu gerente de conta DHL Express. Contas que ainda têm credenciais do DHL XML Services (Site ID e senha) podem usá-las no lugar. Se você usa apenas os preços de contingência, não precisa de credenciais da DHL.
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_africa-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_dhl_africa.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 administrador, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_dhl_africa-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 Africa 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 License key).
5. Escolha a API da DHL, informe a API key, o API secret e o seu número de conta DHL. Mantenha Test mode ativado enquanto usar credenciais de teste. Informe o endereço de Ship from. Se a sua conta DHL não for cobrada na moeda padrão da loja, defina DHL quote currency e Exchange rate. Opcionalmente, defina preços por país e um custo de contingência (veja Configuration). Ative Enable DHL Express Africa e clique em Save.
OpenCart 4
1. No administrador, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_dhl_africa.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 Africa, 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 seus campos são iguais nas duas versões.
Depois da instalação, o método fica desativado até que você ative Enable DHL Express Africa e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações da DHL 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 Africa > Edit. As seções são listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa o cache de cotações da DHL. Preços e pesos aceitam vírgula ou ponto decimal. 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 as tarifas em tempo real estão desativadas porque a API key, o API secret ou o número da conta está vazio (ou, com o XML Services, o Site ID ou a senha), quando o país ou a cidade de origem está vazio, quando o XML Services está selecionado (a DHL o está descontinuando), quando uma moeda de cotação é definida sem uma taxa de câmbio, e quando a unidade de peso ou de comprimento da loja não é reconhecida pela extensão (os pesos dos produtos são então lidos como kg e as dimensões como cm; adicione uma classe de peso com a unidade kg em System > Localisation > Weight Classes ou uma classe de comprimento com a unidade cm em System > Localisation > Length Classes).
Se um valor não for válido ao salvar (um título de método 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, uma moeda de cotação, um país de origem, uma classe de imposto ou uma zona geográfica desconhecidos, uma ordem de classificação que não seja um número inteiro), um aviso acima das configurações indica o campo, por exemplo Select a valid origin country. It was not saved. O valor anterior desse campo é mantido, e as demais configurações são salvas.
Geral
Enable DHL Express Africa: mostra ou oculta o DHL Express no checkout. Padrão: off.
Method title: o nome do método de envio mostrado ao cliente no checkout. Padrão: DHL Express. Obrigatório, no máximo 64 caracteres.
Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Com uma classe de imposto (e impostos ativados na loja), a tarifa da DHL é usada sem o imposto que a DHL cotou, e o OpenCart adiciona o próprio imposto. Com No tax, a tarifa da DHL é cobrada como cotada, com o imposto incluso.
Sort order: a posição do DHL Express entre os métodos de envio no checkout. Um número inteiro.
Conta DHL Express (necessária apenas para as tarifas em tempo real)
DHL API: qual interface da DHL é usada.
API key: o seu nome de usuário da API MyDHL (API key).
API secret: a sua senha da API MyDHL (API secret). Depois de salvar, os campos API key e API secret ficam vazios e exibem Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.
Remove the saved API key and API secret: exibido apenas para a API MyDHL, quando uma chave ou um secret está salvo. Marque e clique em Save para excluir os dois.
XML Site ID: o seu Site ID do DHL XML Services (somente para a API legada). Limpá-lo também remove a senha XML salva.
XML password: a sua senha do DHL XML Services (somente para a API legada). Assim como o API secret, ela não é exibida novamente após salvar.
DHL account number: o seu número de conta DHL Express (9 dígitos). A API MyDHL o exige. Com o XML Services, ele retorna as tarifas da sua conta em vez das tarifas publicadas.
Test mode: usa o ambiente de teste da DHL. Ativado por padrão. Credenciais de teste só funcionam no ambiente de teste, e as de produção só em produção. Desative quando for para produção.
Endereço de origem
O endereço de onde a DHL retira os pacotes. A tarifa depende dele. O OpenCart guarda o endereço da loja como texto livre, por isso a origem é sempre informada aqui. A nota desta seção mostra o país da sua loja.
Origin country: o país de onde você envia.
Origin city: a cidade de onde você envia, por exemplo Johannesburg. A API MyDHL a 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 loja, sem impostos. A tarifa em tempo real é o produto DHL Express mais barato para o pacote. 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 de contingência. Sem nenhum dos dois, o método fica oculto.
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, ela 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 houver conversão. A taxa é uma configuração manual.
Fallback cost: um custo fixo quando não há tarifa em tempo real nem preço de país. Deixe vazio para ocultar o método nesse caso.
Country prices: um preço de contingência 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 (padrão) cobra o preço uma vez. Per item (multiplied by the cart quantity) o multiplica pelo número de itens. Aplica-se somente ao preço do país e ao custo de contingência. A tarifa em tempo real da DHL sempre se refere ao pacote inteiro.
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual este método é gratuito. A DHL não é consultada. Deixe vazio para nunca ser gratuito.
Condições
Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão). Não pode ser maior que Maximum weight (kg).
Maximum weight (kg): oculta o método acima deste peso do carrinho. Padrão: 70 (também usado quando o campo está vazio). 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.
Disponibilidade
Geo zone: ofereça o DHL Express 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 é verificado com Ignore shipping zones.
Ignore shipping zones: ofereça o método para os países abaixo (ou para todos os países, se a lista estiver vazia), independentemente da zona geográfica selecionada.
Countries: os países de destino para esse modo. Usado somente com Ignore shipping zones.
Avançado
Debug log: grava os cálculos de tarifas em storage/logs/vfd_dhla_debug.log.php (no OpenCart 4, em system/storage/logs/vfd_dhla_debug.log.php). O arquivo não pode ser lido pela web. Erros da DHL são sempre registrados, mesmo quando esta opção está desativada. Credenciais, o número da conta e os endereços dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_dhla_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 cotações da DHL em cache e o log. Quando desativado (padrão), tudo é mantido para uma reinstalação. Os produtos DHL dos pedidos feitos são sempre mantidos.
Importação / Exportação
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A API key, o API secret e a senha XML não são exportados.
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. As credenciais salvas são mantidas.
Como funciona no checkout
Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço do DHL Express. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o DHL Express 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 então verifica as condições: os países de Ignore shipping zones, o peso do carrinho e o subtotal mínimo. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à DHL.
Caso contrário, a extensão envia à DHL a origem e o destino (país, cidade, CEP), o peso do carrinho convertido para kg a partir das classes de peso dos produtos (no mínimo 0,5 kg) e uma caixa montada com as 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 à alfândega, com o subtotal do carrinho como valor declarado. Envios nacionais não são declarados. A data de coleta é hoje, no fuso horário da loja, ou a segunda-feira nos fins de semana. Uma tarifa em tempo real só é solicitada depois que o cliente informa uma cidade (com o XML Services, uma cidade ou um CEP). Antes disso, valem os preços de contingência.
O produto DHL Express mais barato é exibido como um único preço com o título do seu método. O cliente não vê o produto DHL. O preço é calculado na moeda padrão, arredondado conforme as casas decimais dela e exibido ao cliente na moeda dele com o imposto da Tax class selecionada.
Cada cotação fica em cache por 1 hora por pacote e rota. Uma requisição com falha fica em cache por 10 minutos, para que o checkout não espere pela 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ê nenhum erro: usa-se o preço de contingência ou o método fica oculto. O motivo é gravado no log de depuração.
A extensão calcula apenas tarifas. Ela não cria envios da DHL, não imprime etiquetas ou faturas comerciais, não agenda coletas, não rastreia encomendas, não oferece pontos de atendimento da DHL, não deixa o cliente escolher entre produtos DHL, não agrupa várias caixas, não adiciona seguro e não calcula taxas e impostos de importação. A cotação vale somente para o envio. Taxas de importação e impostos são pagos pelo destinatário.
No OpenCart 4 o cliente clica em Choose no bloco do método de envio da página de checkout e escolhe o DHL Express na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
Pedidos
Quando o pedido é feito, a extensão mantém a tarifa calculada para o carrinho dele. Abra o pedido em Sales > Orders: o painel DHL Express Africa acima do histórico do pedido mostra o que reservar na 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.
O produto DHL não é mostrado ao cliente nos e-mails nem na página de pedidos dele. O pedido mostra o título do método e o custo do envio como qualquer outro método de envio do OpenCart.
No OpenCart 4 o checkout mantém um único pedido e o atualiza sempre que o cliente confirma novamente. O painel então mostra a tarifa mais recente do checkout. Se o cliente mudar para outro método de envio, o painel deixa de ser exibido para esse pedido.
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 Africa é o primeiro bloco na página Extensions > Extensions > Shipping > VibeFox DHL Africa > 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-africa 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 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 que o endereço da loja mudar, ou depois 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. Libere o slot na sua conta em vibefox.net.
Sem uma chave ativa, o método de envio DHL Express não é exibido aos clientes no checkout e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin no mesmo navegador ainda vê o método na loja, marcado 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 visualização 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 de abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. Feche-o com × para ocultá-lo por 7 dias. 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 ou a página Edit do administrador: uma vez por dia nos primeiros 14 dias após a chave ser inserida, 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
O DHL Express não aparece no checkout: verifique se a licença está ativa e se Enable DHL Express Africa está ativado. Verifique a Geo zone (ou ative Ignore shipping zones e verifique Countries), os limites de peso e o Minimum subtotal. Sem tarifa em tempo real, o método só aparece se houver um preço de país ou um custo de contingência definido. Verifique se os produtos têm Requires Shipping definido como Yes.
As tarifas em tempo real não aparecem: verifique os avisos no topo da página da extensão (credenciais ou origem vazias). Ative Debug log, recarregue o checkout e veja o campo Log na página da extensão. Erros da DHL, como um erro HTTP da API MyDHL, a ausência de produtos para a rota ou um problema de moeda, são sempre registrados. Verifique se 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 log diz DHL quote not usable. Defina DHL quote currency como essa moeda e informe o Exchange rate. Sem isso, a tarifa em tempo real não é usada e valem os preços de contingência.
Tenho credenciais antigas do DHL XML Services: escolha XML Services (legacy) em DHL API. Mude para a API MyDHL quando receber as credenciais MyDHL.
O imposto é cobrado duas vezes no envio: defina uma Tax class para que a tarifa da DHL seja usada sem o imposto 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 da extensão. Isso limpa o cache de cotações da DHL.
A página diz "Warning: You do not have permission to modify VibeFox DHL Africa!": 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_africa (OpenCart 3) ou extension/vfd_dhl_africa/shipping/vfd_dhl_africa (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: a extensão dispara os eventos do OpenCart catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request e xml_request (com o mesmo prefixo), que podem alterar o endereço da API, a declaração aduaneira, a caixa e as requisições à DHL.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox DHL Africa. O OpenCart sempre redefine Enable DHL Express Africa, Sort order, Tax class e Geo zone. As cotações da DHL em cache e os eventos da extensão são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da DHL e o log de depuração 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 produtos DHL dos pedidos feitos nunca são excluídos. Pedidos existentes mantêm o método de envio e o custo.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox DHL Africa na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
DHL é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela DHL.