VibeFox iMile for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
Tarifa do iMile: os preços acordados com a equipe comercial do iMile. Você os insere na tabela de preços, na moeda 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ê usa 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 domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_imile para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox iMile, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira as suas tarifas do iMile na Price table. Opcionalmente, preencha a seção Live rates (API) e ative Live estimate (veja Configuração).
6. Adicione o VibeFox iMile a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones (por exemplo, "United Arab Emirates"), ou ative Ignore shipping zones e escolha os países.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox iMile. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome que os clientes veem nesta zona. Deixe em branco para usar o Method title global.
Sempre que você salva as configurações, as estimativas do iMile em cache e os tokens de acesso são apagados. Quando a estimativa em tempo real está ativa, mas não pode funcionar (sem chaves, sem cidade ou país de origem, sem taxas de câmbio, tabela de preços vazia), aparecem avisos acima das configurações.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.
Method title: o nome do método de envio exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: iMile.
Estimativas em tempo real (API) (opcional)
Se o 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 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 apenas 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.
Secret key: a chave secreta (chave de API) emitida pelo iMile junto com o Customer ID. Ela assina as requisições.
Signature: a forma 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. A lista contém os países para os quais o plugin 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 em branco para usar a cidade da loja em WooCommerce > Settings > General.
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 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 da sua loja, por exemplo "AED = 0.25" ou "SAR = 0.24". Vírgula ou ponto são aceitos como separador decimal. Não é preciso 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 é utilizada no lugar. A mesma taxa converte o valor declarado do carrinho ao iMile. Linhas inválidas são removidas ao salvar.
Preços (usado quando a estimativa em tempo real está desativada e como alternativa quando o iMile não retorna nenhuma estimativa)
Insira sua tarifa do iMile na moeda da loja. 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 X para remover uma. Escolha * All other countries para uma linha que cobre 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 preço, códigos de país inválidos e preços negativos são removidos ao salvar. Apenas uma linha por país é mantida.
Price for countries not in the table: um preço na moeda 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 este peso. Deixe em branco para ocultar o método nesse caso.
Price applies: como o preço da tabela é cobrado.
A mesma escolha vale para a estimativa em tempo real: por pedido, envia um pacote com todo o carrinho; por item, consulta 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 unidade de peso da loja para quilogramas.
Condições
Minimum weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.
Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite.
Minimum order amount: mostra o método somente quando o subtotal do carrinho (após descontos, antes de impostos) atinge este valor. Deixe em branco para mostrar sempre.
Free shipping from: o subtotal do carrinho (após descontos, antes de impostos) a partir do qual a entrega pelo iMile é grátis. Deixe em branco para nunca oferecer frete grátis.
Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de envio do WooCommerce.
Tax status: Taxable adiciona o imposto do WooCommerce ao custo de envio; None não adiciona. Escolha None se os preços da tabela e as estimativas do iMile já incluírem impostos.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o iMile para os países listados abaixo, mesmo que o método não esteja adicionado a nenhuma zona de envio.
Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você envia. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra os cálculos de tarifas em WooCommerce > Status > Logs (origem "vfd_imile"). Nenhuma chave nem endereço de cliente é registrado. Requisições ao iMile com falha são sempre registradas, mesmo com o log de depuração desativado. Desative o log quando terminar.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações do iMile, os métodos de zona e as estimativas em cache. Desativar o plugin nunca apaga nada.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: país de entrega, peso do carrinho, valor mínimo do pedido e classes de envio excluídas. Se o frete grátis se aplicar, o cliente vê o método sem custo e nenhuma requisição é enviada ao iMile.
Com a estimativa em tempo real ativada, o plugin envia ao iMile o país, a província e a cidade de origem; o país, o estado, 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 do iMile e a categoria da mercadoria. A estimativa é sempre solicitada como pré-paga, por isso as taxas de pagamento na entrega não são incluídas. Uma estimativa em tempo real só é solicitada depois que o cliente informa uma cidade, e apenas quando todos os pacotes 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 de 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 da loja com as suas taxas de câmbio. Se o 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ê nenhum erro e o preço da tabela é usado. Se a tabela também não tiver preço, o método fica oculto. O motivo é registrado no log.
O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin calcula apenas tarifas. Ele não cria envios do iMile, não imprime etiquetas AWB, não solicita coletas, não rastreia pacotes, não concilia cobranças na entrega nem oferece pontos de retirada ou armários. Use o portal do iMile para os envios.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox iMile. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status de novo, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o iMile não é exibido aos clientes na finalização de compra. Os gerentes da loja logados ainda o veem, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um aviso aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente em segundo plano.
Solução de problemas
O iMile não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Confira os limites de peso, Minimum order amount e Excluded shipping classes. Verifique se o país ou * tem uma linha na Price table, ou se Price for countries not in the table está preenchido.
O preço da tabela aparece no lugar da estimativa do iMile: abra WooCommerce > Status > Logs, origem "vfd_imile", e ative o Debug log para ver os detalhes. Motivos comuns: Live estimate desativada, chaves ausentes, cliente ainda não informou a cidade, o iMile não reconhece a grafia da cidade, produtos sem peso, falta taxa de câmbio para a moeda de destino ou erro de API. Veja também os avisos acima das configurações.
"sign is invalid" no log: verifique a Secret key e depois teste Signature = SimpleKey.
As chaves são rejeitadas: verifique o Customer ID, a Secret key e o Environment. Chaves de teste funcionam apenas com o servidor de teste.
Os nomes das cidades não correspondem: os nomes das cidades precisam corresponder à lista de cidades do iMile. Os desenvolvedores podem fazer o mapeamento com o filtro vfd_imile_live_request, e os códigos de país com o filtro vfd_imile_live_country_code.
Os preços estão na moeda errada: a tabela de preços fica na moeda da loja (WooCommerce > Settings > General). Converta uma tarifa em AED, SAR ou MXN ao inseri-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á incluem IVA, defina Tax status como None.
As estimativas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as estimativas do iMile em cache.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações, os métodos de zona e as estimativas em cache são removidos somente se Remove data on uninstall estava ativado. Caso contrário, ficam guardados para uma reinstalação posterior. Os pedidos existentes mantêm suas linhas de envio.
O iMile é uma marca registrada de seu respectivo titular. Este plugin não é afiliado ao iMile nem endossado por ele.