VibeFox Delhivery for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e versões posteriores (testado na 4.1.0.3).
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. Os dois links estão na página da extensão. Tokens de teste funcionam com o ambiente de staging. Você também precisa do pincode 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 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_delhivery-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_delhivery.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 administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_delhivery-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 Installer, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Delhivery 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. Informe 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 Chave de licença).
5. Informe o token de API e o seu pincode de origem, escolha Express ou Surface e Pre-paid ou COD. Se a moeda padrão da sua loja não for INR, informe a taxa de conversão. Opcionalmente, informe preços fixos (veja Configuração). Ative Enable Delhivery e clique em Save.
OpenCart 4
1. No administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_delhivery.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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Delhivery, 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.
Após a instalação, o método fica desativado até que você ative Enable Delhivery e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações da Delhivery que você manteve são usadas outra vez.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. As seções são listadas à esquerda. Um botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas da Delhivery em cache. Os valores aceitam "9.99" e "9,99". Se um valor estiver errado, nada é salvo e a página mostra o motivo, por exemplo Enter a valid method title (without < > ; = # { })., uma mensagem informando que um campo deve ser um número não negativo, ou Sort order must be a whole number. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.
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 no topo da página lembra que as tarifas em tempo real não são usadas até que você informe a taxa. Se a loja não tiver uma classe de peso em quilograma e a unidade de peso não for uma padrão (kg, g, lb ou oz), um aviso informa que os pesos dos produtos são lidos como quilogramas. Defina uma unidade padrão em System > Localisation > Weight Classes.
Geral
As configurações se aplicam a todas as zonas geográficas. Você pode limitar o método em Availability.
Enable Delhivery: oferece a Delhivery na finalização de compra. Padrão: desativado.
Method title: o nome do método de envio exibido ao cliente no carrinho e na finalização de compra. Padrão: Delhivery. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.
Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Com uma classe, o OpenCart adiciona o imposto sobre o custo de envio.
Sort order: a posição da Delhivery entre os métodos de envio na finalização de compra. Um número inteiro.
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 mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.
Remove saved token: ative e salve para excluir o token salvo. Então somente os preços fixos são usados.
Origin pincode: o pincode de 6 dígitos do seu local de coleta ou depósito, por exemplo 110001. Se não tiver 6 dígitos, as configurações são salvas com o aviso The origin pincode must have 6 digits — live rates are not requested until it is fixed.
Tarifas em tempo real
Uma tarifa em tempo real é solicitada para destinos na Índia com um pincode válido de 6 dígitos, para um envio de ida (entregue).
Shipping mode: o modo de faturamento 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). A extensão não o altera conforme o método de pagamento escolhido pelo cliente.
Rate amount: a Delhivery retorna o valor com e sem GST.
INR to (store currency) conversion rate: o rótulo mostra a moeda padrão da sua loja. As tarifas da Delhivery estão em rúpias indianas. Se a sua moeda padrão não for INR, informe quantas unidades da sua moeda equivalem a uma rúpia, 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 valem os preços fixos. 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 pincode, o destino está fora da Índia, o pincode não é atendido ou a API retorna um erro. Eles estão na moeda padrão da sua loja, sem impostos.
Prices per country: um por linha no formato CÓDIGO_DO_PAÍS:preço, por exemplo IN:120. É verificado antes do preço de reserva. 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 o método (padrão). 0 significa grátis.
Fixed price is charged: Per order (padrão) cobra o preço uma vez. Per item (price × quantity) o multiplica pelo número de itens no carrinho. Uma tarifa em tempo real da Delhivery é sempre para o peso total do pacote.
Condições
Free shipping from: a entrega é grátis se o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) for pelo menos este valor. Nenhuma requisição é enviada à Delhivery. Deixe vazio para desativar.
Show from subtotal: exibe o método somente se este subtotal 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 (padrão).
Max weight (kg): oculta o método se o carrinho for mais pesado. Padrão: 30. 0 significa sem limite; um campo vazio significa 30 kg. Min weight não pode ser maior que Max weight: a página mostra um erro e nada é salvo.
Os pesos dos produtos são convertidos para kg a partir da classe de peso do OpenCart. A tarifa usa o peso real do carrinho (a soma dos pesos dos produtos), sem peso volumétrico nem caixas.
Disponibilidade
Geo zone: oferece a Delhivery 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 é verificada quando Ignore zones está ativado.
Ignore zones: quando ativado, a zona geográfica não é verificada e o método é oferecido para os países abaixo (todos os países, se a lista estiver vazia).
Countries: os países de destino para esse modo. Usado somente quando Ignore zones está ativado.
Avançado
Debug log: grava os cálculos de tarifas em storage/logs/vfd_dlv_debug.log.php (no OpenCart 4, em system/storage/logs/vfd_dlv_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo quando esta opção está desativada. Tokens e pincodes completos dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_dlv_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações da Delhivery, as tarifas em cache e o log. Quando desativado (padrão), são mantidos para uma nova instalação. Os dados dos pedidos (modo, origem do preço, números de AWB) nunca são excluídos.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O token de API não é exportado.
Import: cole um 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. O token de API salvo não é alterado.
Como funciona na finalização de compra
Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da Delhivery. Se uma Geo zone estiver definida (e Ignore zones estiver desativado) e o endereço estiver fora dela, a Delhivery não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os demais não somam peso e não entram no subtotal. Em seguida, a extensão verifica os países (quando Ignore zones está ativado), o peso do carrinho e o Show from subtotal. 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 à Delhivery.
Para um endereço na Índia com um pincode válido de 6 dígitos (o CEP do endereço), a extensão envia à Delhivery os pincodes 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 loja, arredondado conforme as casas decimais dela e exibido ao cliente na moeda dele com o imposto da Tax class selecionada. 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 pela 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 reserva. Se nenhum dos dois estiver definido, o método é ocultado. O cliente nunca vê um erro da API. O motivo é gravado no log.
A extensão calcula as tarifas e fornece ao cliente um link de rastreamento. Ela não cria envios nem conhecimentos de transporte, não imprime etiquetas, não solicita coletas nem manifestos, não verifica a cobertura de pincodes, não estima datas de entrega, não sincroniza os status de rastreamento e não cota tarifas internacionais da Delhivery. Fora da Índia, apenas os preços fixos são usados.
No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe a Delhivery na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
Pedidos e rastreamento
Quando um pedido é feito com a Delhivery, a extensão salva com o pedido o modo de envio e a origem do preço. Abra o pedido em Sales > Orders: o painel Delhivery acima do histórico do pedido mostra 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.
No OpenCart 4, a finalização de compra mantém um único pedido e o atualiza sempre que o cliente confirma de novo. O modo e a origem do preço são atualizados junto com ele. Se o cliente trocar para outro método de envio antes de um AWB ser informado, o painel da Delhivery deixa de ser exibido para esse pedido.
Crie o envio no Delhivery One e, em seguida, informe o AWB dele no painel e clique em Save. A página não é recarregada. Letras, dígitos e hífens são mantidos (até 64 caracteres). Salve um campo vazio para remover o AWB. Com um AWB, o painel mostra um link Track on delhivery.com. Salvar o AWB exige a permissão para modificar pedidos. Sem ela, o painel é somente leitura.
Um cliente cadastrado vê Delhivery tracking: com o AWB como link para a página de rastreamento da Delhivery, na página do pedido da conta dele. Quando você adiciona uma entrada ao histórico do pedido e notifica o cliente, o e-mail de status do pedido recebe a mesma linha com o link. O e-mail de novo pedido não tem link de rastreamento, porque o AWB é informado depois. O painel e o link de rastreamento também funcionam para pedidos antigos quando a extensão está desativada.
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 Delhivery é o primeiro bloco na página Extensions > Extensions > Shipping > VibeFox Delhivery > Edit, 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 estão a linha Product: opencart-shipping-delhivery e o link Manage licenses and domains in your account, que abre a sua conta 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 administrativo (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 de alterar o endereço da loja ou de liberar uma vaga 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 a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o método de envio da Delhivery não é exibido aos clientes na finalização de compra, e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrativo 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 prévia 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 administrativo. Feche-o com × para ocultá-lo por 7 dias. Os 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 automaticamente quando você abre o Dashboard do administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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
A Delhivery não aparece na finalização de compra: verifique se a licença está ativa e se Enable Delhivery está ativado. Verifique Geo zone, ou Ignore zones e Countries, os limites de peso e Show from subtotal. Sem tarifa em tempo real, é preciso um preço por país ou um Fallback price. Confira se os produtos têm Requires Shipping definido como Yes.
As tarifas em tempo real não aparecem: verifique o token de API, um Origin pincode válido e, se a sua moeda padrão não for INR, a taxa de conversão. O cliente precisa informar como CEP um pincode indiano válido de 6 dígitos. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Ele mostra o motivo, por exemplo um pincode 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 Tax class 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 da extensão. Isso limpa as tarifas da Delhivery em cache.
Não é possível salvar o AWB: a mensagem You do not have permission to modify orders. significa que o seu grupo de usuários administradores precisa da permissão de modificação para sale/order em System > Users > User Groups.
A página diz "Warning: You do not have permission to modify VibeFox Delhivery!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_delhivery (OpenCart 3) ou extension/vfd_delhivery/shipping/vfd_delhivery (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: a extensão dispara os eventos do OpenCart catalog/vfd_delhivery/api_url e catalog/vfd_delhivery/api_timeout, que podem alterar o endereço da API e o tempo limite.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Delhivery. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Delhivery, Sort order, Tax class e Geo zone. As tarifas em cache e os eventos da extensão são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da Delhivery e o log de depuração também são excluídos. Se estiver desativado, as demais configurações são mantidas e usadas novamente quando a extensão for reinstalada. Os dados da Delhivery nos pedidos (modo, origem do preço e números de AWB) nunca são excluídos. Os pedidos existentes mantêm o método de envio e o custo.
No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Delhivery na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
A Delhivery é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada à Delhivery nem endossada por ela.