VibeFox SMSA Express for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não instala em versões anteriores do PHP.

Tabela de tarifas da SMSA Express: os valores da tabela de preços vêm da sua conta SMSA ou da equipe comercial da SMSA. Informe-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 tarifas em tempo real): as tarifas em tempo real usam o serviço web da SMSA (SECOM, operação getShipCharges). A SMSA emite a passKey mediante solicitação: peça ao seu gerente de conta da SMSA ou escreva para info@smsaexpress.com e solicite acesso ao serviço web da SMSA informando o número da sua conta. A passKey pode ser diferente da chave de API do portal e-commerce da SMSA. A SMSA não tem servidor de teste (sandbox) para este serviço.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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, depois, encontre VibeFox SMSA Express na lista de módulos e clique em Configure.

3. Informe a sua chave de licença VibeFox em License key no bloco de licença no topo da página de configuração e clique em Activate (veja Chave de licença).

4. Informe os seus preços da SMSA Express na tabela de preços e clique em Save.

5. Opcional: em Live rates (API), ative Live charges, informe a sua 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.

Na instalação, o módulo cria a transportadora SMSA Express com o texto de prazo de entrega SMSA Express courier. 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 SMSA Express > 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 SMSA em cache. Um valor que não é número, um número negativo, uma taxa de câmbio de 0, um código de moeda que não tenha 3 letras ou um Minimum weight acima do Maximum weight são recusados com erro, e nada é salvo até que você corrija o valor.

Quando as tarifas em tempo real estão ativas, avisos acima das configurações indicam uma passKey, cidade de origem ou taxa de câmbio ausente, ou uma tabela de preços vazia. Também aparece um aviso se o módulo não reconhecer a unidade de peso da loja (nesse caso, os pesos dos produtos são lidos como kg). Defina kg, g, lb ou oz em International > Localization (Local units).

Geral

Enable SMSA Express: liga ou desliga a transportadora em todas as zonas de uma vez. É a mesma chave do status da transportadora em Shipping > Carriers.

Method title: o nome da transportadora exibido no carrinho e na finalização de compra. Padrão: SMSA Express. Obrigatório, até 64 caracteres.

Tax: a regra de imposto da transportadora, ou No tax. Escolha No tax se os seus preços (a tabela e as tarifas da SMSA) já incluírem imposto, por exemplo o IVA saudita.

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

Live charges: obtém o valor do frete da SMSA Express. Padrão: desligado.

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", essa chave não é aceita por este serviço. Peça à SMSA uma passKey para o serviço web.

Ship-from city: a cidade de onde saem as suas encomendas, escrita como a SMSA escreve, por exemplo Riyadh, Jeddah ou Dammam. Deixe vazio para usar a cidade da loja definida em Shop Parameters > Contact > Stores.

Ship-from country: o país de onde saem as suas encomendas. Por padrão, é o país da sua loja.

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

Currency of SMSA charges: a SMSA retorna cada valor com o código da moeda, normalmente SAR (padrão). Um valor em qualquer moeda diferente desta ou da moeda padrão da 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ário quando as duas moedas são iguais. Sem ele, valores em outra moeda não são usados e a tabela de preços é aplicada. Tanto o ponto quanto a vírgula são aceitos como separador decimal.

Preços (a sua tabela de tarifas da SMSA Express na moeda padrão da loja; usada quando as tarifas em tempo real estão desligadas 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 e no ícone de lixeira para remover. A linha * Default (all other countries) se aplica aos países sem linha própria. Cada linha tem um preço base e colunas de peso: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 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 (nem linha *) ou a linha não tem preço para esse peso. Deixe vazio para ocultar a transportadora nesse caso.

Price applies: como o preço é calculado.

Os pesos dos produtos são convertidos da unidade de peso da sua loja para quilogramas.

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: 30. 0 ou campo vazio significa sem limite.

Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para mostrar sempre.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual o frete da 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.

Disponibilidade sem zonas de envio

Normalmente a transportadora é oferecida nas zonas às quais está atribuída em Shipping > Carriers.

Ignore shipping zones: oferece a SMSA Express para os países abaixo, independentemente da zona correspondente. Enquanto estiver ativo, a transportadora é adicionada a todas as zonas, inclusive às criadas depois. Desativá-lo remove essas zonas adicionadas.

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

Avançado

Debug log: registra os cálculos de tarifas em logs/vfd_smsa_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Nenhum endereço de cliente e nenhuma chave são registrados. Erros das tarifas em tempo real são sempre registrados, mesmo com esta opção desligada. Desligue o log quando terminar.

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 o módulo apaga as configurações da SMSA Express, a transportadora e o log. Quando desativado, tudo é mantido para uma reinstalação. Tarifas em cache são sempre removidas.

Como funciona na finalização de compra

Na etapa de envio, o PrestaShop pede ao módulo o preço da SMSA Express. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro as condições: os países de Ignore shipping zones (se ativo), o peso do carrinho e o valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à SMSA.

Com as tarifas em tempo real ativas, o módulo envia à SMSA a sua cidade e país de origem, a cidade e o país do cliente, o tipo de envio, o peso da encomenda em kg e um valor de pagamento na entrega de 0. A SMSA responde com o valor e a sua moeda. O módulo o converte para a moeda padrão da sua loja, e então o preço é exibido na moeda do carrinho do cliente. Uma tarifa em tempo real só é solicitada 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 nova requisição. Uma requisição com falha fica em cache por 5 minutos. Após timeout ou erro do servidor, a SMSA não é consultada por mais 2 minutos. Após uma chave recusada, 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 timeout da requisição é de 12 segundos.

Sempre que a SMSA não retorna um valor utilizável (sem passKey, sem cidade informada ainda, pesos de produto ausentes, chave inválida, timeout, erro, sem 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, a transportadora fica oculta. O cliente nunca vê um erro. O motivo é gravado no log.

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 acompanha a nova versão automaticamente.

O módulo calcula apenas o valor do frete. Ele não cria envios na SMSA, não imprime etiquetas AWB, não trata devoluções nem rastreia encomendas. O pagamento na entrega e a taxa dele não entram na tarifa em tempo real. Não há seletor de ponto de varejo da SMSA: a transportadora é entrega porta a porta.

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 SMSA Express é o primeiro bloco da página Modules > Module Manager > VibeFox SMSA Express > Configure, acima das configurações. Informe 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 ficam a linha Product: presta-shipping-smsa-express 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 do 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 de alterar o endereço da loja, ou depois de 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 na sua conta vibefox.net.

Sem uma chave ativa, a transportadora SMSA Express não é exibida 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ê: é possível configurar o módulo antes de comprar uma chave, mas não 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 precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia durante os primeiros 14 dias após a inserção da chave, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A SMSA Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable SMSA Express está ligado. Em Shipping > Carriers, confira se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou se Ignore shipping zones está ligado e o país está permitido). Verifique os limites de peso e o Minimum order amount. Confira se o país ou * tem preço, ou se Price for countries not in the table está definido. Além disso, produtos podem estar limitados a certas transportadoras na página do produto.

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 é exibido. A tabela também é usada quando a SMSA não responde, recusa a chave ou a cidade, ou retorna o valor em uma moeda sem taxa de câmbio. Veja o campo Log na página do módulo para ver o motivo.

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

A cidade do cliente não é aceita: a SMSA usa a própria grafia de 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 está acima do Maximum weight. Corrija o valor indicado na mensagem e clique em Save novamente.

O imposto sobre o frete é cobrado duas vezes: sua tabela ou as tarifas da SMSA podem já incluir o IVA. Defina Tax como No tax.

As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as tarifas da SMSA em cache.

A página diz que a transportadora SMSA Express 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 SMSA Express e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativo, 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 desativada e todas as configurações são mantidas. Reinstalar o módulo, ou um Reset, devolve à transportadora o status que ela tinha antes.

SMSA Express é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela SMSA Express.