VibeFox Delhivery for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Token de API da Delhivery (somente para tarifas em tempo real): faça login no Delhivery One e abra Settings > API setup. O artigo de ajuda da Delhivery “API token generation” explica os passos. Tokens de teste funcionam com o ambiente de staging. Você também precisa do código PIN de 6 dígitos do seu local de coleta. Se usar apenas preços fixos, não precisa de token.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_delhivery para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Delhivery, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira o token de API e seu código PIN de origem, escolha Express ou Surface e Pre-paid ou COD. Se a moeda da sua loja não for INR, insira a taxa de conversão. Opcionalmente, insira preços fixos (veja Configuração).
6. Adicione VibeFox Delhivery a uma zona de envio (por exemplo, Índia) em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore zones e escolha os países.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox Delhivery. 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 que o cliente vê nesta zona. Deixe vazio para usar o Method title global.
Sempre que você salvar as configurações, as tarifas da Delhivery em cache são limpas. Preços e valores aceitam “9.99” e “9,99”.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.
Method title: o nome do método de envio exibido na finalização de compra. Padrão: Delhivery. Uma zona pode substituí-lo pelo seu próprio Title.
Tax status: Taxable adiciona o imposto do WooCommerce ao custo do envio; None não adiciona.
Conta de API da Delhivery (necessária apenas para tarifas em tempo real)
Environment: Production (track.delhivery.com) (padrão) ou Staging / test account (staging-express.delhivery.com). Use Staging somente com um token de teste da Delhivery.
API token: seu token de API da Delhivery. Ele é enviado somente no cabeçalho de autorização e nunca é gravado nos logs.
Origin pincode: o código PIN de 6 dígitos do seu local de coleta ou depósito, por exemplo 110001.
Tarifas em tempo real
Uma tarifa em tempo real é solicitada para destinos na Índia com um código PIN de 6 dígitos válido, para envios diretos (entregues).
Shipping mode: o modo de cobrança da Delhivery usado para a tarifa: Express (padrão) ou Surface.
Payment type: o tipo de pagamento enviado à Delhivery: Pre-paid (padrão) ou COD (pagamento na entrega; a Delhivery adiciona a taxa de COD). O plugin não altera isso conforme a forma de pagamento escolhida pelo cliente.
Rate amount: a Delhivery retorna o valor com e sem GST.
INR to (store currency) conversion rate: as tarifas da Delhivery estão em rupias indianas. Se a moeda da sua loja não for INR, informe quantas unidades da sua moeda vale uma rupia, por exemplo 0.011. Se deixar vazio, as tarifas em tempo real não são usadas, valem os preços fixos e um aviso aparece acima das configurações. Não é necessário quando a moeda da loja é INR.
Preços fixos (usados quando não há tarifa em tempo real)
Os preços fixos são usados quando ainda não há token ou código PIN, quando o destino está fora da Índia, quando o código PIN não é atendido ou quando a API retorna um erro. Eles são na moeda da sua loja.
Prices per country: um por linha, no formato COUNTRY_CODE:price, por exemplo IN:120. Verificado antes do preço de contingência.
Fallback price: usado quando não se aplica nem uma tarifa em tempo real nem um preço por país. Deixe vazio para ocultar o método. 0 significa grátis.
Fixed price is charged: Per order cobra o preço uma vez. Per item (price × quantity) multiplica pelo número de itens no carrinho. Uma tarifa da Delhivery em tempo real é sempre para o peso total do pacote.
Condições
Free shipping from: o envio é grátis se o subtotal do carrinho for pelo menos este valor. Nenhuma requisição é enviada à Delhivery. Deixe vazio para desativar.
Show from subtotal: exibe o método somente se o subtotal do carrinho for pelo menos este valor. Deixe vazio para exibi-lo sempre.
Min weight (kg): o peso mínimo do carrinho para exibir o método. 0 significa sem limite.
Max weight (kg): oculta o método se o carrinho for mais pesado. Padrão: 30. 0 significa sem limite.
Os pesos dos produtos são convertidos para kg a partir da unidade de peso da sua loja. A tarifa usa o peso real do carrinho (a soma dos pesos dos produtos), sem peso cúbico nem caixas.
Excluded shipping classes: oculta o método se algum item do carrinho pertencer a uma destas classes de envio do WooCommerce.
Disponibilidade sem zonas de envio
Ignore zones: oferece a Delhivery sem adicioná-la a uma zona de envio, para os países abaixo.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais você envia. Usado somente quando Ignore zones está ativado.
Avançado
Debug log: registra os cálculos de tarifas em WooCommerce > Status > Logs, origem vfd_delhivery. Erros da API são sempre registrados, mesmo quando isso está desativado. Tokens e códigos PIN completos dos clientes nunca são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as suas configurações, métodos de zona e tarifas em cache. Desativar o plugin nunca apaga nada.
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 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 à Delhivery.
Para um endereço indiano com código PIN de 6 dígitos válido, o plugin envia à Delhivery os códigos PIN de origem e de destino, o peso do carrinho em gramas, o modo de envio e o tipo de pagamento, e mostra o valor retornado convertido para a moeda da sua loja. Cada resposta fica em cache por 1 hora. Uma requisição com falha fica em cache por 10 minutos, para que a finalização de compra não espere a Delhivery a cada atualização. O tempo limite da API é de 10 segundos.
Se não houver tarifa em tempo real, usa-se o preço do país ou o preço de contingência. Se nenhum estiver definido, o método fica oculto. O cliente nunca vê um erro da API.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalização de compra. É compatível com o HPOS (armazenamento de pedidos de alta performance) do WooCommerce.
O plugin calcula as tarifas e mostra um link de rastreamento. Ele não cria envios nem conhecimentos de transporte, não imprime etiquetas, não solicita coletas ou manifestos, não verifica a cobertura de códigos PIN, não estima datas de entrega, não sincroniza status de rastreamento nem cota tarifas internacionais da Delhivery. Fora da Índia, somente os preços fixos são usados.
Pedidos e rastreamento
Na tela do pedido, abaixo do endereço de entrega, o bloco Delhivery mostra o modo de envio (Express ou Surface) e a origem do preço: tarifa da Delhivery em tempo real, preço fixo ou limite de frete grátis.
Crie o envio no Delhivery One e depois cole o AWB no campo Delhivery AWB / tracking number e salve o pedido. Um link Track on delhivery.com aparece no admin. O cliente vê Delhivery tracking com um link na página do pedido em Minha conta e nos e-mails de pedido (HTML e texto simples). O AWB é salvo antes do status do pedido, então o e-mail “Pedido concluído” já inclui o AWB se você concluir o pedido no mesmo salvamento.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Delhivery. 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 sua conta na vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a na sua conta na vibefox.net.
Sem uma chave ativa, a Delhivery não é exibida aos clientes na finalização de compra. Gerentes da loja conectados 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 exigem renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Delhivery não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se Ignore zones está ativado e o país está permitido). Confira os limites de peso, Show from subtotal e Excluded shipping classes. Sem tarifa em tempo real, é preciso um preço por país ou um Fallback price.
As tarifas em tempo real não aparecem: verifique o token de API, um Origin pincode válido e, em uma loja que não usa INR, a taxa de conversão. O cliente precisa informar um código PIN indiano válido de 6 dígitos. Ative o Debug log e abra WooCommerce > Status > Logs, origem vfd_delhivery, para ver os erros da API, por exemplo um código PIN não atendido.
O GST está sendo cobrado duas vezes: o valor total da Delhivery já inclui o GST. Defina Rate amount como Gross amount (excluding GST) ou Tax status como None.
Testes: use Environment Staging com um token de teste da Delhivery.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as tarifas da Delhivery em cache.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na 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 todos os dados. Para removê-lo, 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. As configurações, os métodos de zona e as tarifas em cache são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os números AWB continuam nos pedidos, e os pedidos existentes mantêm suas linhas de envio.
Delhivery é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Delhivery.