VibeFox DHL Africa for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 5.0 ou superior, instalado e ativo. O plugin se recusa a ser ativado sem ele.

PHP: 8.0 ou superior.

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 de API e um segredo de API. Solicite-as no DHL Developer Portal (MyDHL API, "Get access") ou com o seu gerente de contas 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 DHL.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_dhl_africa para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > DHL Express Africa, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Escolha a DHL API, insira a chave de API, o segredo de API e o número da sua conta DHL. Mantenha Test mode ativado enquanto usar credenciais de teste. Preencha o endereço de origem (Ship from). Se a sua conta DHL não for faturada na moeda da sua loja, defina DHL quote currency e Exchange rate. Opcionalmente, defina preços por país e um custo alternativo (veja Configuração).

6. Adicione DHL Express Africa às suas zonas de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > DHL Express Africa. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome desta opção na finalização de compra para esta zona. Deixe em branco para usar o Name global.

Avisos acima das configurações informam quando as tarifas em tempo real estão desligadas por falta de credenciais ou de origem, e quando uma moeda de cotação é definida sem taxa de câmbio. Sempre que você salvar as configurações, as cotações DHL em cache são limpas. Preços e pesos aceitam vírgula ou ponto decimal.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas ao mesmo tempo.

Name: o nome do método de envio exibido na finalização de compra. Padrão: DHL Express.

Tax status: Taxable (com os impostos do WooCommerce ativados) usa a tarifa DHL sem o imposto cotado pela DHL, e o WooCommerce adiciona o próprio imposto. None cobra a tarifa DHL como cotada, com imposto incluído.

Conta DHL Express (necessária apenas para tarifas em tempo real)

DHL API: qual interface da DHL é usada. Apenas os campos da API escolhida são exibidos.

API key: o seu nome de usuário da MyDHL API (chave de API).

API secret: a sua senha da MyDHL API (segredo de API).

XML Site ID: o seu Site ID dos DHL XML Services (somente API legada).

XML password: a sua senha dos DHL XML Services (somente API legada).

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 só funcionam no ambiente de teste, e as de produção só na produção. Desative ao entrar em operação.

Origem do envio

O endereço do qual a DHL coleta 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 em branco para países sem código postal (por exemplo Quênia, Nigéria, Gana).

Tarifas

Todos os preços estão na moeda da sua loja. 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, 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 da sua loja, a tarifa em tempo real é convertida a partir desta moeda com a taxa de câmbio abaixo. Caso contrário, ela não é usada.

Exchange rate: quanto 1 unidade da moeda de cotação DHL vale na moeda da sua loja, por exemplo 1 ZAR = 0.05. Deixe em branco para não converter. A taxa é uma configuração manual.

Fallback cost: um custo fixo quando não há tarifa em tempo real nem preço do país. Deixe em branco para ocultar o método.

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.

Fallback price basis: Per order cobra o preço uma vez. Per item (multiplied by the cart quantity) multiplica o preço pelo número de itens. Aplica-se apenas ao preço do país e ao custo alternativo. A tarifa DHL em tempo real é sempre para a encomenda inteira.

Free shipping from: o subtotal do carrinho a partir do qual este método é grátis. A DHL não é consultada. Deixe em branco para nunca ser grátis.

Condições

Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite.

Maximum weight (kg): oculta o método acima deste peso do carrinho. Padrão: 70. 0 significa sem limite.

Minimum subtotal: mostra o método somente se o subtotal do carrinho for pelo menos este valor. Deixe em branco para sempre mostrar.

Excluded shipping classes: oculta o método se o carrinho contiver um produto de uma destas classes de envio do WooCommerce.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método para os países abaixo, mesmo que a zona de envio correspondente não o inclua.

Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você envia. Usado somente com Ignore shipping zones.

Avançado

Debug log: registra os cálculos de tarifa em WooCommerce > Status > Logs, origem vfd-dhl-africa. Erros da DHL são sempre registrados, mesmo com esta opção desligada. Credenciais e endereços de clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações e os métodos das zonas. Desativar o plugin nunca apaga dados.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro o peso do carrinho, o subtotal mínimo e as classes de envio excluídas. Se o frete grátis se aplicar, o cliente recebe a entrega gratuita e nenhuma requisição é enviada à DHL.

Caso contrário, o plugin envia à DHL a origem e o destino (país, cidade, código postal), o peso do carrinho convertido para 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 internacionais são declarados como mercadoria, com o subtotal do carrinho como valor declarado, para que a DHL cote produtos de encomenda. Envios domésticos não são declarados. Uma tarifa em tempo real só é solicitada depois que o cliente informa uma cidade (com os XML Services, uma cidade ou um código postal).

O produto DHL Express mais barato é mostrado como uma única tarifa com o seu título. O cliente não vê o produto DHL nem o prazo de entrega. O nome do produto (por exemplo "EXPRESS WORLDWIDE (P)") é salvo como DHL product na linha de envio do pedido, para que você saiba o que reservar.

Cada cotação fica em cache por 1 hora por encomenda e rota. Uma requisição que falhou 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 DHL retornar um erro ou não tiver serviço, o cliente não vê erro: usa-se o preço alternativo ou o método fica oculto.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).

O plugin 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 DHL, não permite que o cliente escolha entre produtos DHL, não embala várias caixas, não adiciona seguro e não calcula taxas e impostos de importação. A cotação é apenas do frete. Taxas e impostos de importação são pagos pelo destinatário.

Chave de licença

O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > DHL Express Africa. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a DHL Express não é mostrada aos clientes na finalização de compra. Gerentes da loja logados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente, automaticamente, em segundo plano.

Solução de problemas

A DHL Express não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Verifique os limites de peso, Minimum subtotal e Excluded shipping classes. Sem tarifa em tempo real, o método só aparece se um preço por país ou um custo alternativo estiver definido.

As tarifas em tempo real não aparecem: verifique os avisos no topo da página de configurações (credenciais ou origem ausentes). Ative Debug log e abra WooCommerce > Status > Logs, origem vfd-dhl-africa. Erros da DHL, como credenciais incorretas, falta de serviço para a rota ou problema de moeda, são sempre registrados. Confira se Test mode corresponde às suas credenciais.

A DHL retorna a tarifa em ZAR, NGN ou KES, mas a minha loja usa outra moeda: defina DHL quote currency como essa moeda e informe a Exchange rate. Sem isso, a tarifa em tempo real não é usada e valem os preços alternativos.

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 imposto é cobrado duas vezes sobre o frete: defina Tax status como Taxable, para que a tarifa DHL seja usada sem o IVA da DHL, ou como None, para cobrar o valor DHL como cotado.

As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as cotações DHL em cache.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todas as configurações. Ele apenas limpa as cotações DHL em cache. Para remover o plugin, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos, assim como as cotações em cache. Configurações e métodos das zonas são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos nunca são alterados, e os pedidos existentes mantêm suas linhas de envio.

DHL é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela DHL.