VibeFox iMile for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 ou superior (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Tarifa da iMile: os preços combinados com a equipe comercial da iMile. Você os informa na tabela de preços, na moeda padrão da sua loja.
Conta de API da iMile (somente para a estimativa em tempo real): a estimativa em tempo real usa a OpenAPI da iMile "Estimated order delivery costs". Você precisa de um Customer ID e de uma Secret key (a chave de API que a iMile emite junto com o seu Customer ID). Para um cliente de teste, cadastre-se no portal de desenvolvedores da iMile (developer.imile.com). As chaves de produção são fornecidas pelo seu gerente de contas na iMile. Se você usar apenas a tabela de preços, não precisa de chaves de API.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
O arquivo baixado é um único 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_imile-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_imile.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 admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_imile-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ê também 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. Localize VibeFox iMile e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o 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 as suas tarifas da iMile na Price table. Opcionalmente, preencha a seção Live rates (API) e ative Live estimate (veja Configuração). Ative Enable iMile e clique em Save.
OpenCart 4
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_imile.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. Localize VibeFox iMile, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Informe 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.
Depois da instalação, o método fica desativado até que você ative Enable iMile e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações da iMile que você manteve voltam a ser usadas.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox iMile > Edit. As seções ficam listadas à esquerda. Um botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as estimativas da iMile em cache e os tokens de acesso. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Ao salvar, a extensão verifica se Method title é válido (no máximo 64 caracteres, sem < > ; = # { }), se os campos de preço, valor e peso são números de 0 ou mais, se Minimum weight (kg) não é maior que Maximum weight (kg), se Sort order é um número inteiro e se a classe de imposto e a zona geográfica existem. Caso contrário, mostra um erro e não salva nada.
Avisos aparecem acima das configurações (e novamente após um salvamento) quando Live estimate está ativado mas não pode funcionar: 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 da iMile), não há taxas de câmbio, ou a tabela de preços está vazia e não há preço para os outros países. Também aparece um aviso quando a loja não tem uma classe de peso em kg e a unidade da classe de peso padrão não é conhecida pela extensão: os pesos dos produtos passam então a ser considerados em quilogramas, então adicione uma classe de peso kg em System > Localisation > Weight Classes.
Geral
As configurações se aplicam a todas as zonas geográficas. Você pode limitar o método a uma zona geográfica em Conditions, ou ativar Ignore shipping zones em Countries para limitá-lo a uma lista de países.
Enable iMile: mostra ou oculta a iMile no checkout. Padrão: desligado.
Method title: o nome do método de envio exibido ao cliente no carrinho e no checkout. Padrão: iMile. Obrigatório.
Sort order: a posição da iMile entre os métodos de envio no checkout. Um número inteiro.
Tarifas em tempo real (API) (opcional)
Se a iMile não retornar nenhuma 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 da iMile. Padrão: desligado. Com a estimativa em tempo real desligada, nada é enviado à iMile durante o checkout.
Environment: Production (openapi.imile.com) (padrão) ou Test (test-openapi.52imile.cn). As chaves de teste funcionam somente com o servidor de teste e geram preços de teste.
Customer ID: o código do cliente (customerId) emitido pela iMile, por exemplo C2102192601. Limpá-lo também apaga a Secret key salva.
Secret key: a chave secreta (chave de API) emitida pela iMile junto com o Customer ID. Ela assina as requisições. Depois de salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um valor novo somente para alterá-la.
Signature: como as requisições são assinadas.
Ship-from country: o país de onde você envia. A primeira opção, Store country, usa o país da sua loja. A lista contém apenas os países para os quais a extensão conhece os códigos de país da iMile.
Ship-from city: a cidade de onde seus pacotes são enviados, escrita como na lista de cidades da iMile (por exemplo Dubai, Riyadh). Obrigatória para estimativas em tempo real: o OpenCart não tem uma cidade da loja, então sem este campo só a tabela de preços é usada.
Ship-from province: opcional, por exemplo Dubai ou Riyadh Province.
iMile service: o tipo de pedido enviado à iMile: Delivery order (100) (padrão) ou Express order (1100). O Express precisa estar habilitado para a sua conta e o seu país.
Goods category: o tipo de mercadoria enviado à iMile: Normal goods (padrão), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents ou Parcel.
Exchange rates: a iMile estima na moeda do país de destino. Informe 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". Não é preciso 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 é aplicada no lugar. A mesma taxa converte também o valor do carrinho declarado à iMile.
Preços (usados quando a estimativa em tempo real está desligada e como alternativa quando a iMile não retorna estimativa)
Informe a sua tarifa da 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 botão × para removê-la. 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. "9.99" e "9,99" são aceitos.
Price for countries not in the table: um preço na moeda padrão da loja. Ele é 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 o método nesse caso.
Price applies: como o preço é cobrado.
A mesma escolha vale para a estimativa em tempo real: por pedido, envia um 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.
Os pesos dos produtos são convertidos da classe de peso do OpenCart para quilogramas, e as dimensões, da classe de comprimento para centímetros.
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: 30. 0 significa sem limite. Se você deixar o campo vazio, são usados 30 kg.
Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe vazio para mostrá-lo sempre.
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual a entrega pela iMile é grátis. Deixe vazio para nunca oferecer frete grátis.
Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Escolha No tax se os preços da tabela e as estimativas da iMile já incluírem o IVA.
Geo zone: oferece a iMile somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. A zona geográfica não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Países
Ignore shipping zones: quando ativado, a Geo zone não é verificada e a iMile é oferecida para os países abaixo. Quando desativado (padrão), somente a Geo zone se aplica.
Countries: os países de destino permitidos. Deixe vazio para permitir todos os países habilitados na loja. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de tarifas em storage/logs/vfd_imile_debug.log.php (no OpenCart 4 system/storage/logs/vfd_imile_debug.log.php). O arquivo não pode ser lido pela web. Nenhuma chave e nenhum endereço de cliente são registrados. As requisições à iMile que falharem são sempre registradas, mesmo com o log de depuração desativado. Desative o log quando terminar. Quando o arquivo atinge 5 MB, ele é movido para vfd_imile_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 apaga as configurações da iMile e o log. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. As estimativas em cache e os tokens de acesso são sempre apagados.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A Secret key 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 Secret key salva é mantida.
Como funciona no checkout
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da iMile. Se uma Geo zone estiver definida, Ignore shipping zones estiver desativado e o endereço estiver fora da zona geográfica, a iMile não é oferecida. Somente os produtos com Requires Shipping definido como Yes contam: os outros produtos não somam peso e não entram no valor do pedido. Em seguida, a extensão verifica as condições: países permitidos (quando Ignore shipping zones está ativado), peso do carrinho e valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vale-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 à iMile.
Com a estimativa em tempo real ativada, a extensão envia à iMile o país, a província e a cidade de origem, o país de destino, a região, a cidade e o 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 da iMile e a categoria da mercadoria. A estimativa é sempre solicitada como pré-paga, então as taxas de pagamento na entrega não são incluídas. Uma 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. Depois de um tempo limite ou de um erro do servidor, a iMile não é consultada por 2 minutos; depois de chaves rejeitadas, por 5 minutos, para que o checkout não espere pela 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 a iMile não fornecer uma estimativa utilizável (chaves não configuradas, cidade ainda não informada, cidade desconhecida, erro, tempo limite, sem taxa de câmbio), o cliente não vê erro e o preço da tabela é usado. Se a tabela também não tiver preço, o método é ocultado. O motivo é gravado no log. O preço é calculado na moeda padrão da sua loja, arredondado para as suas casas decimais e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.
No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de checkout e escolhe a iMile na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
A extensão apenas calcula as tarifas. Ela não cria envios iMile, não imprime etiquetas AWB, não solicita coletas, não rastreia encomendas, não concilia pagamentos na entrega e não oferece pontos de retirada ou armários. Ela não adiciona nada aos pedidos: o pedido mostra o nome do método de envio e o custo de envio como qualquer outro método de envio do OpenCart. Use o portal da iMile para os envios.
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 iMile é o primeiro bloco na página Extensions > Extensions > Shipping > VibeFox iMile > 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-imile 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 de modificação da extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um único 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 dela. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o método de envio iMile não é mostrado aos clientes no checkout e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin 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 admin, por isso, 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 admin. 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 do admin ou a página Edit: uma vez por dia nos primeiros 14 dias após informar a chave, depois uma vez por semana. Não é necessário um cron job. Ao desinstalar a extensão, a chave de licença e o status da licença são sempre removidos.
Solução de problemas
A iMile não aparece no checkout: verifique se a licença está ativa e se Enable iMile está ativado. Confira Geo zone, Ignore shipping zones e Countries, os limites de peso e o Minimum order amount. Verifique se o país ou * All other countries tem uma linha na Price table, ou se Price for countries not in the table está preenchido. Confira se os produtos têm Requires Shipping definido como Yes.
O preço da tabela aparece no lugar da estimativa da iMile: ative o Debug log, recarregue o checkout e veja o campo Log na página da extensão. Causas comuns: Live estimate está desligado, as chaves estão ausentes, o Ship-from city está vazio, o cliente ainda não informou uma cidade, a 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: confira a Secret key e depois tente Signature = SimpleKey.
As chaves são rejeitadas: confira o Customer ID, a Secret key e o Environment. As 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 da iMile. Desenvolvedores podem alterar a requisição com o evento do OpenCart vfd_imile/live_request, e os códigos de país com o evento vfd_imile/live_country_code.
Os preços estão na moeda errada: a tabela de preços está na moeda padrão da loja. Converta uma tarifa em AED, SAR ou MXN ao informá-la. As estimativas em tempo real são convertidas com Exchange rates.
O imposto é cobrado duas vezes no envio: se os seus preços já incluírem o IVA, defina Tax class como No tax.
As estimativas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as estimativas da iMile em cache.
A página diz "Warning: You do not have permission to modify VibeFox iMile!": o seu grupo de usuários administradores só pode visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_imile (OpenCart 3) ou extension/vfd_imile/shipping/vfd_imile (OpenCart 4) em System > Users > User Groups.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox iMile. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable iMile, Sort order, Tax class e Geo zone. As estimativas em cache e os tokens de acesso são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da iMile e o log de depuração também são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você reinstalar a extensão. 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 depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox iMile na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
iMile é uma marca registrada de seu titular. Esta extensão não é afiliada nem endossada pela iMile.