VibeFox SF Express for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

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 ele 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 uma conta SF Express.

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

Instalação

1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_sf_express para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox SF Express, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Preencha a tabela de preços e/ou o custo alternativo.

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 (ou defina um endereço de loja na China) e, se a moeda da loja não for CNY, a taxa de conversão. Teste primeiro com Sandbox e credenciais de sandbox.

7. Adicione VibeFox SF Express a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox SF Express. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome que os clientes veem nesta zona. Deixe vazio para usar o Method title global.

Sempre que você salvar as configurações, os preços em cache da SF Express são apagados. Se os preços em tempo real estiverem configurados parcialmente, um aviso acima das configurações lista o que está faltando ou a taxa de conversão ausente.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.

Method title: o nome do método de envio exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: SF Express.

Tax status: Taxable acrescenta o imposto de envio da sua loja ao custo, None não acrescenta. Escolha None 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.

Checkword: o checkword (校验码) do mesmo ambiente. Ele é usado apenas para assinar as solicitações e nunca é enviado nem registrado.

Sandbox: use o sandbox da FengQiao para testar com credenciais de sandbox. Os preços do sandbox não são reais. Desative em uma loja em produção. Padrão: off.

SF Express product: de qual produto da SF Express 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 WooCommerce > Settings > General, 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 da sua loja não for CNY, informe quantas unidades da moeda da loja valem um CNY. Sem isso, os preços em tempo real não são usados. Se a moeda da 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.

Tabela de preços e custo alternativo (usados 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 da sua loja)

Country prices: uma tabela com um preço base por país. A linha * Any other country 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: ≤ 1 kg, ≤ 2 kg, ≤ 3 kg, ≤ 5 kg e > 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 esse país e o custo alternativo é usado.

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 da tabela e os alternativos 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 a partir do qual o frete é grátis. O frete grátis só é oferecido onde o método tem preço para o destino: um preço em tempo real, uma linha da tabela ou o Fallback cost. Deixe vazio para nunca oferecer frete grátis.

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 unidade de peso da sua loja. 0 significa sem limite.

Max weight (kg): o peso máximo do carrinho em kg. Padrão: 50. 0 significa sem limite.

Excluded shipping classes: oculta o método se o carrinho contiver produtos destas classes de envio do WooCommerce.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método para os países abaixo mesmo que ele não esteja adicionado a uma zona. Quando desativado, o método aparece apenas nas zonas de envio às quais foi adicionado.

Countries: os países de destino para este modo. Deixe vazio para usar todos os países para os quais você envia. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de preço no log do WooCommerce: WooCommerce > Status > Logs, origem vfd-sf-express. Erros da API são sempre registrados, mesmo com esta opção desativada. Nenhum checkword nem endereço de cliente é gravado.

Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações, seus métodos nas zonas de envio e os caches. Desativar o plugin nunca apaga nada.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede um preço ao plugin. O plugin verifica primeiro as condições: país de entrega, peso do carrinho, subtotal mínimo e classes de envio excluídas. Se o frete grátis se aplicar e a tabela de preços ou o Fallback cost tiverem um preço para o destino, o método é exibido com preço 0 e nenhuma solicitação é enviada à SF Express. Caso contrário, o plugin pede primeiro à SF Express um preço em tempo real e exibe o método como grátis somente se um preço for retornado.

Para um endereço de entrega na China continental, com código do cliente e checkword configurados, o plugin envia à SF Express a província e a cidade de origem, a província e a cidade do cliente, o peso do carrinho e o volume do carrinho (dos produtos com as três dimensões preenchidas). A solicitação é assinada com o seu checkword. A SF Express retorna os preços em CNY, e o plugin converte o escolhido para a moeda da sua loja.

A SF Express reconhece endereços pelos nomes chineses padrão. A província do cliente vem do campo de estado da finalização de compra. A cidade deve ser escrita em chinês, por exemplo 广州市. Para Pequim, Xangai, 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, para que o mesmo carrinho não gere 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, o método fica oculto. O cliente nunca vê um erro. O erro é gravado no log.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e de Finalização de compra. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS). Traduções em inglês e em chinês simplificado estão incluídas.

O plugin calcula apenas os preços. Ele não cria conhecimentos de transporte nem etiquetas, não cria pedidos na SF Express, não agenda coletas e não cancela nem rastreia envios. Crie e acompanhe os envios na sua conta da SF Express normalmente. Os clientes não podem escolher um ponto de serviço ou um 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 plugin foi desenvolvido com base na documentação da FengQiao e em respostas simuladas, por isso 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 plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox SF Express. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta do vibefox.net.

Sem uma chave ativa, a SF Express não é exibida aos clientes na finalização de compra. Os gerentes da loja que estiverem logados continuam vendo, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A SF Express não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativo e o país permitido). Verifique os limites de peso, Minimum subtotal e Excluded shipping classes. Confira se a tabela ou o Fallback cost têm um preço para o país.

O preço vem da tabela, não da SF Express: os preços em tempo real exigem código do cliente e checkword, província e cidade de origem, 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) a taxa de conversão. Abra WooCommerce > Status > Logs, origem vfd-sf-express, para ver o motivo. Uma solicitação com falha é repetida após 10 minutos.

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 serve apenas para endereços da China continental.

Os preços parecem desatualizados após uma mudança: salve a página de configurações. Isso limpa os preços em cache da SF Express.

Para desenvolvedores: o filtro vfd_sfex_quote_request altera a solicitação de preço, por exemplo para outro código de produto. vfd_sfex_api_url altera a URL do gateway.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta do vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. Configurações, métodos de zona e preços em cache só são removidos se Remove data on uninstall estiver ativado. Caso contrário, eles são mantidos para uma reinstalação posterior. Os pedidos existentes mantêm as suas linhas de envio.

SF Express é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela SF Express.