VibeFox Aramex for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não instala em versões mais antigas do PHP.
Conta na Aramex (somente para tarifas em tempo real): as tarifas em tempo real usam a API Aramex Rate Calculator. A Aramex concede acesso à API aos titulares de conta. Consulte seu gerente de conta na Aramex ou veja o Aramex Developers Solution Center no site da Aramex. Você precisa de seis valores: nome de usuário da API (normalmente um e-mail), senha, número da conta, PIN da conta, entidade da conta (por exemplo, DXB) e código do país da conta (por exemplo, AE). Se você usa apenas preços fixos por país, não precisa de conta na Aramex.
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 VibeFox Aramex depois na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Escolha como o custo de envio é calculado, preencha as seções correspondentes (veja Configuração) e clique em Save.
Na instalação, o módulo cria a transportadora Aramex 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 Aramex > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas da Aramex em cache.
Geral
Enable Aramex: ativa ou desativa 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: Aramex. Obrigatório.
Shipping cost: como o preço é calculado.
O motivo de uma tarifa em tempo real ausente é registrado 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: seu nome de usuário da API da Aramex, normalmente um e-mail.
Password: sua senha da API da Aramex. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Account number: o número da sua conta de cliente na Aramex.
Account PIN: o PIN da sua conta na Aramex. Assim como a senha, ele não é mostrado novamente após salvar.
Account entity: o código de entidade (escritório) da sua conta na Aramex, por exemplo DXB, AMM ou RUH.
Account country code: o código de país de duas letras da sua conta na 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 (paga o remetente), Collect (paga o destinatário) ou Third party (terceiro). Normalmente Prepaid.
API weight unit: a unidade enviada à Aramex, KG ou LB. Pesos e dimensões dos produtos são convertidos das unidades da sua loja. O peso tarifável é o maior entre o peso real e o peso volumétrico (comprimento × largura × altura em cm / 5000). O mínimo é 0,5 kg, que também vale para produtos sem peso.
Currency conversion rate: a Aramex é solicitada a cotar na moeda padrão da sua loja. Se ela responder mesmo assim em outra moeda, a tarifa é multiplicada por este número (1 unidade da moeda da Aramex = X unidades da moeda padrão da sua loja). Deixe vazio para rejeitar essas cotações, assim o cliente nunca é cobrado na moeda errada.
Envio 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.
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 Shop Parameters > Contact > Stores.
Preços fixos (usados no modo fixo e como alternativa para as tarifas em tempo real)
Price per country: uma tabela de códigos de país de duas letras e preços na moeda padrão da sua loja, sem impostos. Clique em Add row para adicionar um país e no ícone de lixeira para remover um. Use * como código de país para todos os outros países. Países sem preço (quando não há uma linha com *) não recebem tarifa fixa, então a transportadora fica oculta para eles.
Fixed price applies: Per order cobra o preço uma única vez. Per item multiplica pelo número de itens no carrinho. As tarifas em tempo real da Aramex são sempre por envio.
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: 100. 0 significa sem limite.
Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (após descontos, antes de impostos) atinge este valor. Deixe vazio para sempre mostrá-la.
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 de impostos) a partir do qual a entrega é grátis. Usado somente quando Free shipping está ativado.
Tax: a regra de imposto da transportadora, ou No tax. As tarifas em tempo real da Aramex podem já incluir IVA. Nesse caso, escolha No tax para não cobrar o imposto duas vezes.
Countries: oferece a Aramex somente para estes países de destino. Deixe vazio para permitir todos os países das zonas da transportadora.
Avançado
Debug log: grava os cálculos de tarifas e os erros da API em logs/vfd_armx_debug.log.php, na pasta do módulo. 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.
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, ao desinstalar o módulo são apagadas as configurações da Aramex, a transportadora, as tarifas em cache e os logs. Quando desativado, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da Aramex. Só produtos físicos contam: produtos virtuais não somam peso nem entram no valor do pedido. O módulo verifica primeiro as condições: países permitidos, 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 à Aramex.
No modo fixo, o preço vem da tabela. Nos modos em tempo real, o módulo envia à Aramex os endereços de origem e de entrega, o peso tarifável, o serviço e a moeda padrão da sua loja, e usa o total retornado. Uma tarifa em tempo real só é solicitada quando o endereço de entrega tem cidade ou CEP. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
Cada resposta fica em cache por 1 hora, para que o mesmo carrinho não gere 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ê erro. A transportadora fica oculta, ou o preço fixo é usado no modo de alternativa. O motivo é registrado 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 segue a nova versão automaticamente.
O módulo calcula apenas tarifas. Ele não cria envios na Aramex, não imprime etiquetas, não agenda coletas, não rastreia encomendas e não permite ao cliente escolher um escritório da Aramex. A encomenda é sempre enviada à Aramex como uma peça única.
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 Aramex é o primeiro bloco em Modules > Module Manager > VibeFox Aramex > 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-aramex 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 Aramex não é mostrada aos clientes na finalização de compra e nenhuma tarifa é calculada. A loja 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. Pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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, depois uma vez por semana. Não é necessário 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 Aramex não aparece na finalização de compra: verifique se a licença está ativa e se Enable Aramex está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente. Confira Countries, os limites de peso e Minimum order amount. No modo fixo, verifique se o país ou * tem preço. Os produtos também podem estar limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: ative Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Ele mostra o motivo: credenciais da API ausentes, o código de erro da Aramex, falta de cidade de origem, falta de cidade ou CEP de entrega, um limite de peso ou de valor, ou uma cotação em outra moeda. Com Aramex live rates, fixed prices if the API fails, os clientes continuam recebendo o preço fixo enquanto você corrige o problema.
Erro ERR75 no log: a Aramex recusou o login. Confira o nome de usuário, a senha, o número da conta, o PIN, a entidade e o código do país com o seu gerente de conta na Aramex.
Cotação em outra moeda é rejeitada: a Aramex respondeu em uma moeda diferente da moeda padrão 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 como No tax.
As tarifas parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa as tarifas da Aramex em cache.
A página informa que a transportadora Aramex 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 Aramex e escolha Uninstall. A chave de licença, o status da licença e as tarifas em cache são sempre removidos. 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 desabilitada e todas as configurações são mantidas. Instalar o módulo novamente reativa a transportadora salva.
Aramex é uma marca comercial de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Aramex.