VibeFox SF Express for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posterior (testado na 4.1.0.3).
PHP: 8.0 ou superior.
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 na 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 de sandbox e de 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, que é a zona do OpenCart (Region / State) do endereço. O OpenCart tem as zonas da China, mas o Tibete está faltando. A extensão pode adicioná-lo para você (veja Chinese provinces abaixo).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_sf_express-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_sf_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 painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_sf_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ê pode copiar o conteúdo da pasta upload do pacote para a pasta raiz da sua loja.
2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox SF Express e clique em Install (o botão verde +).
3. Clique em Edit (o botão com lápis) para abrir a página de configurações.
4. Insira sua chave de licença VibeFox em License key, no bloco de licença no topo da página Edit, e clique em Activate (veja Chave de licença).
5. Preencha a tabela de preços e/ou o custo de contingência.
6. Para preços em tempo real na China continental, informe o código do cliente e o checkword, a província e a cidade de origem e, se a moeda da sua loja não for o 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.
7. Ative Enable SF Express e clique em Save.
OpenCart 4
1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_sf_express.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. Encontre VibeFox SF Express, clique em Install (o botão verde +) e depois em Edit (o botão com 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 seus campos são iguais nas duas versões.
Após a instalação, o método fica desativado até que você ative Enable SF Express e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da SF 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 SF Express > Edit. As seções ficam listadas à esquerda. Elas se aplicam a todas as geo zones. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento também limpa os preços da SF Express em cache. Somente administradores com a permissão de modificação para esta extensão podem salvar as configurações.
Ao salvar, a extensão verifica os valores. Um título de método vazio, com mais de 64 caracteres ou contendo < > ; = # { }, um valor que não seja número, um valor ou peso negativo, uma taxa de conversão de moeda igual a 0, um Min weight (kg) acima de Max weight (kg), um preço errado na tabela de preços ou uma ordem de exibição que não seja um número inteiro são recusados com uma mensagem, e nada é salvo até que você corrija. Os avisos acima das configurações informam quando os preços em tempo real estão configurados só em parte (as configurações faltantes são listadas), quando a taxa de conversão de moeda está faltando, quando a loja não tem zonas da China, ou quando a loja não tem uma classe de peso em kg ou uma classe de comprimento em cm e a unidade padrão dela não é conhecida pela extensão.
Geral
Enable SF Express: mostra ou oculta a SF Express na finalização de compra. Padrão: desativado.
Method title: o nome do método exibido no carrinho e na finalização de compra. Padrão: SF Express. Obrigatório, no máximo 64 caracteres.
Tax class: a classe de imposto do custo de envio, ou No tax. Com uma classe de imposto, o imposto de envio da sua loja é somado ao custo. Escolha No tax se o preço da SF Express já inclui tudo o que você quer cobrar.
Sort order: a posição da SF Express entre os métodos de envio na finalização de compra. Um número inteiro.
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. Esvaziá-lo também apaga o checkword salvo, para que você possa remover as credenciais.
Checkword: o checkword (校验码) do mesmo ambiente. Ele é usado somente para assinar as requisições e nunca é enviado nem registrado. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.
Sandbox: usa o sandbox da FengQiao (sfapi-sbox.sf-express.com) para testes com credenciais de sandbox. Os preços de 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, por exemplo Guangdong / 广东. A primeira opção usa a região da sua loja (System > Settings > Store > Local) quando a loja está na China. Ela então mostra Same as the store region com o nome da província; caso contrário, — Select —.
Sender city: o nome padrão em chinês da cidade, por exemplo 深圳市. Obrigatório para os preços em tempo real: o endereço da loja no OpenCart é texto livre, então a cidade nunca é obtida dele.
Currency conversion rate: os preços da SF Express estão em CNY (yuan). Se a moeda padrão da sua loja não for o CNY, informe quantas unidades da sua moeda vale um CNY (1 CNY = ? unidades), por exemplo 0.13. Sem essa taxa, os preços em tempo real não são usados. Se a moeda da loja for o CNY, o campo informa que ela não é necessária e 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 quantas das 32 províncias, regiões autônomas e municípios da SF Express são zonas da China no OpenCart e quais estão faltando. Endereços em uma província que falta recebem o preço da tabela. Clique em Add Chinese provinces para adicionar somente as que faltam como zonas da China (código ISO, um nome como "Tibet / 西藏"). As zonas existentes não são alteradas. Nada muda sem esse clique. As zonas adicionadas assim permanecem na loja após a desinstalação.
Tabela de preços e contingência (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; preços 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 botão de remover para excluir uma. A linha * All other countries se aplica a todos os países que não têm linha própria. Um preço de faixa de peso maior que 0 substitui o preço base para os pacotes dessa faixa: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 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 de contingência é usado. "9.99" e "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 o método nesse caso.
Table / fallback price is: como os preços de tabela e de contingência 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 (produtos que precisam de envio, após o cupom, antes dos 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 consulta de preço, então a partir deste valor o método é oferecido gratuitamente para todos os destinos em que está disponível, mesmo um país sem linha na tabela ou sem Fallback cost.
Minimum subtotal: exibe o método somente quando o subtotal do carrinho atinge este valor. Deixe vazio para exibi-lo sempre.
Min weight (kg): o peso mínimo do carrinho em kg. Os pesos dos produtos são convertidos a partir da classe de peso deles. 0 significa sem limite.
Max weight (kg): o peso máximo do carrinho em kg. Padrão: 50. 0 ou vazio significa sem limite.
Geo zone: oferece a SF Express somente para endereços desta geo zone. All zones (padrão) significa sem limite. As geo zones são gerenciadas em System > Localisation > Geo Zones. Não é verificada quando Ignore shipping zones está ativado.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece a SF Express para os países abaixo, independentemente da geo zone. Quando desativado, a geo zone decide e a lista de países não é usada.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países ativos. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de preço em storage/logs/vfd_sfex_debug.log.php. O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Checkword ou endereços de clientes não são gravados. Quando o arquivo chega a 5 MB, ele é movido para vfd_sfex_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão apaga as configurações e o log. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. Os preços em cache são sempre apagados.
Importação / Exportação
Export: clique em Download JSON para salvar as configurações em um arquivo JSON, sem o checkword.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. Os valores são verificados como em um salvamento normal. O checkword 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 da SF Express. Se uma Geo zone estiver definida e o endereço estiver fora dela, a SF Express não é oferecida (a menos que Ignore shipping zones esteja ativado). Somente produtos com Requires Shipping definido como Yes contam: os demais não somam peso e não entram no subtotal. O subtotal é o preço desses produtos 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. A extensão então verifica 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 requisição é enviada à SF Express.
Para um endereço de entrega na China continental com código do cliente e checkword definidos, a extensão envia à SF Express a sua província e cidade de origem, a província e a cidade do cliente, o peso do carrinho (pelo menos 0,1 kg) e o volume do carrinho (dos produtos com as três dimensões). A requisição é assinada com o seu checkword. A SF Express retorna os preços em CNY; a extensão converte o escolhido para a moeda padrão da sua loja e o arredonda para as casas decimais. O preço é então exibido na moeda do cliente, com o imposto da Tax class selecionada.
A SF Express reconhece os endereços pelos nomes padrão em chinês. A província do cliente vem da zona Region / State do endereço, identificada pelo nome. A zona "Hong Kong" não é uma província da China continental e recebe o preço da tabela. A cidade deve ser escrita em chinês, por exemplo 广州市. Para Pequim, Xangai, Tianjin e Chongqing, a cidade é preenchida automaticamente. Uma cidade escrita em letras latinas, como "Guangzhou", recebe o preço da tabela.
Cada preço 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 10 minutos, para que a finalização de compra não aguarde a 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, o método fica oculto. O cliente nunca vê um erro. O erro é gravado no log.
A extensão calcula somente preços. Ela não cria guias de remessa ou etiquetas, não cria pedidos na SF Express, não agenda coletas e 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 atendimento ou um armário da SF. A SF Express é usada como entrega porta a porta. Os preços em tempo real existem somente para endereços de entrega na China continental. A extensão foi desenvolvida 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.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de finalização de compra e escolhe a SF Express na janela Shipping method options, onde o título do método é exibido com o preço. 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 VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox SF Express é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox SF 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 ficam a linha Product: opencart-shipping-sf-express e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente 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 com 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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o método de envio da SF Express não é mostrado aos clientes na finalização de compra, e nenhum preço é calculado. Um usuário administrador conectado ao admin 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 do administrador, então sem uma chave ativa o método fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. 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 precisam de renovação. O status é verificado automaticamente quando você abre o Dashboard ou a página Edit do admin: 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 a extensão 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á ativado. Verifique Geo zone 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. Verifique se os produtos têm Requires Shipping definido como Yes.
O preço vem da tabela, e 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 origem, de um endereço de entrega na China continental com província e nome de cidade em 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 da extensão, depois ative o Debug log, recarregue a finalização de compra e veja o campo Log para descobrir o motivo. Uma requisição com falha é tentada novamente após 10 minutos.
O log mostra um erro de assinatura: o checkword está errado ou pertence ao outro ambiente. Verifique a configuração Sandbox. Se a SF Express disser que a API não é permitida, adicione a API de consulta de preços ao seu aplicativo FengQiao.
Endereços no Tibete recebem o preço da tabela: clique em Add Chinese provinces na seção de API da página da extensão.
Hong Kong: funciona com a tabela de preços e o custo de contingência. A consulta de preços da FengQiao é para endereços da China continental.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa os preços da SF Express em cache.
A página diz "Warning: You do not have permission to modify VibeFox SF Express!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_sf_express (OpenCart 3) ou extension/vfd_sf_express/shipping/vfd_sf_express (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: os eventos do OpenCart vfd_sf_express/quote_request e vfd_sf_express/api_url permitem que outra extensão altere a requisição de preço (por exemplo, para outro código de produto) e a URL do gateway.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox SF Express. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable SF Express, Sort order, Tax class e Geo zone. Os preços em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as demais configurações e o log também são apagados. Se estiver desativado, eles são mantidos e voltam a ser usados quando você reinstalar a extensão. As zonas da China adicionadas com Add Chinese provinces permanecem. 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 após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox SF Express na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho da lixeira) para remover o pacote enviado.
SF Express é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela SF Express.