VibeFox Econt for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Países: Bulgária e Romênia devem estar ativados em System > Localisation > Countries.
Econt: não é necessário contrato nem chave de API. A lista de escritórios é uma nomenclatura pública da Econt. Apenas o código do país é enviado à Econt, nenhum dado do cliente. Preencha um usuário e uma senha do e-Econt somente se a Econt solicitar à sua loja uma autorização. O login do e-Econt está descrito na página de desenvolvedores da Econt (econt.com/developers).
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 README.txt, o pacote do OpenCart 3 vfd_econt-oc3-(versão).ocmod.zip e o pacote do OpenCart 4 vfd_econt.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. Na administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_econt-oc3-(versão).ocmod.zip. A extensão não adiciona modificações OCMOD, portanto você não precisa atualizar Extensions > Modifications. Em vez do Installer, você também 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 Econt 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 em License key, no bloco de licença no topo da página Edit, e clique em Activate (veja License key).
5. Defina os valores por país e verifique as demais opções (veja Configuration), ative Enable/Disable e clique em Save. Clique em Load offices from Econt now para testar a conexão.
OpenCart 4
1. Na administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_econt.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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 Econt, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).
4. Insira a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são os mesmos nas duas versões.
Após a instalação, o método fica desativado até que você ative Enable/Disable e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações que você manteve serão usadas de novo.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Econt > Edit. As seções aparecem à esquerda. Um botão Save salva a página inteira sem recarregá-la. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações, carregar os escritórios ou limpar o log.
No topo da página, a extensão exibe avisos: a API de demonstração está ativada, nenhum valor está definido para a Bulgária ou a Romênia (o método então nunca é exibido), a última consulta de escritórios de um país falhou, ou sua loja não tem uma classe de peso com a unidade kg (os pesos dos produtos são então lidos pelo nome da unidade: kg, g, lb ou oz). Os campos numéricos aceitam vírgula decimal, por exemplo 5,99. Se um campo numérico contiver algo que não seja um número ou um número negativo, ou se Minimum weight (kg) for maior que Maximum weight (kg), um erro indica o campo e nada é salvo. O mesmo acontece com um Name vazio ou com mais de 64 caracteres, um Sort order que não seja um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida.
Geral
Enable/Disable: mostra ou oculta a entrega Econt no checkout. Padrão: desativado.
Name: o nome do método de entrega exibido no carrinho e na finalização de compra. Padrão: Econt Express. Obrigatório, no máximo 64 caracteres.
Sort order: a posição entre os métodos de entrega na finalização de compra. Um número inteiro.
Tax class: a classe de imposto do valor da entrega, ou --- None --- (padrão). O OpenCart adiciona este imposto aos valores abaixo. Com --- None ---, os valores são finais.
Lista de escritórios da Econt
Os escritórios e os Econtomats são carregados da API da Econt e ficam em cache por 24 horas.
Demo API: usa a API de demonstração da Econt com dados de teste. Mantenha-a desativada em uma loja ativa. Os escritórios de demonstração têm IDs diferentes dos reais. No modo de demonstração, a conta de teste pública da Econt é usada quando nenhum login está configurado.
Econt username: opcional. O seu login do e-Econt para a autorização HTTP Basic.
Econt password: opcional. É armazenada no banco de dados da loja e nunca é gravada no log. Depois de salvar, o campo fica vazio e exibe Saved - leave empty to keep it. Digite um novo valor somente para alterá-lo.
Remove the saved password: ative a opção e clique em Save para excluir a senha salva.
Office list: mostra quantos escritórios estão em cache por país e quando foram carregados. O botão Load offices from Econt now recarrega imediatamente as listas da Bulgária e da Romênia e mostra o resultado por país. Se um carregamento falhar, são mantidos os escritórios do último carregamento bem-sucedido. Sem este botão, a lista é carregada automaticamente no primeiro checkout. Alterar Demo API, o usuário ou a senha limpa as listas em cache.
Seletor de escritório na finalização de compra
Show: quais pontos os clientes podem escolher.
City order: mostra primeiro as maiores cidades (Sofia, Plovdiv, Varna, Bucareste e outras). Quando desativado, as cidades são ordenadas alfabeticamente. Padrão: ativado.
City list width: a largura CSS da lista de cidades, por exemplo 100% ou 300px. Padrão: 100%.
Office list width: a largura CSS da lista de escritórios, por exemplo 100% ou 400px. Padrão: 100%.
Valores (o título da seção mostra a moeda padrão da sua loja)
Os valores estão na moeda padrão da sua loja, sem impostos. A extensão não consulta a Econt para obter taxas em tempo real. A Bulgária usa o euro desde 1º de janeiro de 2026, então uma loja búlgara normalmente informa valores em EUR.
Price per country: um país por linha (ou separados por vírgula): código do país, dois-pontos, valor, por exemplo BG:5.99 e RO:8.99 (estes são os valores padrão). Vírgula decimal também é aceita: BG:5,99. Um valor de 0 significa entrega grátis. Se o campo estiver vazio, são usados os valores padrão BG:5.99 e RO:8.99. Entradas em outro formato são ignoradas e listadas em um aviso ao salvar. O restante é salvo.
Calculation: Per order (padrão) cobra o valor uma única vez. Per item (price x quantity) multiplica pelo número de itens que precisam de entrega.
Price for other countries: usado para um país da Econt (Bulgária ou Romênia) que não está listado acima. Vazio ou 0 oculta o método nesse país.
Condições
Subtotal do carrinho significa os produtos que precisam de entrega, após o cupom e antes do imposto.
Free shipping from: o subtotal do carrinho a partir do qual a entrega é grátis. Deixe vazio para nunca oferecer entrega grátis.
Minimum subtotal: exibe o método somente quando o subtotal do carrinho for pelo menos este valor. Deixe vazio para exibi-lo sempre.
Minimum weight (kg): oculta o método para carrinhos mais leves. Os pesos dos produtos são convertidos da classe de peso para kg. Deixe vazio para não haver limite.
Maximum weight (kg): oculta o método para carrinhos mais pesados. Deixe vazio para não haver limite.
Disponibilidade
A Econt entrega somente na Bulgária e na Romênia. Normalmente, a zona geográfica define onde o método é oferecido; com Ignore geo zone, os países selecionados passam a definir isso.
Geo zone: oferece a Econt somente a endereços nesta zona geográfica. All Zones (padrão) significa em toda a Bulgária e a Romênia. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. A zona geográfica não é usada com Ignore geo zone.
Ignore geo zone: a zona geográfica não é verificada. A Econt é oferecida nos países abaixo, esteja ou não o endereço na zona geográfica.
Countries: Bulgária e/ou Romênia. Usado somente com Ignore geo zone. Nenhum selecionado significa todos os países da Econt.
Avançado
Debug log: grava mensagens de depuração em storage/logs/vfd_ecn_debug.log.php (no OpenCart 4, system/storage/logs/vfd_ecn_debug.log.php). O arquivo não pode ser lido pela web. Ao atingir 5 MB, um novo log é iniciado. Erros e avisos da API (Econt inacessível, nenhum escritório, pedido sem escritório) são sempre registrados. Nenhuma senha ou dado de cliente é gravado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações da Econt, o log e as escolhas de finalizações de compra não concluídas. Quando desativado, as configurações são mantidas para uma reinstalação. Os escritórios salvos nos pedidos são sempre mantidos.
Importação / Exportação
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha não é exportada.
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. A senha salva é mantida.
Como funciona na finalização de compra
O método é oferecido somente para a Bulgária e a Romênia. Quando o OpenCart exibe os métodos de entrega, ele pede à extensão o valor da Econt. Com Ignore geo zone, a zona geográfica não é verificada e o método é oferecido somente nos Countries selecionados (nenhum selecionado = Bulgária e Romênia). Caso contrário, se uma Geo zone estiver definida, o endereço precisa estar nela. 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 verifica os limites de peso e o subtotal mínimo e então obtém o valor do país. Se o subtotal do carrinho atingir Free shipping from, o valor é 0. Se não houver lista de escritórios disponível para o país, o método é ocultado, porque a entrega sempre vai para um escritório. O valor é calculado na moeda padrão da sua loja e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.
Quando o cliente seleciona a Econt, duas listas aparecem abaixo do método: City e Office / Econtomat. A lista de escritórios é carregada uma vez por página, somente quando a Econt está selecionada. Os Econtomats são marcados na lista. A escolha é salva imediatamente. Se a lista de escritórios não puder ser carregada, o cliente vê a mensagem Econt offices cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
Quando o cliente clica em Continue na etapa do método de entrega, a extensão verifica no servidor se um escritório foi escolhido e se ele existe na lista da Econt para o país de entrega (filtrada por Show). Sem escritório, o cliente vê Please select an Econt office or Econtomat. Um escritório que não está na lista é recusado com The selected Econt office is not available for the shipping country. Please select it again. O nome do escritório é sempre obtido da lista da Econt, e não do navegador.
No OpenCart 4, o cliente clica em Choose no bloco do método de entrega da página de finalização de compra e escolhe a Econt na janela Shipping method options. As listas City e Office / Econtomat aparecem nessa janela, abaixo do método, e funcionam como descrito acima. O botão Continue da janela não avança sem um escritório válido, com as mesmas mensagens.
A lista de escritórios fica em cache por 24 horas, separadamente para a API ao vivo e a de demonstração e para cada país. Se a Econt não estiver acessível, a última lista válida é usada e a Econt não é consultada novamente por 10 minutos. O tempo limite da API é de 15 segundos. A lista de escritórios vem de https://ee.econt.com/services/ (ao vivo) ou https://demo.econt.com/ee/services/ (demonstração).
A extensão usa somente valores fixos. Ela não consulta a Econt para obter taxas em tempo real, não cria conhecimentos de transporte ou etiquetas, não solicita coletas, não rastreia encomendas, não trata de pagamento na entrega nem entrega em um endereço. Somente a Bulgária e a Romênia têm lista de escritórios.
Pontos de retirada
Quando o pedido é feito, o escritório escolhido na finalização de compra é salvo com o pedido: a cidade, o nome e o endereço do escritório, e o código do escritório da Econt. Use o código do escritório ao criar o envio no e-Econt.
Cliente: o escritório é adicionado ao método de entrega do pedido, por exemplo Econt Express - Econt office / Econtomat: city, office (address) (no máximo 128 caracteres; no OpenCart 4 o texto não é abreviado). Assim ele aparece no histórico de pedidos do cliente, nos e-mails do pedido, na fatura e no pedido na administração. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo, e o escritório do pedido é atualizado junto.
Página do pedido na administração: em Sales > Orders, o painel Econt office / Econtomat acima do histórico mostra o escritório e o seu código, mesmo que o método seja desativado depois. Em Change, escolha outra cidade e outro escritório do país do pedido e clique em Save. O painel mostra Saved., o texto do método de entrega do pedido é atualizado, e uma nota no histórico do pedido (não enviada ao cliente) registra o escritório antigo e o novo. Se você clicar em Save sem escolher um escritório, o painel diz Select a city and an office first - nothing was changed. Um escritório que não está na lista do país do pedido é recusado com The selected Econt office is not available for the shipping country - nothing was changed. Qualquer usuário administrador com permissão de modificação de pedidos pode alterar o escritório; não é necessário acesso às configurações da extensão. Se a lista de escritórios não puder ser carregada, o painel mostra Econt offices cannot be loaded right now. Um pedido feito sem escritório mostra No Econt office is saved for this order., e o log tem um erro para ele.
Os nomes dos escritórios são exibidos no idioma local (cirílico para a Bulgária) quando o idioma da loja é búlgaro ou romeno, e em inglês nos demais casos.
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 Econt é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox Econt > Edit, acima das configurações. Insira 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 ficam a linha Product: opencart-shipping-econt 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 e uma data. Depois de alterar o endereço da loja, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não estiver acessível, 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 de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o método de entrega Econt não é exibido aos clientes na finalização de compra e nenhum valor é calculado. Um usuário administrador conectado à administração 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 vê o login da administração, 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 da administração. 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 exigem renovação. O status é verificado novamente de forma automática ao abrir o Dashboard da administração ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida e, depois, uma vez por semana. Não é necessário um cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
A Econt não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ativado, e se o país de entrega é a Bulgária ou a Romênia (ativado em System > Localisation > Countries). Verifique Geo zone (ou Ignore geo zone e Countries), se há um valor definido para o país, os limites de peso e Minimum subtotal. Verifique a linha Office list nas configurações: o método fica oculto enquanto não houver lista de escritórios para o país. Verifique se os produtos têm Requires Shipping definido como Yes.
A lista de escritórios não carrega: clique em Load offices from Econt now e leia o resultado, ou o aviso no topo da página de configurações. Os erros são sempre gravados no log; ative Debug log para mais detalhes e veja o campo Log. Se a Econt exigir autorização para a sua loja, preencha Econt username e Econt password.
Os clientes veem escritórios de teste: Demo API está ativada. Desative-a em uma loja ativa.
Em qual moeda estão os valores? Na moeda padrão da sua loja, sem impostos. Os clientes os veem na moeda deles.
O imposto é cobrado sobre o valor: uma classe de imposto está selecionada. Defina Tax class como --- None --- se os seus valores já incluem o IVA.
A página mostra "Warning: You do not have permission to modify VibeFox Econt!": o seu grupo de usuários administradores só pode visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_econt (OpenCart 3) ou extension/vfd_econt/shipping/vfd_econt (OpenCart 4) em System > Users > User Groups.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Econt. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort order, Tax class e Geo zone. A extensão sempre remove os seus eventos e as listas de escritórios em cache. Se Remove data on uninstall estiver ativado, as demais configurações, o log e as escolhas de finalizações de compra não concluídas também são excluídos. Se estiver desativado, as configurações são mantidas e usadas novamente quando você instalar a extensão de novo. Os escritórios salvos nos pedidos são sempre mantidos, e os pedidos existentes mantêm o método de entrega e o custo.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Econt na lista de extensões instaladas e, depois, em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
A Econt é marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Econt.