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

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. São necessários quatro valores. Solicite uma conta VIP da J&T no site da J&T Express Malásia (a página do módulo 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, Indonésia e outros países não têm uma API pública de cotações, então use a tabela de preços para eles. Se você usa somente 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 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 encontre VibeFox J&T Express depois na lista de módulos e clique em Configure.

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

Na instalação, o módulo cria a transportadora J&T 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 ali: 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 J&T Express > Configure. Cada seção tem o próprio botão Save, que salva a página inteira. Cada salvamento também limpa as cotações da J&T em cache. Se as cotações em tempo real estiverem configuradas só 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 está ausente. Valores que não são um número igual ou maior que 0 são recusados com erro, assim como uma Currency conversion rate igual a 0 e um Min weight maior que Max weight. Se a unidade de peso da sua loja não for reconhecida, um aviso pede que você defina uma unidade padrão em International > Localization.

Geral

As configurações desta página valem para todas as zonas. Zonas, grupos de clientes e limites de tamanho da transportadora são definidos em Shipping > Carriers (ou use Ignore shipping zones abaixo).

Enable J&T 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 de compra. Padrão: J&T Express. Obrigatório.

Tax: a regra de imposto da transportadora, ou No tax. Uma regra de imposto acrescenta o imposto de envio da sua loja ao custo. Escolha No tax 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; todas as quatro credenciais são obrigatórias)

VIP customer code: seu código de cliente VIP da J&T Express. Limpá-lo também apaga a chave de API VIP salva.

VIP API key: a chave de API (senha) que a J&T Express entregou junto com o código VIP. Ela nunca é registrada no log. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-la.

API account: o nome da sua conta de API da J&T Express. Limpá-lo também apaga a chave privada salva.

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 no log. Como a chave de API VIP, ela não é exibida novamente após salvar.

Sender postcode: o CEP malaio de onde os pacotes são enviados. Deixe em branco para usar o CEP da loja em Shop Parameters > Contact > Stores, quando a loja estiver na Malásia. 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 padrão da sua loja não for MYR, informe quantas unidades da sua moeda vale um MYR (1 MYR = X). Sem isso, 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 aplicados no lugar. Se a sua moeda padrão for MYR, o campo informa isso e não é necessário: as cotações são usadas como estão. Tanto o ponto quanto a vírgula são aceitos como separador decimal. A taxa deve ser maior que 0.

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

Country prices: uma tabela com uma linha por país. Clique em Add country para adicionar uma linha e no ícone da lixeira 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. Se um país aparecer em duas linhas, a última é mantida. 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 a transportadora nesse caso. 0 significa frete grátis.

Table / fallback price is: Per order cobra o preço uma única vez. Per item (multiplied by the number of items) multiplica pelo número de itens do 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 (produtos que precisam de envio, após descontos, antes dos impostos) a partir do qual o frete é grátis. Deixe em branco para não ter frete grátis.

Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho atinge este valor. Deixe em branco para exibi-la sempre.

Min weight: oculta a transportadora quando o carrinho pesa menos, em kg. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. 0 significa sem limite. Não pode ser maior que Max weight.

Max weight: oculta a transportadora quando o carrinho pesa mais, em kg. Padrão: 50. 0 significa sem limite.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece a transportadora para os países abaixo, mesmo que ela não esteja vinculada à zona deles. Quando ativado, a transportadora é vinculada a todas as zonas ativas, e também às zonas criadas depois. Quando desativado, a transportadora é oferecida somente nas próprias zonas em Shipping > Carriers. Ao desativar, a transportadora volta às zonas anteriores.

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 é usado somente quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de preço em logs/vfd_jtex_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. 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.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.

Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações do módulo, a transportadora, as cotações em cache e o log. Quando desativado, 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 J&T Express. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: país de entrega (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o subtotal do carrinho atingir Free shipping from, o preço é 0 e nenhuma requisição é enviada à J&T.

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

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

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

3. Custo de contingência.

Se nenhuma dessas fontes fornecer um preço, a transportadora fica oculta para aquele carrinho. Per item se aplica somente aos preços de tabela e de contingência. O preço é calculado na moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente.

Cada resposta da J&T fica em cache por 1 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 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. O preço da tabela ou de contingência é usado, e 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 segue a nova versão automaticamente.

O módulo calcula somente 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 os clientes escolham um ponto de retirada. Crie e rastreie os envios na sua conta da J&T normalmente. O módulo 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 módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox J&T Express é o primeiro bloco em Modules > Module Manager > VibeFox J&T 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 ficam a linha Product: presta-shipping-jt-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 que o endereço da loja for alterado, 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 vibefox.net.

Sem uma chave ativa, a transportadora J&T Express não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: você pode configurar o módulo antes de comprar uma chave, mas não pode 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 J&T Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable J&T Express está ligado. Em Shipping > Carriers, verifique 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 é permitido). Confira os limites de peso e Minimum subtotal. Verifique se Country prices tem uma linha para o país ou uma linha *, ou se Fallback cost está definido. Produtos também podem ser limitados a certas transportadoras na página do produto. Ative o Debug log e veja o campo Log na página do módulo.

O preço vem da tabela, não da J&T: as cotações em tempo real precisam das quatro credenciais da API, de um CEP do 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. Verifique os avisos no topo da página do módulo. Se a J&T rejeitar a requisição ou não responder, o erro é registrado e o preço da tabela ou 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ções para esses países. Use a tabela de preços e o custo de contingência nesses casos.

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

As tarifas parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa as cotações da J&T em cache.

A página informa que a transportadora J&T 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.

Hooks para desenvolvedores: o hook actionVfdJtexQuoteRequest altera o corpo da requisição de cotação (por exemplo, o tipo de serviço), e actionVfdJtexApiUrl altera o endpoint de cotação.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox J&T Express e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As cotações em cache são sempre removidas. Se Remove data on uninstall estiver ligado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desligado, a transportadora é apenas desativada e todas as configurações são mantidas. Reinstalar o módulo devolve à transportadora salva o status anterior.

J&T Express é uma marca comercial de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela J&T Express.