VibeFox Envioclick 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.

Conta no Envioclick (somente para tarifas em tempo real): uma conta no Envioclick no México ou na Colômbia com acesso à API. A chave da API está na sua conta no Envioclick, em Mi cuenta (canto superior direito) > Información del API. Se você usar apenas valores fixos, não precisa de uma conta no Envioclick.

User-Agent (somente México): o Envioclick México exige um valor de User-Agent em cada requisição à API. Solicite-o ao suporte do Envioclick (soporte.tecnico@envioclick.com).

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_envioclick-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_envioclick.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_envioclick-oc3-(version).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 Envioclick 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 Chave de licença).

5. Insira a chave da API, escolha o país da API, informe o User-Agent (México), o CEP ou o código DANE de origem e o endereço de origem. Se a moeda padrão da sua loja não for MXN nem COP, informe a taxa de conversão. Opcionalmente, adicione valores fixos por país e um custo de contingência. Ative Enable Envioclick e clique em Save.

OpenCart 4

1. Na administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_envioclick.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 Envioclick, 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 iguais nas duas versões.

Após a instalação, o método fica desativado até que você ative Enable Envioclick e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações do Envioclick 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 Envioclick > Edit. As seções aparecem à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento também limpa as cotações do Envioclick em cache. Os campos numéricos aceitam tanto ponto quanto vírgula como separador decimal. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.

A seção General exibe avisos quando as tarifas em tempo real não podem funcionar com as configurações salvas: nenhuma taxa de conversão para uma moeda da loja diferente de MXN ou COP, nenhum User-Agent para o México, nenhum CEP ou código DANE de origem, ou nenhum endereço de origem para a Colômbia. Também avisa se a unidade de peso ou de comprimento da loja não for reconhecida; nesse caso, adicione uma classe de peso com a unidade kg em System > Localisation > Weight Classes ou uma classe de comprimento com a unidade cm em System > Localisation > Length Classes. Ao salvar, a extensão verifica se Method title tem de 1 a 64 caracteres, se os campos numéricos contêm números não negativos, se Currency conversion rate é maior que 0, se Minimum weight (kg) não é maior que Maximum weight (kg), se o código de origem tem 5 dígitos para o México ou 8 dígitos (ou o código de município de 5 dígitos) para a Colômbia, se cada linha de Price per country tem um país válido e um valor, e se Sort order é um número inteiro. Se alguma verificação falhar, nada é salvo e a página lista os erros.

Geral

O cliente vê uma única tarifa do Envioclick, a da transportadora mais barata ou mais rápida. Você pode limitar o método a uma zona geográfica ou a países em Availability.

Enable Envioclick: exibe ou oculta o Envioclick na finalização de compra. Padrão: desativado.

Method title: o nome do método de entrega exibido ao cliente no carrinho e na finalização de compra, com no máximo 64 caracteres. Padrão: Envioclick Shipping. Obrigatório.

Carrier in the title: adiciona ao título a transportadora do Envioclick e o prazo de entrega estimado de uma tarifa em tempo real, por exemplo «Envioclick Shipping (Estafeta Express, 1 day)». O OpenCart salva este título com o pedido, então ele também aparece nos e-mails do pedido e nas páginas de pedidos. A transportadora é salva no pedido de qualquer forma. Padrão: ativado.

Sort order: a posição do Envioclick entre os métodos de entrega na finalização de compra. Um número inteiro.

API do Envioclick (tarifas em tempo real)

Opcional. Sem chave de API, somente os valores fixos são usados. A seção leva à documentação da API do Envioclick para o México e a Colômbia. As tarifas em tempo real são solicitadas apenas para destinos no país da API. A entrega para outros países usa os valores fixos.

API key: a sua chave de API do Envioclick, disponível em Mi cuenta > Información del API. Ela é enviada no cabeçalho «Authorization» e nunca é exibida aos clientes nem gravada no log. Após salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.

Remove the saved API key: ative a opção e salve para excluir a chave salva; então somente os valores fixos são usados. Uma chave digitada em API key substitui a salva. O botão de alternância se desativa sozinho após o salvamento.

API country: o país da sua conta no Envioclick.

User-Agent (Mexico): o valor emitido pelo suporte do Envioclick (soporte.tecnico@envioclick.com), por exemplo EcUserAgent-2/123456. Obrigatório para o México; sem ele, as tarifas em tempo real para o México não são solicitadas. Opcional para a Colômbia.

Carrier choice: Cheapest (padrão) ou Fastest (then cheapest). O Envioclick retorna cotações de várias transportadoras, e o cliente recebe uma única tarifa.

Branch pickup rates: considera também as tarifas «Ocurre», nas quais o cliente retira a encomenda na agência da transportadora. Quando desativado, são usadas apenas as tarifas de entrega em domicílio. Serviços de pagamento na entrega (COD) nunca são usados. Padrão: desativado.

Currency conversion rate: o Envioclick cota em MXN (México) ou COP (Colômbia). Se a moeda padrão da sua loja for outra, informe o valor de 1 MXN ou 1 COP na moeda da sua loja, por exemplo 0,05. O valor declarado da encomenda é convertido da mesma forma. Deixe vazio se a moeda da loja for MXN ou COP. Sem a taxa, as tarifas em tempo real não são usadas em outra moeda.

Envio de

Usado para as tarifas em tempo real. O OpenCart não tem CEP, cidade ou rua da loja, por isso informe-os aqui.

Origin postcode / DANE code: México: o CEP de 5 dígitos. Colômbia: o código DANE de 8 dígitos do município, por exemplo 11001000 para Bogotá; um código de município de 5 dígitos (11001) é completado com 000.

Origin address: a rua e o número do endereço de coleta. Obrigatório para a Colômbia, opcional para o México.

Valores fixos

Usados quando não há tarifa em tempo real: sem chave de API, destino fora do país da API, erro da API ou nenhuma transportadora para a rota.

Price per country: uma lista de países e valores na moeda padrão da sua loja, sem impostos. Clique em Add country para adicionar uma linha e no botão × para remover uma. Escolha * All other countries para um valor usado em todos os países que não têm linha própria.

Fallback cost: usado quando não há tarifa em tempo real e nenhuma linha da tabela corresponde. Deixe vazio para ocultar o método nesse caso.

Fixed price applies: Per order (padrão) cobra o valor uma única vez. Per item (price × quantity) o multiplica pelo número de itens no carrinho. As tarifas em tempo real do Envioclick são sempre por envio.

Condições

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

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

Minimum order amount: exibe o método somente quando o subtotal dos produtos que precisam de entrega (após o cupom, antes do imposto) for pelo menos este valor. Deixe vazio para exibi-lo sempre.

Free shipping from: entrega grátis quando o subtotal dos produtos que precisam de entrega (após o cupom, antes do imposto) atingir este valor. Nesse caso, nenhuma requisição é feita à API. Deixe vazio para nunca oferecer entrega grátis.

Tax class: a classe de imposto do custo de entrega, ou No tax (padrão). As cotações do Envioclick já incluem os impostos das transportadoras; por isso, escolha No tax para não cobrar imposto sobre a entrega duas vezes.

Disponibilidade

Normalmente o método é oferecido para endereços na zona geográfica selecionada, ou em qualquer lugar.

Geo zone: oferece o Envioclick 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 shipping zones está ativado.

Ignore shipping zones: não verifica a zona geográfica; a lista de países abaixo decide. Padrão: desativado.

Countries: os países de destino para este modo. Deixe vazio para permitir todos os países. Usado somente quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de tarifas e os erros da API em storage/logs/vfd_evc_debug.log.php (no OpenCart 4, system/storage/logs/vfd_evc_debug.log.php). O arquivo não pode ser lido pela web. A chave da API e os endereços dos clientes não são registrados. Enquanto o log estiver desativado, nada é gravado, nem mesmo os erros da API. Desative-o quando terminar. Quando o arquivo atinge 5 MB, ele é movido para vfd_evc_debug.old.log.php e um novo log é iniciado.

Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações do Envioclick, as cotações em cache e o log. Quando desativado (padrão), elas são mantidas para uma reinstalação. Os dados do Envioclick dos pedidos realizados são sempre mantidos.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave da API 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 chave da API salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart exibe os métodos de entrega, ele pede à extensão o preço do Envioclick. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o Envioclick não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no valor do pedido. Em seguida, a extensão verifica as condições: os países de Ignore shipping zones, o peso do carrinho e o valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de entrega, 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 a entrega grátis se aplicar, o preço é 0 e nenhuma requisição é enviada ao Envioclick.

Se uma chave de API estiver definida e o destino estiver no país da API, a extensão pede cotações ao Envioclick. No México, a requisição é feita quando o cliente informa um CEP de 5 dígitos. Na Colômbia, é feita quando o município é reconhecido a partir de um código DANE de 8 dígitos no campo de CEP, ou a partir do departamento (a região do endereço do OpenCart) e da cidade; um nome de cidade único na Colômbia é reconhecido sem o departamento. Acentos e maiúsculas/minúsculas não fazem diferença. A extensão escolhe a cotação mais barata ou a mais rápida que não seja pagamento na entrega e a converte para a moeda padrão da sua loja. O preço é arredondado conforme as casas decimais dessa moeda e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.

A encomenda é sempre uma única caixa: o peso total convertido para kg a partir das classes de peso dos produtos, e um tamanho de caixa calculado a partir das dimensões dos produtos convertidas para cm. Produtos sem dimensões contam como 10 × 10 × 10 cm. Um carrinho sem nenhum peso é enviado como 0,5 kg. O valor declarado é o valor do pedido.

Cada cotação fica em cache por 1 hora para a mesma rota e a mesma encomenda. Uma requisição com falha fica em cache por 10 minutos, para que uma API indisponível não atrase cada atualização da finalização de compra. Se o Envioclick retornar um erro ou nenhuma transportadora para a rota, o cliente não vê nenhum erro: o valor fixo ou o custo de contingência é usado, ou o método fica oculto. O motivo é gravado no log de depuração, quando ele está ativado.

A extensão calcula somente tarifas. Ela não cria guias ou etiquetas, não solicita coletas e não rastreia nem cancela envios. Oferece uma tarifa, não uma escolha entre transportadoras, e não usa serviços de pagamento na entrega nem cotações de várias encomendas. As cotações em tempo real valem somente para envios nacionais.

No OpenCart 4, o cliente clica em Choose no bloco do método de entrega na página de finalização de compra e escolhe o Envioclick na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido é feito com o Envioclick, a tarifa calculada na finalização de compra é salva com o pedido e não muda mais. Em Sales > Orders, a página do pedido mostra o painel Envioclick shipping com Envioclick carrier, Estimated delivery e Envioclick rate ID (para uma tarifa em tempo real), Price source (Envioclick live rate, Fixed price per country, Fallback cost ou Free shipping threshold) e Calculated price (excl. tax). O painel é exibido mesmo depois que o método é desativado.

No OpenCart 4, a finalização de compra mantém um único pedido e o atualiza sempre que o cliente confirma de novo. A tarifa salva é então substituída pela tarifa mais recente da finalização de compra. Se o cliente mudar para outro método de entrega, o painel não é mais exibido para esse pedido. Alterações do pedido na administração não mudam a tarifa salva.

Se Carrier in the title estiver ativado, a transportadora faz parte do nome do método de entrega do pedido. Se estiver desativado, uma linha Shipping carrier: com a transportadora de uma tarifa em tempo real é adicionada ao e-mail de novo pedido e à página do pedido na conta do cliente, enquanto a extensão estiver ativada. Crie a guia na sua conta do Envioclick. Pedidos feitos com valor fixo não têm transportadora do Envioclick.

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 Envioclick é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Envioclick > Edit, acima das configurações. Insira a chave em License key e clique em Activate. Depois, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está válida 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-envioclick 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 da administração (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 seguido de 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 nas configurações do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o Envioclick não é exibido aos clientes na finalização de compra e nenhuma tarifa é calculada. 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é-visualização 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 precisam de renovação. O status é verificado novamente de forma automática quando você abre 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 cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O Envioclick não aparece na finalização de compra: verifique se a licença está ativa e se Enable Envioclick está ativado. Verifique Geo zone, ou Ignore shipping zones e Countries, os limites de peso e Minimum order amount. Sem tarifa em tempo real, o método precisa de um valor fixo para o país, de uma linha * All other countries ou de um Fallback cost. Verifique se os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: leia os avisos na seção General, depois ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Motivos comuns: nenhuma taxa de conversão (a moeda da loja não é MXN nem COP), nenhum User-Agent (México), nenhum CEP ou código DANE de origem, o CEP do cliente (México) ou a cidade (Colômbia) ainda não foi informado, o destino está fora do país da API, ou não há transportadora para a rota.

Por que uma taxa de conversão? O Envioclick retorna preços somente em pesos mexicanos ou colombianos. A extensão nunca exibe um valor em pesos como se fosse outra moeda.

Colômbia: a cidade não é reconhecida: verifique se o cliente seleciona o departamento como região do endereço e digita corretamente o nome do município. Um código DANE de 8 dígitos digitado como CEP também funciona.

O imposto sobre a entrega é cobrado duas vezes: as cotações do Envioclick já incluem os impostos das transportadoras. Defina Tax class como No tax.

As tarifas parecem desatualizadas após uma alteração: clique em Save na página da extensão. Isso limpa as cotações em cache.

A página diz "Warning: You do not have permission to modify VibeFox Envioclick!": o seu grupo de usuários administradores pode somente visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_envioclick (OpenCart 3) ou extension/vfd_envioclick/shipping/vfd_envioclick (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API de cotação do Envioclick pode ser substituído pela configuração vfd_evc_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Envioclick. O OpenCart sempre redefine Enable Envioclick, Sort order, Tax class e Geo zone. As cotações em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações do Envioclick 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 você instalar a extensão de novo. Os dados do Envioclick dos pedidos realizados são mantidos nos dois casos, e os pedidos conservam o método de entrega e o custo.

Para remover também os arquivos da extensão no OpenCart 4, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Envioclick na lista de extensões instaladas e, depois, em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

O Envioclick é marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo Envioclick.