VibeFox iMile for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Tarifa do iMile: os preços acordados com a equipe comercial do iMile. Você os insere na tabela de preços, na moeda padrão da sua loja.
Conta de API do iMile (somente para a estimativa em tempo real): a estimativa em tempo real usa a OpenAPI do iMile "Estimated order delivery costs". Você precisa de um Customer ID e de uma Secret key (a chave de API que o iMile emite junto com o Customer ID). Para um cliente de teste, cadastre-se no portal de desenvolvedores do iMile (developer.imile.com). As chaves de produção são fornecidas pelo seu gerente de conta do iMile. Se você usar apenas a tabela de preços, não precisa de chaves de API.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um único 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 encontre depois o VibeFox iMile na lista de módulos e clique em Configure.
3. Insira 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 seus preços do iMile na Price table. Opcionalmente, preencha a seção Live rates (API) e ative a Live estimate (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora iMile com o texto de prazo de entrega Courier delivery. 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 iMile > Configure. Elas se aplicam a todas as zonas da transportadora. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as estimativas do iMile em cache e os tokens de acesso.
Quando a Live estimate está ativada, mas não consegue funcionar, avisos aparecem acima das configurações: o Customer ID ou a Secret key estão vazios, a cidade ou o país de origem não foram informados (ou o país não é um mercado do iMile), não há taxas de câmbio, ou a tabela de preços está vazia e não há preço para outros países. Um aviso também aparece quando o módulo não reconhece a unidade de peso da loja: os pesos dos produtos são então considerados em quilogramas, por isso defina a unidade em International > Localization (Local units). Ao salvar, o módulo verifica se o Method title é válido (no máximo 64 caracteres), se os campos de valor e peso são números iguais ou maiores que 0, se o Minimum weight não é maior que o Maximum weight e se a regra de imposto existe. Caso contrário, exibe um erro e não salva nada.
Geral
Enable iMile: liga ou desliga 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: iMile. Obrigatório.
Tarifas em tempo real (API) (opcional)
Se o iMile não retornar uma estimativa (sem chaves, cidade ainda não informada, erro, tempo limite, sem taxa de câmbio), a tabela de preços é usada.
Live estimate: ative para obter o custo de envio do iMile. Padrão: desativado. Com a estimativa em tempo real desativada, nada é enviado ao iMile durante a finalização de compra.
Environment: Production (openapi.imile.com) (padrão) ou Test (test-openapi.52imile.cn). Chaves de teste funcionam somente com o servidor de teste e geram preços de teste.
Customer ID: o código de cliente (customerId) emitido pelo iMile, por exemplo C2102192601. Limpar esse campo também limpa a Secret key salva.
Secret key: a chave secreta (chave de API) emitida pelo iMile junto com o Customer ID. Ela assina as requisições. Após salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.
Signature: como as requisições são assinadas.
Ship-from country: o país de onde você envia. Por padrão, é o país da sua loja (Shop country). A lista contém apenas os países para os quais o módulo tem códigos de país do iMile.
Ship-from city: a cidade de onde seus pacotes são enviados, escrita como na lista de cidades do iMile (por exemplo Dubai, Riyadh). Deixe vazio para usar a cidade da loja em Shop Parameters > Contact > Stores.
Ship-from province: opcional, por exemplo Dubai ou Riyadh Province.
iMile service: o tipo de pedido enviado ao iMile: Delivery order (100) (padrão) ou Express order (1100). O Express precisa estar habilitado para sua conta e seu país.
Goods category: o tipo de mercadoria enviada ao iMile: Normal goods (padrão), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents ou Parcel.
Exchange rates: o iMile calcula as estimativas na moeda do país de destino. Insira uma linha por moeda com o preço de 1 unidade na moeda padrão da sua loja, por exemplo "AED = 0.25" ou "SAR = 0.24". Ponto ou vírgula são aceitos como separador decimal. Não é necessária uma taxa para a própria moeda da loja. Sem taxa, as estimativas nessa moeda não são usadas e a tabela de preços é usada no lugar. A mesma taxa converte o valor do carrinho declarado ao iMile. Linhas inválidas são removidas ao salvar.
Preços (usados quando a estimativa em tempo real está desativada e como alternativa quando o iMile não retorna estimativa)
Insira sua tarifa do iMile na moeda padrão da loja, sem impostos. Se ela estiver em AED, SAR ou outra moeda, converta-a antes.
Price table: uma linha por país de destino. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. Escolha * All other countries para uma linha que cubra todos os países sem linha própria. Cada linha tem um Base price e colunas de peso opcionais: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Uma coluna de peso vazia (ou 0) usa o preço base. Um preço base de 0 significa frete grátis para esse país. Tanto "9.99" quanto "9,99" são aceitos. Linhas sem nenhum preço e preços negativos são removidos ao salvar. Só é mantida uma linha por país.
Price for countries not in the table: um preço na moeda padrão da loja. É usado quando a tabela não tem linha para o país de destino (e não há linha *), ou quando a linha não tem preço para esse peso. Deixe vazio para ocultar a transportadora nesse caso.
Price applies: como o preço da tabela é cobrado.
A mesma escolha se aplica à estimativa em tempo real: por pedido, envia um único pacote com o carrinho inteiro; por item, pede uma estimativa para cada pacote diferente e multiplica pelo número de unidades. Se o carrinho tiver mais de 5 pacotes diferentes, a tabela de preços é usada.
Pesos e dimensões dos produtos são convertidos das unidades da sua loja para quilogramas e centímetros.
Condições
Minimum weight: oculta a transportadora quando o carrinho pesa menos, em kg. 0 significa sem limite.
Maximum weight: oculta a transportadora quando o carrinho pesa mais, em kg. Padrão: 30. 0 significa sem limite.
Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para mostrá-la sempre.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega pelo iMile é grátis. Deixe vazio para nunca oferecer frete grátis.
Tax: a regra de imposto da transportadora, ou No tax. Escolha No tax se os preços da tabela e as estimativas do iMile já incluem o IVA.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o iMile para os países abaixo, independentemente da zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas, e as zonas criadas depois também a recebem. Desativar a opção remove essas zonas adicionadas, e a transportadora volta às zonas que tinha antes.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativos. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de tarifas em logs/vfd_imle_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Nenhuma chave e nenhum endereço de cliente são registrados. Requisições com falha ao iMile são sempre registradas, mesmo com o log de depuração desligado. Desligue o log quando terminar.
Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações do iMile, a transportadora, as estimativas em cache e os logs. 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 do iMile. Só 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: países permitidos (quando a Ignore shipping zones está ativada), peso do carrinho e valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada ao iMile.
Com a estimativa em tempo real ativada, o módulo envia ao iMile o país, a província e a cidade de origem, o país de destino, estado, cidade e CEP de destino, o peso do carrinho em kg, o tamanho em cm³ (a partir das dimensões dos produtos), o valor do carrinho, o serviço do iMile e a categoria da mercadoria. A estimativa é sempre solicitada como pré-paga, portanto as taxas de pagamento na entrega não estão incluídas. A estimativa em tempo real só é solicitada depois que o cliente informa um endereço de entrega com cidade, e somente quando todos os produtos do carrinho têm peso. Cada resposta fica em cache por 1 hora. Uma requisição com falha fica em cache por 5 minutos. Após um tempo limite ou erro do servidor, o iMile não é consultado por 2 minutos; após chaves rejeitadas, por 5 minutos, para que a finalização de compra não espere pelo iMile a cada atualização. O tempo limite da API é de 12 segundos. Um token de acesso expirado é renovado automaticamente.
A estimativa é convertida para a moeda padrão da loja com as suas taxas de câmbio. Se o iMile não fornecer uma estimativa utilizável (chaves não definidas, cidade ainda não informada, cidade desconhecida, erro, tempo limite, sem taxa de câmbio), o cliente não vê nenhum erro e é usado o preço da tabela. Se a tabela também não tiver preço, a transportadora fica oculta. O motivo é gravado no log. O preço é calculado na moeda padrão e depois exibido na moeda do carrinho do cliente.
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 segue a nova versão automaticamente.
O módulo calcula apenas as tarifas. Ele não cria envios do iMile, não imprime etiquetas AWB, não solicita coletas, não rastreia pacotes, não concilia pagamentos na entrega nem oferece pontos de retirada ou armários. Use o portal do iMile para os envios.
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 iMile é o primeiro bloco em Modules > Module Manager > VibeFox iMile > Configure, acima das configurações. Insira a chave em License key e clique em Activate. Depois disso, o bloco exibe 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-imile 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 iMile não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao 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 pode 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 durante os primeiros 14 dias após a chave ser inserida, 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
O iMile não aparece na finalização de compra: verifique se a licença está ativa e se o Enable iMile está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative o Ignore shipping zones e confira os Countries. Verifique os limites de peso e o Minimum order amount. Confirme se o país ou o * tem uma linha na Price table, ou se o Price for countries not in the table está definido. Produtos também podem estar limitados a determinadas transportadoras na página do produto.
O preço da tabela aparece no lugar da estimativa do iMile: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Motivos comuns: a Live estimate está desativada, faltam as chaves, o cliente ainda não informou uma cidade, o iMile não reconhece a grafia da cidade, os produtos não têm peso, não há taxa de câmbio para a moeda de destino, ou um erro da API. Verifique também os avisos acima das configurações.
"sign is invalid" no log: verifique a Secret key e depois tente Signature = SimpleKey.
As chaves são rejeitadas: verifique o Customer ID, a Secret key e o Environment. Chaves de teste funcionam somente com o servidor de teste.
Os nomes das cidades não correspondem: os nomes das cidades precisam corresponder à lista de cidades do iMile. Desenvolvedores podem mapeá-los com o hook actionVfdImileLiveRequest, e os códigos de país com o hook actionVfdImileLiveCountryCode.
Os preços estão na moeda errada: a tabela de preços fica na moeda padrão da loja. Converta uma tarifa em AED, SAR ou MXN ao inseri-la. As estimativas em tempo real são convertidas com a Exchange rates.
O imposto é cobrado duas vezes no frete: se seus preços já incluem o IVA, defina o Tax como No tax.
As estimativas parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa as estimativas do iMile em cache.
A página informa que a transportadora iMile 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
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox iMile e escolha Uninstall. A chave de licença e o status da licença são sempre removidos.As estimativas em cache e os tokens de acesso são sempre removidos. Se o 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 é desabilitada e todas as configurações são mantidas. Reinstalar o módulo restaura o status que a transportadora tinha antes.
iMile é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pelo iMile.