VibeFox SF Express for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Conta SF Express (somente para preços em tempo real): os preços em tempo real usam a plataforma aberta FengQiao da SF Express (open.sf-express.com). Você precisa de uma conta mensal da SF Express e de uma conta de desenvolvedor no FengQiao. Cadastre-se lá, crie um aplicativo, adicione a API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) e copie o código do cliente e o checkword. Os checkwords do sandbox e da produção são diferentes. Se você usar apenas a tabela de preços, não precisa de conta na SF Express.
Províncias chinesas (somente para preços em tempo real): o preço em tempo real precisa da província do endereço de entrega. O PrestaShop não tem províncias chinesas por padrão. O módulo pode adicioná-las para você (veja Chinese provinces abaixo).
Chave de licença do 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 upload terminar, clique em Configure, ou encontre depois o VibeFox SF Express na lista de módulos e clique em Configure.
3. Insira a sua chave de licença do VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Preencha a tabela de preços e/ou o custo alternativo e clique em Save.
5. Para preços em tempo real na China continental, insira o código do cliente e o checkword, a província e a cidade de envio (ou defina um endereço de loja na China) e, se a moeda da sua loja não for CNY, a taxa de conversão de moeda. Clique em Add Chinese provinces se a página pedir. Teste primeiro com Sandbox e as credenciais de sandbox.
Na instalação, o módulo cria a transportadora SF Express 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 lá: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox SF Express > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa os preços da SF Express em cache.
Ao salvar, o módulo verifica os números. Um valor que não é número, um valor ou peso negativo, uma taxa de conversão de 0, um Min weight acima de Max weight ou um preço incorreto na tabela de preços são recusados com uma mensagem, e nada é salvo até você corrigir. Avisos acima das configurações informam quando os preços em tempo real estão configurados parcialmente (os itens que faltam são listados), quando a taxa de conversão está ausente, quando os endereços chineses não têm campo de província, ou quando a unidade de peso ou de dimensão da sua loja não é reconhecida pelo módulo. As unidades são definidas em International > Localization (Local units).
Geral
Enable SF Express: liga ou desliga 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 da compra. Padrão: SF Express. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. Com uma regra de imposto, o imposto de envio da sua loja é adicionado ao custo. Escolha No tax se o preço da SF Express já incluir tudo o que você quer cobrar.
API FengQiao da SF Express (preços em tempo real) (opcional, para endereços de entrega na China continental)
Customer code (partnerID): o código do cliente (顾客编码) do seu aplicativo FengQiao. Limpá-lo também apaga o checkword salvo, para que você possa remover as credenciais.
Checkword: o checkword (校验码) do mesmo ambiente. Ele é usado apenas para assinar as solicitações e nunca é enviado nem registrado. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Sandbox: usa o sandbox da FengQiao (sfapi-sbox.sf-express.com) para testes com credenciais de sandbox. Os preços do sandbox não são reais. Desative em uma loja em produção. Padrão: desativado.
SF Express product: qual produto da SF Express tem o preço exibido.
Sender province: a província de onde os pacotes são enviados. Deixe vazio para usar a província do endereço da loja em Shop Parameters > Contact > Stores, quando a loja estiver na China.
Sender city: o nome padrão da cidade chinesa, por exemplo 深圳市. Deixe vazio para usar a cidade da loja, quando a loja estiver na China.
Currency conversion rate: os preços da SF Express são em CNY (yuan). Se a moeda padrão da sua loja não for CNY, informe quantas unidades da sua moeda vale um CNY (1 CNY = ? unidades). Sem ela, os preços em tempo real não são usados. Se a moeda da sua loja for CNY, os preços são usados como estão. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Chinese provinces: mostra se os endereços chineses podem ter província. Se não, clique em Add Chinese provinces. O botão adiciona as 32 províncias, regiões autônomas e municípios como estados da China (códigos ISO como GD e BJ, nomes como "Guangdong / 广东"), ativa "Contains states" para a China e adiciona o campo de estado ao formulário de endereço chinês. As províncias que já existem não são adicionadas de novo. Nada é alterado sem este clique.
Tabela de preços e alternativa (usada para Hong Kong, Macau, Taiwan e outros países, quando os preços em tempo real não estão configurados ou quando a SF Express não retorna preço; os preços estão na moeda padrão da sua loja, sem impostos)
Country prices: uma tabela com um preço base por país. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. A linha * All other countries se aplica a todos os países sem linha própria. Um preço de faixa de peso acima de 0 substitui o preço base para os pacotes dessa faixa: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Um preço base de 0 significa frete grátis. Um preço base vazio significa que não há preço para este país e o custo alternativo é usado. Tanto "9.99" quanto "9,99" são aceitos. Uma linha sem nenhum preço não é salva.
Fallback cost: usado quando nem a SF Express nem a tabela fornecem um preço. Deixe vazio para ocultar a transportadora nesse caso.
Table / fallback price is: como os preços da tabela e o custo alternativo são cobrados.
Os preços em tempo real da SF Express são sempre para o pedido inteiro.
Condições
Free shipping from: o subtotal do carrinho (após descontos, antes de impostos) a partir do qual o frete é grátis. Deixe vazio para nunca oferecer frete grátis. O frete grátis é verificado antes de qualquer preço ser consultado, então a partir deste valor a transportadora é oferecida gratuitamente para todos os destinos em que estiver disponível, mesmo um país sem linha na tabela ou sem Fallback cost.
Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho (após descontos, antes de impostos) atinge este valor. Deixe vazio para exibi-la sempre.
Min weight: o peso mínimo do carrinho em kg. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. 0 significa sem limite.
Max weight: o peso máximo do carrinho em kg. Padrão: 50. 0 ou vazio significa sem limite.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece a SF Express para os países abaixo, independentemente da zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas, e as zonas criadas depois também. Desativar a opção remove essas zonas adicionadas. Quando desativada, a transportadora aparece somente nas suas próprias zonas.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países ativos. Este campo é usado somente quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de preço em logs/vfd_sfex_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Nem o checkword nem os endereços dos clientes são gravados.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativada, desinstalar o módulo apaga as configurações, a transportadora, os preços em cache e os logs. Quando desativada, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da SF Express. Só produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o subtotal atingir Free shipping from, o preço é 0 e nenhuma solicitação é enviada à SF Express.
Para um endereço de entrega na China continental, com código do cliente e checkword configurados, o módulo envia à SF Express a sua província e cidade de envio, a província e a cidade do cliente, o peso do carrinho e o volume do carrinho (a partir dos produtos com as três dimensões). A solicitação é assinada com o seu checkword. A SF Express retorna os preços em CNY, e o módulo converte o escolhido para a moeda padrão da sua loja. O preço é então exibido na moeda do carrinho do cliente.
A SF Express reconhece endereços pelos nomes chineses padrão. A província do cliente vem do campo de estado do endereço. A cidade deve ser escrita em chinês, por exemplo 广州市. Para Beijing, Shanghai, Tianjin e Chongqing, a cidade é preenchida automaticamente. Uma cidade escrita com letras latinas, como "Guangzhou", recebe o preço da tabela.
Cada preço fica em cache por uma hora, então o mesmo carrinho não gera uma nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela SF Express a cada atualização. O tempo limite HTTP é de 10 segundos.
Se não houver preço em tempo real, o preço vem da tabela de preços e, depois, do Fallback cost. Se nenhum dos dois se aplicar, a transportadora fica oculta. O cliente nunca vê um erro. O erro é 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 somente preços. Ele não cria conhecimentos de transporte nem etiquetas, não cria pedidos na SF Express, não agenda coletas, não cancela nem rastreia envios. Crie e rastreie os envios na sua conta da SF Express como de costume. Os clientes não podem escolher um ponto de serviço ou armário da SF. A SF Express é usada como courier porta a porta. Os preços em tempo real existem somente para endereços de entrega na China continental. O módulo foi desenvolvido com base na documentação da FengQiao e em respostas simuladas, então confirme os preços com a sua conta da SF Express (primeiro no sandbox) antes de ir para produção.
Chave de licença
O módulo funciona com uma chave de licença do VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox SF Express é o primeiro bloco da página Modules > Module Manager > VibeFox SF Express > 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-sf-express e o link Manage licenses and domains in your account, que abre a sua conta do 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 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 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 do vibefox.net.
Sem uma chave ativa, a transportadora SF Express não é exibida aos clientes na finalização de compra e nenhum preço é calculado. A vitrine do PrestaShop não sabe que você está logado no 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 nos primeiros 14 dias após a chave ser inserida e, depois, uma vez por semana. Não é necessário nenhum 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 SF Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable SF Express está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou ative Ignore shipping zones e verifique Countries). Verifique os limites de peso e o Minimum subtotal. Verifique se a tabela ou o Fallback cost têm preço para o país. Os produtos também podem estar limitados a certas transportadoras na página do produto.
O preço vem da tabela, não da SF Express: os preços em tempo real precisam do código do cliente e do checkword, de uma província e cidade de envio, de um endereço de entrega na China continental com província e nome de cidade chinês e (para lojas que não usam CNY) da taxa de conversão de moeda. Leia os avisos no topo da página do módulo, depois ative o Debug log, recarregue a finalização de compra e veja o campo Log para ver o motivo. Uma solicitação com falha é repetida após 10 minutos.
O formulário de endereço da China não tem província: clique em Add Chinese provinces na seção da API da página do módulo.
Erro A1006 no log: assinatura inválida. O checkword está errado ou pertence ao outro ambiente. Verifique a configuração Sandbox.
Erro A1004 no log: a API de consulta de preços não foi adicionada ao seu aplicativo FengQiao.
Hong Kong: funciona com a tabela de preços e o custo alternativo. A consulta de preços da FengQiao é apenas para endereços da China continental.
Os preços parecem desatualizados após uma alteração: clique em Save na página do módulo. Isso limpa os preços da SF Express em cache.
A página diz que a transportadora SF 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.
Para desenvolvedores: o hook actionVfdSfExpressQuoteRequest altera a solicitação de preço, por exemplo, para outro código de produto. actionVfdSfExpressApiUrl altera a URL do gateway.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox SF Express e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Os preços 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 desativada e todas as configurações são mantidas. Reinstalar o módulo, ou um Reset, devolve à transportadora o status que ela tinha antes. Os pedidos existentes mantêm suas linhas de envio.
SF Express é uma marca registrada do respectivo titular. Este módulo não é afiliado nem endossado pela SF Express.