VibeFox J&T Express for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

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

PHP: 8.0 ou superior.

Acesso à API da J&T Express Malásia (somente para cotações em tempo real): as cotações em tempo real existem apenas para a J&T Express Malásia, para endereços de entrega na Malásia. Você precisa de quatro valores. Solicite uma conta VIP da J&T no site da J&T Express Malásia (a página de configurações tem um link): a J&T fornece o código de cliente VIP e a chave de API VIP. A conta de API e a chave privada para assinar as requisições são emitidas pela J&T para a integração por API. Peça-as ao seu gerente de conta da J&T. A J&T Filipinas, a Indonésia e os outros países não têm API pública de cotação, então use a tabela de preços para eles. Se você usa apenas a tabela de preços e o custo de contingência, não precisa de acesso à API da J&T.

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

Instalação

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

2. Clique em Activate.

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

4. Informe 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 de contingência. Para as cotações em tempo real da Malásia, informe também as credenciais de API da J&T, o CEP do remetente e, se a moeda da sua loja não for MYR, a taxa de conversão (veja Configuração).

6. Adicione VibeFox J&T 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 J&T 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 o cliente vê para esta zona. Deixe em branco para usar o Method title global.

Sempre que você salvar as configurações, as cotações da J&T em cache são apagadas. Se as cotações em tempo real estiverem configuradas apenas em parte, um aviso no topo da página lista as configurações que faltam ou informa que a taxa de conversão de moeda não foi definida.

Geral

Enable/Disable: liga ou desliga o método em todas as zonas de uma vez. Padrão: on.

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: J&T Express.

Tax status: Taxable adiciona o imposto de envio da sua loja ao custo, None não adiciona. Escolha None se o preço da J&T já incluir tudo o que você quer cobrar.

API da J&T Express Malásia (cotações em tempo real) (opcional, para endereços de entrega na Malásia; as quatro credenciais são obrigatórias)

VIP customer code: o seu código de cliente VIP da J&T Express.

VIP API key: a chave de API (senha) que a J&T Express entregou junto com o código VIP. Ela nunca é registrada em log.

API account: o nome da sua conta de API da J&T Express.

API private key: a chave privada da conta de API. Ela é usada somente para assinar as requisições (SHA-256). Nunca é enviada à J&T nem registrada em log.

Sender postcode: o CEP malaio de onde os pacotes são enviados. Deixe em branco para usar o CEP da loja definido em WooCommerce > Settings > General, quando a loja estiver na Malásia. Os espaços são removidos ao salvar.

Currency conversion rate: as cotações da J&T Express Malásia são em MYR. Se a moeda da sua loja não for MYR, informe quantas unidades da sua moeda equivalem a um MYR (1 MYR = X). Sem esse valor, as cotações em tempo real não são usadas, e a tabela de preços ou o custo de contingência são usados no lugar. Se a moeda da loja for MYR, deixe em branco: as cotações são usadas como estão. Tanto o ponto quanto a vírgula são aceitos como separador decimal.

Tabela de preços e contingência (usada para países diferentes da Malásia, quando as cotações em tempo real não estão configuradas ou quando a J&T não retorna cotação; preços na moeda da sua loja)

Country prices: uma tabela com uma linha por país. Clique em Add country para adicionar uma linha e no X para remover. Escolha * Any other country para todos os países sem linha própria. Cada linha tem um Base price e cinco faixas de peso: 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 de faixa maior que 0 substitui o preço base para carrinhos nessa faixa. Uma faixa com 0 usa o preço base. Um preço base de 0 significa frete grátis, e um preço base vazio é salvo como 0. Países sem linha (quando não há linha *) não recebem preço de tabela.

Fallback cost: o preço usado quando nem a J&T nem a tabela fornecem um preço. Deixe em branco para ocultar o método nesse caso.

Table / fallback price is: Per order cobra o preço uma única vez. Per item (multiplied by the number of items) multiplica o preço pelo número de itens no carrinho. As cotações em tempo real da J&T são sempre para o pedido inteiro.

Condições

Free shipping from: o subtotal do carrinho (após descontos e antes dos impostos) a partir do qual o frete é grátis. Deixe em branco se não houver frete grátis.

Minimum subtotal: exibe o método somente quando o subtotal do carrinho atinge este valor. Deixe em branco para exibi-lo sempre.

Min weight (kg): oculta o método quando o carrinho pesa menos. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. 0 significa sem limite.

Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 50. 0 significa sem limite.

Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de envio do WooCommerce.

Disponibilidade sem zonas de envio

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

Countries: os países de destino para esse modo. Deixe em branco 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 em WooCommerce > Status > Logs, origem vfd-jt-express. Erros da API da J&T são sempre registrados, mesmo com esta opção desativada. Nenhuma chave, senha ou CEP de cliente é gravado. Desative o log quando terminar.

Remove data on uninstall: quando ativado, excluir o plugin remove as suas configurações, os métodos das zonas e as cotações em cache. Desativar o plugin nunca exclui nada.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa 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 subtotal do carrinho atingir Free shipping from, o método é exibido com custo de 0, mas somente se o país tiver preço: uma linha em Country prices, um Fallback cost ou uma cotação da J&T em tempo real. A J&T só é consultada quando a tabela e o custo de contingência não fornecem preço.

Caso contrário, o custo é obtido da primeira fonte que fornecer um preço:

1. Cotação da J&T em tempo real: somente quando as quatro credenciais de API e um CEP de remetente estão preenchidos, o país de entrega é a Malásia, o cliente informou um CEP de 5 dígitos e, para lojas que não usam MYR, uma taxa de conversão está definida. O plugin envia à J&T os CEPs do remetente e do destinatário e o peso do carrinho (mínimo de 0,1 kg) para o serviço padrão EZ, um pacote, e converte o preço retornado em MYR para a moeda da sua loja.

2. Country prices: a linha do país de entrega, ou a linha *, com o preço da faixa de peso do carrinho.

3. Fallback cost.

Se nenhuma dessas fontes fornecer um preço, o método é ocultado. Per item se aplica apenas aos preços de tabela e de contingência.

Cada resposta da J&T fica em cache por 1 hora, para que o mesmo carrinho não dispare uma nova requisição. Uma requisição com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela J&T a cada atualização. O tempo limite de uma requisição é de 10 segundos. Se a J&T retornar um erro, um preço zero ou nenhuma resposta, o cliente não vê erro algum. Usa-se o preço da tabela ou o custo de contingência, e o motivo é gravado no log.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o HPOS (High-Performance Order Storage) do WooCommerce.

O plugin calcula apenas os custos de envio. Ele não gera conhecimentos de transporte, guias ou etiquetas, não agenda coletas, não cancela nem rastreia envios e não permite que o cliente escolha um ponto de retirada. Gere e rastreie os envios na sua conta da J&T normalmente. O plugin foi desenvolvido com base no formato de requisição do plugin oficial da J&T Express Malásia. Confirme os preços com a sua conta da J&T antes de entrar em 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 J&T 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 informar 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 único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta do vibefox.net.

Sem uma chave ativa, a J&T Express não aparece para os clientes na finalização de compra. Os gerentes da loja que estão logados ainda a veem, 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 J&T 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á ligado e o país está permitido). Confira os limites de peso, Minimum subtotal e Excluded shipping classes. Verifique se Country prices tem uma linha para o país ou uma linha *, ou se Fallback cost está preenchido. Ative o Debug log e veja WooCommerce > Status > Logs.

O preço vem da tabela, não da J&T: as cotações em tempo real precisam das quatro credenciais de API, de um CEP de remetente, de um endereço de entrega na Malásia com CEP de 5 dígitos e, para lojas que não usam MYR, da Currency conversion rate. Confira os avisos no topo da página de configurações. Se a J&T rejeitar a requisição ou não responder, o erro é registrado e o preço da tabela ou o custo de contingência é usado. A requisição com falha é repetida após 10 minutos.

Sem cotações em tempo real para as Filipinas ou a Indonésia: a J&T não oferece uma API pública de cotação para esses países. Use a tabela de preços e o custo de contingência para eles.

Um país recebe frete grátis por engano: a linha dele tem preço base de 0 (um preço base vazio é salvo como 0). Informe um preço base ou remova a linha.

As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as cotações da J&T em cache.

Hooks para desenvolvedores: o filtro vfd_jtex_quote_request altera o corpo da requisição de cotação (por exemplo, o tipo de serviço), vfd_jtex_api_url altera o endpoint de cotação, e o filtro padrão woocommerce_shipping_vfd_jt_express_is_available controla a disponibilidade.

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 estiver inacessível, 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 da licença deste plugin são sempre removidos. As configurações, os métodos das zonas e as cotações em cache só são removidos se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas linhas de envio.

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