VibeFox J&T Express for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 ou superior (testado na 4.1.0.3).

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 da extensão 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 solicitaçõ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 nas Filipinas, na Indonésia e em outros países não tem uma API pública de cotações, então use a tabela de preços para eles. Se você usar 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 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_jt_express-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_jt_express.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma nas duas versões.

OpenCart 3

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_jt_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 deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox J&T Express e clique em Install (o botão verde +).

3. Clique em Edit (o botão do 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. Para as cotações em tempo real na Malásia, insira também as credenciais da API da J&T, o código postal 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). Ative Enable J&T Express e clique em Save.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_jt_express.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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 J&T Express, clique em Install (o botão verde +) e depois em Edit (o botão do lápis).

4. Insira a chave de licença e as configurações como nos passos 4 e 5 para o OpenCart 3. A página de configurações e os seus campos são os mesmos nas duas versões.

Após a instalação, o método fica desativado até você ativar Enable J&T Express e salvar. Se você instalar a extensão novamente após uma desinstalação, as configurações do J&T Express que você manteve serão usadas novamente.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox J&T Express > Edit. As seções ficam listadas à esquerda. Um botão Save na parte inferior salva a página inteira sem recarregá-la. Cada salvamento também limpa as cotações da J&T em cache. Se um valor estiver errado, nada é salvo e a página mostra o motivo: um título de método inválido, um valor que não é um número igual ou maior que 0, uma Currency conversion rate igual a 0, um Min weight (kg) maior que Max weight (kg) ou uma ordem de exibição que não é um número inteiro. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.

Os avisos acima das configurações (exibidos novamente após cada salvamento) indicam quando as cotações em tempo real estão configuradas apenas parcialmente: eles listam as configurações de API que faltam ou informam que a moeda da sua loja não é MYR e a taxa de conversão está ausente. Outro aviso aparece se a sua loja não tiver uma classe de peso com a unidade kg em System > Localisation > Weight Classes. Os pesos dos produtos são então convertidos pelo nome da unidade (kg, g, lb, oz), e outras unidades são lidas como kg.

Geral

O método é oferecido para a zona geográfica selecionada ou para os países de Ignore shipping zones. As configurações desta página se aplicam a todas as zonas.

Enable J&T Express: mostra ou oculta o método na finalização de compra (o status desta extensão). Padrão: desativado.

Method title: o nome do método de envio mostrado ao cliente no carrinho e na finalização de compra. Padrão: J&T Express. Obrigatório, até 64 caracteres, sem os caracteres < > ; = # { }.

Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Uma classe de imposto adiciona o imposto de envio sobre o custo. Escolha No tax se o preço da J&T já incluir tudo o que você quer cobrar.

Sort order: a posição do método entre os métodos de envio na finalização de compra. Um número inteiro.

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)

A cotação é solicitada à J&T Express Malásia para cada código postal malaio e fica em cache por uma hora. Sem as credenciais, e para outros países, são usadas a tabela de preços e o custo de contingência.

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

VIP API key: a chave de API (senha) que a J&T Express forneceu junto com o código VIP. Ela nunca é registrada no log. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo. Para removê-la, limpe VIP customer code e salve.

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

API private key: a chave privada da conta de API. Ela é usada apenas para assinar as solicitações (SHA-256). Nunca é enviada à J&T nem registrada no log. Assim como a chave de API VIP, não é mostrada novamente após salvar. Para removê-la, limpe API account e salve.

Sender postcode: o código postal malaio de onde os pacotes são enviados, por exemplo 50000. Obrigatório para as cotações em tempo real: o endereço da loja no OpenCart é texto livre, então o código postal nunca é tirado dele.

Currency conversion rate: as cotações da J&T Express Malásia estã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), por exemplo 0.20. 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 aplicados. 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. A taxa deve ser maior que 0.

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 fornece cotação; preços na moeda padrão da sua loja, sem impostos)

Country prices: uma tabela com uma linha por país. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. 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 da 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. 0 significa frete grátis.

Table / fallback price is: Per order (padrão) cobra o preço uma vez. Per item (multiplied by the number of items) o multiplica pelo número de itens no carrinho. As cotações em tempo real da J&T sempre valem 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 em branco para não ter frete grátis.

Minimum subtotal: mostrar o método somente quando o subtotal do carrinho atingir este valor. Deixe em branco para sempre mostrá-lo.

Min weight (kg): ocultar o método quando o carrinho pesar menos. Os pesos dos produtos são convertidos pela classe de peso. 0 significa sem limite (padrão). Não pode ser maior que Max weight (kg).

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

Geo zone: oferecer o método somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usada quando Ignore shipping zones está ativado.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferecer o método para os países abaixo, independentemente da zona geográfica. Padrão: desativado.

Countries: os países de destino para esse modo, escolhidos entre os países habilitados na sua loja. Deixe em branco para permitir todos os países. 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_jtex_debug.log.php (no OpenCart 4, em system/storage/logs/vfd_jtex_debug.log.php). O arquivo não pode ser lido pela web. Os erros da API da J&T são sempre registrados, mesmo com esta opção desativada. Chaves, senhas, o código de cliente e os códigos postais dos clientes nunca são gravados. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_jtex_debug.old.log.php e um novo log é iniciado.

Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações do J&T Express e o log. Quando desativado (padrão), elas são mantidas para uma reinstalação. As cotações em cache são sempre removidas.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API VIP e a chave privada não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. As chaves salvas são mantidas.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da J&T Express. Se houver uma Geo zone definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os outros não adicionam peso e não entram no subtotal. A extensão então verifica as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vales-presente, pontos de recompensa e crédito da loja não são considerados. Se o subtotal atingir Free shipping from, o preço é 0 e nenhuma solicitaçã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 código postal do remetente estão definidos, o país de entrega é a Malásia, o cliente informou um código postal de 5 dígitos e, para lojas cuja moeda padrão não é MYR, há uma taxa de conversão definida. A extensão envia à J&T os códigos postais 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 em MYR retornado 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, o método é ocultado para aquele carrinho. Per item se aplica somente aos preços da tabela e de contingência. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

Cada resposta da J&T fica em cache por 1 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 J&T a cada atualização. O tempo limite da solicitação é de 10 segundos. Se a J&T retornar um erro, um preço zero ou nenhuma resposta, o cliente não vê nenhum erro. O preço da tabela ou de contingência é usado, e o motivo é gravado no log.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe J&T Express na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

A extensão calcula apenas os custos de envio. Ela não cria 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. Ela não adiciona nada aos pedidos: o pedido mostra o título do método e o custo de envio como qualquer outro método do OpenCart. Crie e rastreie os envios na sua conta da J&T como de costume. A extensão foi desenvolvida com base no formato de solicitação da integração 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

A extensão 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 Extensions > Extensions > Shipping > VibeFox J&T Express > Edit, acima das configurações. Insira a chave em License key e clique em Activate. Depois, 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 estão a linha Product: opencart-shipping-jt-express e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 de alterar o endereço da loja, ou após 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 na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio J&T Express não é mostrado aos clientes na finalização de compra, e nenhuma tarifa é calculada. Um usuário administrador conectado ao painel administrativo 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 no painel administrativo, 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 painel administrativo. 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 novamente de forma automática ao abrir o Dashboard do painel administrativo ou a página Edit: 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. Ao desinstalar a extensão, a chave de licença e o status da licença são sempre removidos.

Solução de problemas

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á ativado. Verifique a Geo zone (ou se Ignore shipping zones está ativado e o país está em Countries), os limites de peso e o Minimum subtotal. Confirme se Country prices tem uma linha para o país ou uma linha *, ou se Fallback cost está definido. Confirme se os produtos têm Requires Shipping definido como Yes. Ative o Debug log e veja o campo Log na página da extensão.

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 código postal do remetente, de um endereço de entrega na Malásia com código postal de 5 dígitos e, para lojas que não usam MYR, da Currency conversion rate. Verifique os avisos no topo da página da extensão. Se a J&T rejeitar a solicitação ou não responder, o erro é registrado e o preço da tabela ou de contingência é usado. A solicitação com falha é repetida após 10 minutos.

Não há 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 ali a tabela de preços e o custo de contingência.

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 o Free shipping from.

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

A página diz "Warning: You do not have permission to modify VibeFox J&T Express!": o grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_jt_express (OpenCart 3) ou extension/vfd_jt_express/shipping/vfd_jt_express (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: outras extensões podem alterar o corpo da solicitação de cotação (por exemplo, o tipo de serviço) com o evento do OpenCart vfd_jt_express/quote_request, e o endereço do endpoint de cotação com vfd_jt_express/api_url.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox J&T Express. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable J&T Express, Sort order, Tax class e Geo zone. As cotações em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações do J&T Express e o log de depuração também são excluídos. Se estiver desativado, as demais configurações são mantidas e usadas novamente ao reinstalar a extensão. 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 e clique em Uninstall (o botão laranja −) ao lado de VibeFox J&T Express na lista de extensões instaladas, depois em Delete (o botão vermelho da lixeira) para remover o pacote enviado.

J&T Express é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela J&T Express.