VibeFox Envioclick for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Conta na Envioclick (somente para tarifas em tempo real): uma conta na Envioclick no México ou na Colômbia com acesso à API. A chave de API fica na sua conta da Envioclick, em Mi cuenta (no canto superior direito) > Información del API. Se você usar apenas preços fixos, não precisa de conta na Envioclick.
User-Agent (somente México): a Envioclick México exige um valor de User-Agent em cada requisição à API. Peça-o ao suporte da Envioclick (soporte.tecnico@envioclick.com).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No Back Office, vá em 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 encontre depois VibeFox Envioclick 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. Informe a chave de API, escolha o país da API, informe o User-Agent (México), o código postal 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 de moeda. Para a Colômbia, clique em Add Colombian departments, se a página oferecer essa opção.
5. Opcionalmente, adicione preços fixos por país e um custo alternativo e, depois, clique em Save.
Na instalação, o módulo cria a transportadora Envioclick Shipping com o texto de prazo de entrega Courier delivery by the best Envioclick carrier. 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, logotipo 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 Envioclick > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as cotações da Envioclick em cache. Os campos numéricos aceitam tanto o ponto quanto a vírgula como separador decimal.
Quando uma chave de API está definida, a página mostra avisos no topo se as tarifas em tempo real não puderem funcionar: nenhuma taxa de conversão para uma moeda da loja diferente de MXN ou COP, nenhum User-Agent para o México, nenhum código postal ou código DANE de origem, ou nenhum endereço de origem para a Colômbia. A página também avisa se a unidade de peso ou de dimensão da sua loja não for reconhecida; defina kg, g, lb ou oz e cm, mm, m ou in em International > Localization (Local units). Ao salvar, o módulo verifica se Method title é um nome válido de transportadora, se os campos numéricos contêm números não negativos, se Currency conversion rate é maior que 0, se Minimum weight não é maior que Maximum weight e 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 uma verificação falhar, um erro é exibido e nada é salvo.
Geral
Zonas, grupos de clientes e limites de tamanho da transportadora são definidos em Shipping > Carriers (ou use Ignore shipping zones abaixo). As configurações desta página se aplicam a todas as zonas.
Enable Envioclick: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido ao cliente no carrinho e na finalização de compra. Padrão: Envioclick Shipping. Obrigatório.
Carrier in the title: mostra a transportadora Envioclick e o prazo de entrega estimado de uma tarifa em tempo real abaixo da transportadora na finalização de compra, por exemplo “Estafeta Express, 1 day”. A transportadora é salva no pedido e exibida nas páginas de pedido de qualquer forma. Padrão: ativado.
API Envioclick (tarifas em tempo real)
Opcional. Sem chave de API, apenas os preços fixos são usados. A seção traz links para a documentação da API da Envioclick para o México e a Colômbia. As tarifas em tempo real são solicitadas apenas para destinos do país da API. Envios para outros países usam os preços fixos.
API key: sua chave de API da Envioclick, obtida em Mi cuenta > Información del API. Ela é enviada no cabeçalho “Authorization”. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.
Remove the saved API key: aparece apenas enquanto uma chave está salva. Escolha Yes e salve para excluir a chave; depois disso, somente os preços fixos são usados. Uma chave digitada em API key substitui a salva.
API country: o país da sua conta na Envioclick.
Colombian departments: somente Colômbia. O PrestaShop não tem departamentos colombianos por padrão. Sem eles, são reconhecidos apenas nomes de cidades que são únicos na Colômbia; o departamento distingue municípios com o mesmo nome. O botão Add Colombian departments adiciona os 33 departamentos como estados da Colômbia (códigos ISO ANT, DC etc.), ativa “Contains states” para a Colômbia e acrescenta o campo de departamento ao formulário de endereço colombiano. Departamentos que já existem não são adicionados de novo. Quando tudo estiver pronto, o campo mostra quantos departamentos os endereços colombianos têm.
User-Agent (México): o valor emitido pelo suporte da Envioclick (soporte.tecnico@envioclick.com), por exemplo EcUserAgent-2/123456. Obrigatório para o México; sem ele, as tarifas em tempo real não são solicitadas para o México. Opcional para a Colômbia.
Carrier choice: Cheapest (padrão) ou Fastest (then cheapest). A Envioclick retorna cotações de várias transportadoras, e o cliente recebe uma única tarifa.
Branch pickup rates: considera também as tarifas “Ocurre”, em que o cliente retira o pacote na agência da transportadora. Quando desligado, apenas as tarifas de entrega em domicílio são usadas. Serviços de pagamento na entrega (COD) nunca são usados. Padrão: desligado.
Currency conversion rate: a 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 do pacote é convertido da mesma forma. Deixe em branco 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.
Origem do envio
Usado para as tarifas em tempo real. Campos vazios são preenchidos com o endereço da loja em Shop Parameters > Contact > Stores, se a loja estiver no país da API.
Origin postcode / DANE code: México: o código postal de 5 dígitos. Colômbia: o código DANE de 8 dígitos do município, por exemplo 11001000 para Bogotá; o código de município de 5 dígitos (11001) também funciona.
Origin address: a rua e o número do endereço de coleta. Obrigatório para a Colômbia, opcional para o México.
Preços 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 tabela de códigos de país de 2 letras e preços na moeda padrão da loja, sem impostos. Clique em Add row para adicionar um país e no ícone de lixeira para removê-lo. Use * como código de país para todos os países sem linha própria.
Fallback cost: usado quando não há tarifa em tempo real e nenhuma linha da tabela corresponde. Deixe em branco para ocultar a transportadora nesse caso.
Fixed price applies: Per order cobra o preço uma vez. Per item (price × quantity) multiplica pelo número de itens no carrinho. As tarifas em tempo real da Envioclick são sempre por envio.
Condições
Minimum weight: oculta a transportadora abaixo deste peso do carrinho, em kg. 0 significa sem limite.
Maximum weight: oculta a transportadora acima deste peso do carrinho, em kg. Padrão: 25. 0 significa sem limite.
Minimum order amount: exibe a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) é pelo menos este valor. Deixe em branco para exibi-la sempre.
Free shipping from: frete grátis quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Nenhuma requisição é feita à Envioclick nesse caso. Deixe em branco para nunca oferecer frete grátis.
Tax: a regra de imposto da transportadora, ou No tax. As cotações da Envioclick já incluem os impostos das transportadoras; por isso, escolha No tax para não cobrar imposto sobre o frete duas vezes.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida nas zonas atribuídas a ela em Shipping > Carriers.
Ignore shipping zones: oferece a Envioclick para os países indicados abaixo, mesmo que a transportadora não esteja atribuída à zona deles. Quando você ativa a opção, a transportadora é atribuída a todas as zonas, inclusive às criadas depois. Quando você a desativa, a transportadora recupera suas zonas anteriores.
Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você envia (países ativos). Usado somente quando Ignore shipping zones está ativado.
Avançado
Debug log: registra os cálculos de tarifas e os erros da API em logs/vfd_evc_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. A chave de API e os endereços dos clientes não são registrados. Nada é gravado enquanto o log estiver desligado. Desligue-o quando terminar.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo exclui as configurações da Envioclick, a transportadora, as cotações em cache e os logs. A transportadora salva em pedidos anteriores é mantida. Quando desativado, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da Envioclick. Apenas produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro as condições: os países de Ignore shipping zones, o peso do carrinho e o valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Envioclick.
Se uma chave de API estiver definida e o destino estiver no país da API, o módulo solicita cotações à Envioclick. No México, a requisição é feita quando o cliente informa um código postal de 5 dígitos. Na Colômbia, é feita quando o departamento e o município são reconhecidos (acentos e maiúsculas não fazem diferença). O módulo 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. Em seguida, o preço é exibido na moeda do carrinho do cliente.
O pacote é sempre uma única caixa: o peso total convertido para kg, o comprimento e a largura do maior item e uma altura que mantém o volume total de todos os itens. Produtos sem dimensões são considerados como 10 × 10 × 10 cm. Um carrinho sem peso é enviado como 0,5 kg. O valor declarado é o subtotal do carrinho.
Cada cotação fica em cache por 1 hora para a mesma rota e o mesmo pacote. 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. O tempo limite da API é de 10 segundos. Se a Envioclick retornar um erro ou nenhuma transportadora para a rota, o cliente não vê erro: é usado o preço fixo, ou a transportadora é ocultada. O motivo é gravado no log de depuração.
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 apenas tarifas. Ele 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ários pacotes. As cotações em tempo real valem somente para envios nacionais.
Pedidos
Quando um pedido é feito com a transportadora Envioclick, a tarifa calculada para o carrinho dele é salva com o pedido e não muda mais. A página do pedido no Back Office mostra o bloco 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). Para uma tarifa em tempo real, a página do pedido do cliente mostra Shipping carrier. Crie a guia na sua conta da Envioclick.
Pedidos feitos com preço fixo não têm transportadora Envioclick.
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 Envioclick é o primeiro bloco em Modules > Module Manager > VibeFox Envioclick > Configure, 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 deles estão a linha Product: presta-shipping-envioclick 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 para o 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 seguido de 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 único 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. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a transportadora Envioclick não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está logado no back office, então a transportadora também fica oculta para você: você pode 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. Os pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 inserida e depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Envioclick não aparece na finalização de compra: verifique se a licença está ativa e se Enable Envioclick está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones e confira Countries. Verifique os limites de peso e o Minimum order amount. Sem tarifa em tempo real, a transportadora precisa de um preço fixo para o país, de uma linha * ou de um Fallback cost. Os produtos também podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: leia os avisos no topo da página do módulo, depois ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Motivos comuns: falta a taxa de conversão (a moeda da loja não é MXN nem COP), falta o User-Agent (México), falta o código postal ou o código DANE de origem, o código postal 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? A Envioclick retorna preços somente em pesos mexicanos ou colombianos. O módulo nunca mostra um valor em pesos como se fosse outra moeda.
Colômbia: a cidade não é reconhecida: clique em Add Colombian departments na página do módulo para que os clientes possam escolher o departamento, e verifique se o nome do município está digitado corretamente. Um código DANE de 8 dígitos digitado como código postal também funciona.
O imposto é cobrado duas vezes no frete: as cotações da Envioclick já incluem os impostos das transportadoras. Defina Tax como No tax.
As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página do módulo. Isso limpa as cotações em cache.
A página informa que a transportadora da Envioclick não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Envioclick e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As cotações em cache e as tarifas salvas de carrinhos sem pedido são sempre removidas. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, a transportadora salva recupera o status anterior. Os dados da Envioclick de pedidos realizados são mantidos nos dois casos.
A Envioclick é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Envioclick.