VibeFox Aramex for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não pode ser ativado sem ele.
PHP: 8.0 ou superior.
Conta Aramex (somente para tarifas em tempo real): as tarifas em tempo real usam a API Aramex Rate Calculator. A Aramex dá acesso à API aos titulares de conta. Pergunte ao seu gerente de conta Aramex ou consulte o Aramex Developers Solution Center no site da Aramex. Você precisa de seis valores: nome de usuário da API (geralmente um endereço de e-mail), senha, número da conta, PIN da conta, entidade da conta (por exemplo, DXB) e código de país da conta (por exemplo, AE). Se você usar apenas preços fixos por país, não precisa de conta Aramex.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_aramex para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Aramex, 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. Escolha como o valor do frete é calculado e preencha as seções correspondentes (veja Configuração).
6. Adicione VibeFox Aramex a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, 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 Aramex. Elas se aplicam a todas as zonas de envio. Quando você adiciona 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ê salvar as configurações, as tarifas da Aramex armazenadas em cache serão limpas.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas ao mesmo tempo.
Method title: o nome do método de envio exibido no carrinho e na finalização de compra. Padrão: Aramex.
Shipping cost: como o preço é calculado.
O motivo de uma tarifa em tempo real ausente é gravado no log de depuração. Ele nunca é mostrado ao cliente.
Conta da API Aramex (necessária apenas para tarifas em tempo real; todos os seis campos são obrigatórios)
Username: o seu nome de usuário da API Aramex, geralmente um endereço de e-mail.
Password: a sua senha da API Aramex.
Account number: o número da sua conta de cliente Aramex.
Account PIN: o PIN da sua conta Aramex.
Account entity: o código da entidade (escritório) da sua conta Aramex, por exemplo DXB, AMM ou RUH.
Account country code: o código de país de 2 letras da sua conta Aramex, por exemplo AE.
Serviço Aramex (usado para tarifas em tempo real)
Se o endereço de entrega estiver no país de origem, o envio é cotado como Domestic. Todos os outros envios são cotados como International express.
International service: o produto Aramex para envios ao exterior: PPX Priority Parcel Express (padrão), PDX Priority Document Express, PLX Priority Letter Express, DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express ou GDX Ground Document Express.
Domestic service: o produto Aramex para envios dentro do país de origem: ONP Overnight Parcel (padrão), OND Overnight Document, SMP Same Day Parcel, SMD Same Day Document, SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express ou HVY Heavy (20 kg ou mais).
Payment type: quem paga a Aramex pelo envio: Prepaid (o remetente paga), Collect (o destinatário paga) ou Third party. Geralmente Prepaid.
API weight unit: a unidade enviada à Aramex, KG ou LB. Os pesos dos produtos são convertidos da unidade de peso da sua loja. O peso tarifável é o maior valor entre o peso real e o peso volumétrico (comprimento × largura × altura em cm / 5000). O mínimo é 0,5 kg, que também se aplica a produtos sem peso.
Currency conversion rate: o plugin solicita à Aramex uma cotação na moeda da sua loja. Se ainda assim responder em outra moeda, a cotação é multiplicada por este número (1 unidade da moeda da Aramex = X unidades da moeda da sua loja). Deixe em branco para rejeitar essas cotações, assim o cliente nunca é cobrado na moeda errada. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Envio a partir de (endereço de origem) (usado para tarifas em tempo real)
Origin country: o país de onde você envia. Por padrão, é o país da sua loja.
Origin city: a cidade de onde você envia. A Aramex exige este campo.
Origin state / emirate: opcional.
Origin postcode: opcional.
Se o país de origem for o país da sua loja, os campos vazios são preenchidos com o endereço da loja em WooCommerce > Settings > General.
Preços fixos (usados no modo fixo e como alternativa para as tarifas em tempo real)
Price per country: uma tabela com códigos de país de 2 letras e preços na moeda da sua loja. Clique em Add row para adicionar um país e no ícone × para remover um país. Use * como código de país para todos os outros países. Países sem preço (quando não há linha com *) não recebem preço fixo, então o método fica oculto para eles.
Fixed price applies: Per order cobra o preço uma vez. Per item multiplica o preço pelo número de itens no carrinho. As tarifas em tempo real da Aramex são sempre por envio.
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: 100. 0 significa sem limite.
Minimum order amount: exibe o método somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe em branco para exibir sempre.
Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de envio do WooCommerce.
Free shipping: ativa a entrega grátis pela Aramex a partir do valor abaixo.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega é grátis. Usado somente quando Free shipping está ativado.
Tax status: Taxable adiciona o imposto do WooCommerce ao valor do frete, None não adiciona. As tarifas em tempo real da Aramex podem já incluir IVA. Nesse caso, escolha None para que o imposto não seja cobrado duas vezes.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece a Aramex para os países 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 é usado somente quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de tarifa e os erros da API em logs/vfd_armx_debug.log.php na pasta do plugin. O arquivo não pode ser aberto pela web. Senhas, PIN, número da conta e endereços de clientes são mascarados. Desative o log quando terminar.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as suas configurações, métodos de zona, tarifas em cache e logs. Desativar o plugin nunca exclui nada.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce solicita uma tarifa ao plugin. Primeiro, o plugin verifica 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 como Aramex (free) e nenhuma requisição é enviada à Aramex.
No modo fixo, o preço é obtido da tabela. Nos modos em tempo real, o plugin envia à Aramex os endereços de origem e de entrega, o peso tarifável, o serviço e a moeda da sua loja, e exibe o total retornado. Uma tarifa em tempo real só é solicitada depois que o cliente informa uma cidade ou CEP. Cada resposta fica em cache por 1 hora, então o mesmo carrinho não dispara uma nova requisição. Uma requisição com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela Aramex a cada atualização. O tempo limite da API é de 10 segundos.
Se a Aramex retornar um erro, um valor zero ou uma cotação em outra moeda sem taxa de conversão, o cliente não vê nenhum erro. O método fica oculto, ou o preço fixo é usado no modo de alternativa. O motivo é gravado no log de depuração.
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 armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).
O plugin calcula somente tarifas. Ele não cria envios na Aramex, não imprime etiquetas, não agenda coletas, não rastreia encomendas e não permite que o cliente escolha uma agência da Aramex. A encomenda é sempre enviada à Aramex como uma única peça.
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 Aramex. 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 novamente, 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 em 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 em vibefox.net.
Sem uma chave ativa, a Aramex não é exibida aos clientes na finalização de compra. Gerentes de loja logados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete 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 a renovação. O status é verificado novamente em segundo plano, automaticamente.
Solução de problemas
A Aramex 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 está permitido). Verifique os limites de peso, Minimum order amount e Excluded shipping classes. No modo fixo, verifique se o país ou * tem um preço.
As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e abra logs/vfd_armx_debug.log.php na pasta do plugin. Ele mostra o motivo: credenciais da API ausentes, o código de erro da Aramex, cidade de origem ausente, cidade ou CEP de entrega ainda não informados, um limite de peso ou de valor, ou uma cotação em outra moeda. Com Aramex live rates, fixed prices if the API fails selecionado, os clientes continuam recebendo o preço fixo enquanto você resolve o problema.
Erro ERR75 no log: a Aramex rejeitou o login. Verifique o nome de usuário, a senha, o número da conta, o PIN, a entidade e o código de país com o seu gerente de conta Aramex.
Cotação em outra moeda é rejeitada: a Aramex respondeu em uma moeda diferente da moeda da sua loja. Informe a Currency conversion rate, ou peça à Aramex que cote na sua moeda.
O imposto é cobrado duas vezes no frete: os totais da Aramex podem já incluir IVA. Defina Tax status como None.
As tarifas parecem desatualizadas após uma alteração: salve a página de configurações. Isso limpa as tarifas da Aramex armazenadas em cache.
Sandbox da Aramex: o plugin usa a Aramex Rate Calculator de produção. Desenvolvedores podem alterar o endpoint com o filtro vfd_armx_api_url. Os filtros vfd_armx_rate_request, vfd_armx_number_of_pieces e vfd_armx_volumetric_divisor ajustam a requisição, o número de peças e o divisor volumétrico.
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 em 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 de licença deste plugin são sempre removidos. Configurações, métodos de zona, tarifas em cache e logs são removidos somente se Remove data on uninstall estava ativado. Caso contrário, eles permanecem para uma eventual reinstalação. Pedidos existentes mantêm suas linhas de envio.
A Aramex é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Aramex.