VibeFox SMSA Express for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Tabela de tarifas do SMSA Express: os preços da tabela vêm da sua conta na SMSA ou da equipe comercial da SMSA. Insira-os na moeda padrão da sua loja. Se a sua tabela estiver em SAR, AED ou outra moeda, converta-a antes.

passKey da SMSA (somente para valores em tempo real): os valores em tempo real usam o serviço web da SMSA (SECOM, operação getShipCharges). A SMSA emite o passKey sob solicitação: peça ao seu gerente de conta na SMSA ou escreva para info@smsaexpress.com. O passKey pode ser diferente da chave de API do portal de e-commerce da SMSA. A SMSA não tem servidor de testes (sandbox) para este serviço.

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

Instalação

O download é um 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_smsa_express-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_smsa_express.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 administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_smsa_express-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 SMSA Express 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. Insira sua chave de licença do 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 seus preços do SMSA Express na tabela de preços.

6. Opcional: em Live rates (API), ative Live charges, informe seu passKey da SMSA, a cidade e o país de origem e, se a moeda padrão da sua loja não for SAR, a taxa de câmbio.

7. Ative Enable SMSA Express e clique em Save.

OpenCart 4

1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_smsa_express.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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 SMSA Express, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Insira a chave de licença e as configurações como nos passos 4 a 7 do OpenCart 3. A página de configurações e os campos são os mesmos nas duas versões.

Depois da instalação, o método fica desativado até que você ative Enable SMSA Express e salve. Se você reinstalar a extensão após uma desinstalação, as configurações do SMSA Express 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 SMSA Express > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa os valores da SMSA em cache. Um título de método inválido, um valor que não seja número, um número negativo, uma taxa de câmbio de 0, um código de moeda que não tenha 3 letras, um preço incorreto na tabela, um Minimum weight (kg) maior que o Maximum weight (kg) ou uma ordem de classificação que não seja número inteiro são recusados com um erro, e nada é salvo até que você corrija. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

Quando os valores em tempo real estão ativados, avisos acima das configurações informam sobre um passKey, uma cidade de origem ou uma taxa de câmbio ausentes, ou uma tabela de preços vazia. Um aviso também aparece se a loja não tiver uma classe de peso em kg e a unidade de peso padrão dela não for conhecida pela extensão (os pesos dos produtos são então lidos como kg). Adicione uma classe de peso em 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 a uma lista de países com Ignore shipping zones.

Enable SMSA Express: mostra ou oculta o SMSA Express na finalização de compra. Padrão: desativado.

Method title: o nome do método de envio mostrado ao cliente no carrinho e na finalização de compra. Padrão: SMSA Express. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.

Sort order: a posição do SMSA Express entre os métodos de envio na finalização de compra. Um número inteiro.

Tarifas em tempo real (API) (opcional; se a SMSA não retornar valor, a tabela de preços é usada)

Live charges: obtém o valor do envio do SMSA Express. Quando desativado, nada é enviado à SMSA na finalização de compra. Padrão: desativado.

SMSA passKey: a chave do serviço web da SMSA (SECOM). Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente para alterá-la. Marque Remove the saved passKey para excluí-la. Se o log mostrar "Invalid Passkey", esta chave não é aceita por este serviço. Peça à SMSA um passKey para o serviço web.

Ship-from city: a cidade de onde saem os seus pacotes, escrita como a SMSA a escreve, por exemplo Riyadh, Jeddah ou Dammam. Obrigatória para os valores em tempo real: o OpenCart não tem cidade da loja, então ela nunca é obtida do endereço da loja.

Ship-from country: o país de onde saem os seus pacotes. A primeira opção, Store country, usa o país da sua loja em System > Settings > Store > Local. É o padrão.

Shipment type: enviado à SMSA como tipo de remessa. DLV (o padrão) é a entrega padrão. Altere somente se a SMSA tiver informado outro código.

Currency of SMSA charges: o código de 3 letras da moeda em que a SMSA retorna os valores, normalmente SAR (o padrão). Um valor em qualquer moeda diferente desta ou da moeda padrão da sua loja não é usado.

Exchange rate: o preço de 1 unidade da moeda da SMSA na moeda padrão da sua loja, por exemplo 0.27. Não é necessária quando as duas moedas são iguais. Sem ela, valores em outra moeda não são usados e vale a tabela de preços.

Preços (a sua tabela de tarifas do SMSA Express na moeda padrão da sua loja; usada quando os valores em tempo real estão desativados e como alternativa quando a SMSA não retorna valor)

Price table: uma linha por país de destino. Clique em Add country para adicionar uma linha. A linha * All other countries se aplica aos países sem linha própria. Cada linha tem um preço Base e colunas de peso: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Uma coluna de peso vazia ou com 0 usa o preço base. Um preço base de 0 significa frete grátis. Linhas sem nenhum preço não são salvas. Se um país tiver duas linhas, a primeira é usada. Tanto "9.99" quanto "9,99" são aceitos.

Price for countries not in the table: 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 vazio para ocultar o método nesse caso.

Price applies: como o preço é calculado.

Os pesos dos produtos são convertidos da classe de peso do OpenCart para quilogramas.

Condições

Minimum weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite (padrão).

Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 ou um campo vazio significa sem limite.

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 sempre mostrar.

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual o envio pelo SMSA Express é grátis. Quando o carrinho atinge esse valor, o preço é 0 e nenhuma requisição é enviada à SMSA. 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 seus preços (a tabela e os valores da SMSA) já incluírem impostos, por exemplo o IVA saudita.

Geo zone: oferecer o SMSA Express somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. Não é verificada enquanto Ignore shipping zones estiver ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Disponibilidade sem zonas de envio

Normalmente o método é oferecido para os endereços da zona geográfica escolhida em Conditions.

Ignore shipping zones: oferecer o SMSA Express para os países listados abaixo, independentemente da zona geográfica. Quando desativado, a zona geográfica decide e a lista de países não é usada.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativados na loja. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: registra os cálculos de tarifas em storage/logs/vfd_smsa_debug.log.php. O arquivo não pode ser lido pela web. Nenhum endereço de cliente e nenhuma chave são registrados. Erros dos valores em tempo real são sempre registrados, mesmo com esta opção desativada. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_smsa_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 ativado, desinstalar a extensão apaga as configurações do SMSA Express e o log de depuração. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. Os valores em cache são sempre removidos.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O passKey não é exportado.

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. O passKey salvo é mantido.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço do SMSA Express. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o SMSA Express não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no valor do pedido. Em seguida, a extensão verifica as condições: os países de Ignore shipping zones (se ativado), o peso do carrinho e o valor mínimo do pedido. 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 à SMSA.

Com os valores em tempo real ativados, a extensão envia à SMSA a cidade e o país de origem, a cidade e o país do cliente, o tipo de remessa, o peso do pacote em kg e um valor de pagamento na entrega de 0. A SMSA responde com o valor e a moeda dele. A extensão converte o valor para a moeda padrão da sua loja e o arredonda para as casas decimais dela. O preço é então mostrado na moeda do cliente com o imposto da Tax class selecionada. Um valor em tempo real só é solicitado depois que o cliente informa um endereço de entrega com cidade.

Cada valor fica em cache por uma hora, para que o mesmo carrinho não gere uma nova requisição. Uma requisição com falha fica em cache por 5 minutos. Depois de um tempo limite ou erro do servidor, a SMSA não é consultada por 2 minutos. Depois de uma chave rejeitada, ela não é consultada por 5 minutos. Assim, a finalização de compra nunca espera por um serviço com falha a cada atualização. O tempo limite da requisição é de 12 segundos.

Sempre que a SMSA não retornar um valor utilizável (sem passKey, cidade ainda não informada, chave inválida, tempo limite, erro, nenhum serviço para a cidade ou moeda desconhecida), a tabela de preços é usada. Se a tabela e Price for countries not in the table não derem preço algum, o método fica oculto. O cliente nunca vê um erro. O motivo é gravado no log.

A extensão calcula apenas o preço do envio. Ela não cria envios da SMSA, não imprime etiquetas AWB, não trata devoluções e não rastreia pacotes. O pagamento na entrega e a respectiva taxa não estão incluídos no valor em tempo real. Não há seletor de ponto de venda da SMSA: o método é entrega porta a porta. Ela não acrescenta nada aos pedidos: o pedido mostra o título do método e o custo de envio como qualquer outro método de envio do OpenCart.

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 o SMSA Express na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Chave de licença

A extensão funciona com uma chave de licença do VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox SMSA Express é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit, acima das configurações. Cole 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 estão a linha Product: opencart-shipping-smsa-express 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 Modify para a 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 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 domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o SMSA Express não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um 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 vê o login do 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 renovação. O status é verificado novamente automaticamente 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 inserida e depois uma vez por semana. Nenhum cron job é necessário. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O SMSA Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable SMSA Express está ligado. Confira Geo zone (ou, com Ignore shipping zones ligado, Countries), os limites de peso e o Minimum order amount. Confira se o país ou * tem um preço, ou se Price for countries not in the table está definido. Confira se os produtos têm Requires Shipping definido como Yes.

Os clientes veem o preço da tabela em vez do valor da SMSA: a SMSA precisa da cidade do cliente, então até que ela seja informada o preço da tabela é mostrado. A tabela também é usada quando a SMSA não responde, rejeita a chave ou a cidade, ou retorna o valor em uma moeda sem taxa de câmbio. Veja o campo Log na página da extensão para o motivo.

"Invalid Passkey" no log: a chave não é aceita pelo serviço web da SMSA. Peça à SMSA um passKey para o serviço web.

A cidade do cliente não é aceita: a SMSA espera a grafia dela para as cidades. Confira a cidade no endereço de entrega e a Ship-from city.

As configurações não são salvas e aparece um erro: um campo numérico contém texto ou um valor negativo, a taxa de câmbio é 0, o código da moeda não tem 3 letras ou o Minimum weight (kg) é maior que o Maximum weight (kg). Corrija o valor indicado na mensagem e clique em Save novamente.

O imposto sobre o envio está sendo cobrado duas vezes: a sua tabela ou os valores da SMSA podem já incluir o IVA. Defina Tax class como No tax.

As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página da extensão. Isso limpa os valores da SMSA em cache.

A página mostra "Warning: You do not have permission to modify VibeFox SMSA Express!": 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_smsa_express (OpenCart 3) ou extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço do serviço web da SMSA pode ser substituído pela configuração vfd_smsa_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 SMSA Express. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable SMSA Express, Sort order, Tax class e Geo zone. Os valores em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações do SMSA Express 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 SMSA Express na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para excluir o pacote enviado.

O SMSA Express é uma marca registrada do seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo SMSA Express.