VibeFox Delhivery for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
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 as etapas. Ambos os links estão na página do módulo. 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: adquirida em vibefox.net. Uma chave funciona em um 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, depois, localize VibeFox Delhivery 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. Insira o token de API e o seu código PIN de origem, escolha Express ou Surface e Pre-paid ou COD. Se a moeda padrão da sua loja não for INR, insira a taxa de conversão. Opcionalmente, insira preços fixos (consulte Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora Delhivery com o texto de prazo de entrega Courier delivery (India) e a página de rastreamento da Delhivery como URL de rastreamento. 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, logo 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 ficam na página do módulo: Modules > Module Manager > VibeFox Delhivery > Configure. Elas valem para todas as zonas. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa o cache de tarifas da Delhivery. Os valores aceitam «9.99» e «9,99». Se um campo numérico não contiver um número não negativo, um erro é exibido e nada é salvo.
Se a moeda padrão da sua loja não for INR, houver um token de API salvo e nenhuma taxa de conversão definida, um aviso acima do formulário lembra que as tarifas em tempo real não são usadas até que você insira a taxa. Se a unidade de peso da sua loja não for uma unidade padrão (kg, g, lb ou oz), um aviso pede que você a defina em International > Localization (Local units), pois, caso contrário, os pesos dos produtos são lidos como quilogramas.
Geral
Enable Delhivery: ativa ou desativa a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido no carrinho e na finalização de compra. Padrão: Delhivery. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. Com uma regra, o PrestaShop adiciona o imposto ao custo do frete.
Conta de API da Delhivery (necessária somente 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: o seu token de API da Delhivery. Ele é enviado somente no cabeçalho de autorização e nunca é gravado em logs. Depois de salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Remove saved token: ative e salve para excluir o token salvo. Depois disso, somente os preços fixos são usados.
Origin pincode: o código PIN de 6 dígitos do seu local de coleta ou depósito, por exemplo 110001. Se ele não tiver 6 dígitos, um aviso é exibido e as tarifas em tempo real não são solicitadas até que seja corrigido.
Tarifas em tempo real
Uma tarifa em tempo real é solicitada para destinos na Índia com um código PIN válido de 6 dígitos, para envios de ida (entregas).
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 (cash on delivery — Delhivery adds its COD charge). O módulo não o altera de acordo com a forma de pagamento escolhida pelo cliente.
Rate amount: a Delhivery retorna o valor com e sem GST.
INR to (shop currency) conversion rate: o rótulo mostra a moeda padrão da sua loja. As tarifas da Delhivery são em rupias indianas. Se a sua moeda padrão não for INR, informe quantas unidades da sua moeda equivalem a uma rupia, por exemplo 0.011. A taxa precisa ser maior que 0. Se você deixá-la vazia, as tarifas em tempo real não são usadas e os preços fixos são aplicados. Não é necessária se a sua moeda padrão for INR.
Preços fixos (usados quando nenhuma tarifa em tempo real está disponível)
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 expressos na moeda padrão da sua loja, sem impostos.
Prices per country: um por linha, no formato COUNTRY_CODE:price, por exemplo IN:120. Verificados antes do preço de contingência. Linhas em outro formato são descartadas ao salvar, e um aviso as lista.
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 a transportadora. 0 significa grátis.
Fixed price is charged: Per order cobra o preço uma vez. Per item (price × quantity) multiplica-o pelo número de itens no carrinho. Uma tarifa em tempo real da Delhivery é sempre referente ao peso total do pacote.
Condições
Free shipping from: o envio é grátis se o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) for pelo menos este valor. Nenhuma requisição é enviada à Delhivery. Deixe vazio para desativar.
Show from subtotal: exibe a transportadora somente se o subtotal do carrinho for pelo menos este valor. Deixe vazio para sempre exibi-la.
Min weight: o peso mínimo do carrinho em kg para exibir a transportadora. 0 significa sem limite.
Max weight: oculta a transportadora se o carrinho for mais pesado, em kg. Padrão: 30. 0 significa sem limite; campo vazio significa 30 kg. Min weight não pode ser maior que Max weight: a página exibe um erro e nada é salvo.
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 volumétrico nem caixas.
Disponibilidade sem zonas de envio
Ignore zones: quando desativada, os países são definidos pelas zonas da transportadora em Shipping > Carriers. Quando ativada, a transportadora é vinculada a todas as zonas (inclusive às que você criar depois) e oferecida para os países abaixo. Ao desativar, a transportadora recupera as zonas anteriores.
Countries: os países de destino para esse modo, escolhidos entre os seus países ativos. Deixe vazio para usar todos os países para os quais você envia. Usado somente quando Ignore zones está ativada.
Avançado
Debug log: grava os cálculos de tarifas em logs/vfd_dlv_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 esta opção está desativada. Tokens e códigos PIN completos dos clientes nunca são registrados.
Log: exibe o tamanho e os registros mais recentes do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativada, desinstalar o módulo exclui as configurações da Delhivery, a transportadora, as tarifas em cache, os dados dos pedidos e os logs. Quando desativada, tudo é mantido para uma reinstalação. Os números AWB dos pedidos nunca são excluídos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop solicita ao módulo o preço da Delhivery. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro os países (quando Ignore zones está ativada), o peso do carrinho e Show from subtotal. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Delhivery.
Para um endereço na Índia com código PIN válido de 6 dígitos, o módulo 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. O valor retornado é convertido de INR para a moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente. 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 aguarde a Delhivery a cada atualização. O tempo limite da API é de 10 segundos.
Se não houver tarifa em tempo real, é usado o preço do país ou o preço de contingência. Se nenhum dos dois estiver definido, a transportadora é ocultada. O cliente nunca vê um erro da API. O motivo é gravado no log.
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 as tarifas e oferece aos clientes um link de rastreamento. Ele não cria envios nem conhecimentos de transporte, não imprime etiquetas, não solicita coletas nem manifestos, não verifica a cobertura de códigos PIN, não estima datas de entrega, não sincroniza os status de rastreamento e não calcula tarifas internacionais da Delhivery. Fora da Índia, somente os preços fixos são usados.
Pedidos e rastreamento
Quando um pedido é feito com a Delhivery, o módulo salva o modo de envio e a origem do preço junto ao pedido. Na página do pedido no admin, o bloco Delhivery exibe Mode: (Express ou Surface), Price: (tarifa em tempo real da Delhivery, preço fixo ou limite de frete grátis) e o Delhivery AWB / tracking number, ou Not entered yet.
Crie o envio no Delhivery One e, em seguida, insira o AWB dele como número de rastreamento do pedido no bloco Carriers da página do pedido (Edit). O bloco Delhivery passa a exibir um link Track on delhivery.com. O cliente vê um link de rastreamento no histórico do pedido e recebe o e-mail «Em trânsito» do PrestaShop.
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 Delhivery é o primeiro bloco da página Modules > Module Manager > VibeFox Delhivery > 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-delhivery 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 com 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 domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a transportadora Delhivery não é exibida aos clientes na finalização de compra, e nenhuma tarifa é calculada. A loja 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. 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. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Delhivery não aparece na finalização de compra: verifique se a licença está ativa e se Enable Delhivery está ligada. Em Shipping > Carriers, confira se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore zones e verifique Countries. Confira os limites de peso e Show from subtotal. Sem tarifa em tempo real, é preciso um preço por país ou um Fallback price. Os produtos também podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: verifique o token de API, um Origin pincode válido e, se a moeda padrão não for INR, a taxa de conversão. O cliente deve informar um código PIN indiano válido de 6 dígitos. Ative Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Ele mostra o motivo, por exemplo um código PIN não atendido ou um erro HTTP da Delhivery.
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 defina Tax como No tax.
Testes: defina Environment como Staging e use um token de teste da Delhivery.
As tarifas parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa o cache de tarifas da Delhivery.
A página diz que a transportadora Delhivery 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 executa os hooks actionVfdDlvApiUrl e actionVfdDlvApiTimeout, que podem alterar o endereço da API e o tempo limite.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Delhivery e escolha Uninstall. A chave de licença, o status da licença e o cache de tarifas são sempre removidos. Se Remove data on uninstall estiver ativada, a transportadora recupera as zonas anteriores e é excluída (os pedidos mantêm o histórico), e as configurações, o log e os dados da Delhivery dos pedidos (modo e origem do preço) são removidos. Se estiver desativada, a transportadora apenas é desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, a transportadora é restaurada com o status que tinha antes. Os números AWB permanecem nos pedidos.
A Delhivery é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Delhivery.