VibeFox Aramex for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).

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 concede 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 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 uma conta Aramex.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

O download é um único arquivo 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_aramex-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_aramex.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 painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_aramex-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ê 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. Encontre VibeFox Aramex e clique em Install (o botão verde +).

3. Clique em Edit (o botão de lápis) para abrir a página de configurações.

4. Insira 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. Escolha como o custo de frete será calculado, preencha as seções correspondentes (veja Configuração), ative Enable Aramex e clique em Save.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_aramex.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 Aramex, clique em Install (o botão verde +) e depois em Edit (o botão de 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 campos são iguais nas duas versões.

Após a instalação, o método fica desativado até que você ative Enable Aramex e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações Aramex 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 Aramex > Edit. As seções são listadas à esquerda. Um único botão Save na parte inferior salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas Aramex em cache. Se um valor estiver errado, nada é salvo e a página mostra o motivo, por exemplo Enter a method title (1 to 64 characters)., uma mensagem de que um campo deve ser um número, ou The account country code must have 2 letters, e.g. AE. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

Geral

As configurações valem para todas as zonas geográficas. Você pode limitar o método a uma zona geográfica e a determinados países em Conditions.

Enable Aramex: mostra ou oculta a Aramex na finalização de compra. Padrão: desativado.

Method title: o nome do método de frete exibido ao cliente 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 é gravado no log de depuração. Ele nunca é mostrado ao cliente.

Sort order: a posição da Aramex entre os métodos de frete na finalização de compra. Um número inteiro.

Conta da API Aramex (necessária somente para tarifas em tempo real; todos os seis campos são obrigatórios)

Username: seu nome de usuário da API Aramex, geralmente um e-mail. Limpá-lo também apaga a senha salva.

Password: sua senha da API Aramex. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.

Account number: o número de cliente da sua conta Aramex. Limpá-lo também apaga o PIN salvo.

Account PIN: o PIN da sua conta Aramex. Como a senha, ele não é mais exibido após salvar.

Account entity: o código de entidade (escritório) Aramex da sua conta, 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 (documentos abaixo de 0,5 kg), 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 (shipper pays) (padrão), Collect (receiver pays) ou Third party. Geralmente Prepaid.

API weight unit: a unidade enviada à Aramex: Kilograms (KG) (padrão) ou Pounds (LB). Os pesos dos produtos são convertidos da sua classe de peso, e as dimensões da sua classe de comprimento. 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, o que também vale para produtos sem peso.

Currency conversion rate: pede-se à Aramex que cote na moeda padrão da sua loja. Se ela ainda responder 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 o campo vazio para rejeitar essas cotações, para que um cliente nunca seja cobrado na moeda errada.

Envio a partir de (usado para tarifas em tempo real)

Origin country: o país de onde você envia. A primeira opção, Store country, usa o país da sua loja.

Origin city: a cidade de onde você envia. A Aramex exige. O endereço da loja no OpenCart é um texto livre, então a cidade nunca é obtida dele: informe-a aqui.

Origin state / emirate: opcional.

Origin postcode: opcional.

Se o país de origem for o país da sua loja, um estado vazio é obtido da região da sua loja em System > Settings > Store > Local.

Preços fixos (usados quando Shipping cost é Fixed prices, e como alternativa para tarifas em tempo real)

Price per country: uma lista de países e preços na moeda padrão da sua loja, sem impostos. Clique em Add country para adicionar uma linha e no botão × para remover uma. Escolha * All other countries para um preço usado em todos os países sem linha própria. Países sem preço (quando não há linha *) não recebem tarifa fixa, então o método fica oculto para eles.

Fixed price applies: Per order (padrão) cobra o preço uma vez. Per item (price × quantity) multiplica-o pelo número de itens no carrinho. As tarifas Aramex em tempo real são sempre por envio.

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: 100. 0 significa sem limite. Se deixar o campo vazio, são usados 100 kg.

Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de frete (após o cupom, antes dos impostos) atinge este valor. Deixe o campo vazio para sempre mostrá-lo.

Free shipping: ativa a entrega Aramex gratuita a partir do valor abaixo.

Free shipping from: o subtotal dos produtos que precisam de frete (após o cupom, antes dos impostos) a partir do qual a entrega é gratuita. Usado somente quando Free shipping está ativo.

Tax class: a classe de imposto do custo do frete, ou No tax (padrão). As tarifas Aramex em tempo real podem já incluir o IVA. Nesse caso, escolha No tax para não cobrar imposto duas vezes sobre o frete.

Geo zone: ofereça a Aramex somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Countries: ofereça a Aramex somente para estes países de destino. Deixe o campo vazio para permitir todos os países. Este limite se aplica junto com Geo zone.

Avançado

Debug log: grava os cálculos de tarifas e os erros da API em storage/logs/vfd_armx_debug.log.php. O arquivo não pode ser lido pela web. Senhas, PIN e endereços de clientes nunca são registrados. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_armx_debug.old.log.php e um novo log é iniciado.

Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativo, ao desinstalar a extensão são apagadas as configurações Aramex, as tarifas em cache e o log. Quando desativado (padrão), eles são mantidos para uma nova instalação.

Importar / exportar

Exportar: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha e o PIN não são exportados.

Importar: cole o 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 senha e o PIN salvos são mantidos.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de frete, ele pede à extensão o preço da Aramex. Se uma Geo zone estiver definida e o endereço estiver fora dela, a Aramex não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no valor do pedido. Em seguida, a extensão verifica as condições: países permitidos, peso do carrinho e valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de frete, após o desconto do cupom e antes dos impostos. Vales-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 solicitação é enviada à Aramex.

No modo de preços fixos, o preço é obtido da tabela. Nos modos de tarifas em tempo real, a extensão 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 sua loja, arredondado conforme as casas decimais dela, e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.

Cada resposta fica em cache por 1 hora, para que o mesmo carrinho não gere uma nova solicitação. Uma solicitação que falhou 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 alternativo. O motivo é gravado no log de depuração.

A extensão apenas calcula tarifas. Ela não cria envios na Aramex, não imprime etiquetas, não agenda coletas, não rastreia pacotes e não permite que os clientes escolham um escritório da Aramex. Ela não acrescenta nada aos pedidos: o pedido mostra o nome do método e o custo do frete como qualquer outro método de frete do OpenCart. O pacote é sempre enviado à Aramex como uma única peça.

No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe a Aramex na janela Shipping method options. O método funciona do mesmo modo que no OpenCart 3.

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 Aramex é o primeiro bloco na página Extensions > Extensions > Shipping > VibeFox Aramex > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-aramex e o link Manage licenses and domains in your account, que abre a sua conta 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 administrador (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco mostra 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 do domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, o método de frete Aramex não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrador 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 no administrador, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. 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 exigem a renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do administrador ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário 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 Aramex não aparece na finalização de compra: verifique se a licença está ativa e se Enable Aramex está ativado. Confira Geo zone, Countries, os limites de peso e Minimum order amount. No modo de preços fixos, verifique se o país ou * All other countries tem preço. Verifique se os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Ele mostra o motivo: credenciais da API ausentes, código de erro da Aramex, nenhuma cidade de origem, nenhuma 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 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 o IVA. Defina a Tax class como No tax.

As tarifas parecem desatualizadas após uma alteração: clique em Save na página da extensão. Isso limpa as tarifas Aramex em cache.

A página diz "Warning: You do not have permission to modify VibeFox Aramex!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_aramex (OpenCart 3) ou extension/vfd_aramex/shipping/vfd_aramex (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API Aramex pode ser substituído pela configuração vfd_armx_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Aramex. O OpenCart sempre redefine Enable Aramex, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativo, as configurações Aramex 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 ao instalar a extensão novamente. Os pedidos existentes mantêm o método de frete e o custo.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Aramex na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

Aramex é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada à Aramex nem endossada por ela.