VibeFox Jadlog for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Contrato com a Jadlog (para preços em tempo real e pontos Pickup): os preços em tempo real e a lista de pontos Pickup vêm da API Embarcador da Jadlog. Sua franquia Jadlog emite o acesso após a assinatura do contrato. Você precisa do token da API Embarcador, do CNPJ (ou CPF) do remetente cadastrado no contrato, da conta corrente (conta corrente) e, se tiver, do número do contrato. Se usar apenas preços fixos, você não precisa de contrato com a Jadlog.
Chave de licença VibeFox: adquirida 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, depois, encontre VibeFox Jadlog na lista de módulos e clique em Configure.
3. Insira 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. Cole o token da API, informe o CNPJ, a conta corrente, o número do contrato e o CEP de origem, escolha o serviço Jadlog e, se a moeda padrão da sua loja não for BRL, informe a taxa de câmbio BRL. Adicione preços fixos ou um custo de contingência, se quiser (veja Configuração). Clique em Save.
5. Para oferecer também os pontos Jadlog Pickup, ative Enable Jadlog Pickup e clique em Save.
Na instalação, o módulo cria duas transportadoras: Jadlog (entrega em domicílio, ativada, texto de prazo de entrega Jadlog delivery to your address) e Jadlog Pickup (desativada, texto de prazo de entrega Pickup at a Jadlog Pickup point). Ambas estão vinculadas à zona do Brasil 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 Jadlog > Configure. Elas se aplicam às duas transportadoras Jadlog. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa os preços da Jadlog e as listas de pontos Pickup em cache.
No topo da página, o módulo mostra avisos de configuração incompleta: sem token de API (somente preços fixos são usados, e os pontos Pickup não podem ser listados), sem token de API e sem preços fixos (o método nunca é exibido), sem CNPJ ou conta corrente, sem CEP de origem, sem taxa de câmbio BRL para uma loja que não vende em BRL, uma unidade de peso ou de dimensão da loja que o módulo não reconhece (nesse caso os pesos são considerados em kg e as dimensões em cm; defina as unidades em International > Localization, Local units), ou uma transportadora Jadlog que foi excluída. Ao salvar, valores incorretos são informados: um CEP sem 8 dígitos, um CNPJ sem 14 dígitos (ou 11 para um CPF), um número inválido, um peso mínimo acima do peso máximo (ambos os pesos mantêm os valores salvos), um país desconhecido ou um preço inválido na tabela de preços.
General
Enable/Disable: ativa ou desativa a entrega em domicílio pela Jadlog. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora de entrega em domicílio exibido no carrinho e na finalização de compra. Padrão: Jadlog. Obrigatório.
Tax status: None ou Taxable com uma das suas regras de imposto. É salvo nas duas transportadoras Jadlog. Os preços da Jadlog são preços finais da transportadora. Escolha None se o PrestaShop não deve somar imposto a eles.
Jadlog live prices
Os preços em tempo real são solicitados somente para endereços no Brasil com CEP completo de 8 dígitos.
API token: o token Embarcador fornecido pela Jadlog. Você pode colá-lo com ou sem a palavra "Bearer". Deixe em branco para usar somente preços fixos. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.
Remove the saved API token: marque a caixa e clique em Save para excluir o token salvo.
CNPJ: o CNPJ (14 dígitos) ou o CPF (11 dígitos) do remetente cadastrado no contrato com a Jadlog. Pontos, barras e traços são permitidos.
Current account (conta corrente): o número da sua conta corrente na Jadlog. Sem ele e sem o CNPJ, a Jadlog não consegue cotar e somente preços fixos são usados.
Contract number: o número do seu contrato com a Jadlog, se a sua franquia tiver fornecido um.
Origin CEP: o CEP de onde as encomendas são enviadas, com 8 dígitos. Ele é salvo no formato 00000-000. Deixe em branco para usar o CEP da loja em Shop Parameters > Contact > Stores, se o endereço da loja estiver no Brasil.
Jadlog service: o serviço (modalidade) do seu contrato para entrega em domicílio: .Package (3, padrão), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) ou Emergencial (14). A Jadlog Pickup (40) é a segunda transportadora.
Insurance type: Normal (N) (padrão) ou Own insurance policy (A - apolice), conforme acordado no seu contrato com a Jadlog.
Volumetric weight: a Jadlog cobra o maior entre o peso real e o peso cubado.
BRL exchange rate: a Jadlog cota em reais. Se a moeda padrão da sua loja for o BRL, este campo não é necessário. Caso contrário, informe quanto vale 1 BRL na moeda padrão da sua loja, por exemplo 0.16. O preço da Jadlog é multiplicado por essa taxa, e o valor declarado do pedido enviado à Jadlog é convertido de volta para BRL. Sem a taxa, os preços em tempo real não são usados e somente os preços fixos se aplicam. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Delivery time: exibe na finalização de compra o prazo de entrega devolvido pela Jadlog, abaixo da transportadora Jadlog e ao lado de cada ponto Pickup, por exemplo "Delivery time: 3 business days". Ativado por padrão. O prazo de entrega é sempre salvo com o pedido.
Jadlog Pickup
Uma segunda transportadora com o serviço Jadlog Pickup (40). Ela precisa do token da API. Sem pontos, a transportadora fica oculta.
Enable Jadlog Pickup: ativa ou desativa a transportadora Jadlog Pickup. É o mesmo interruptor do status dela em Shipping > Carriers. Desativada após a instalação.
Jadlog Pickup carrier name: o nome desta opção na finalização de compra. Padrão: Jadlog Pickup. Obrigatório.
Points to show: quantos pontos Pickup oferecer, de 1 a 10. Padrão: 5.
Fixed prices (usados quando não há token de API, para países que a Jadlog não atende e sempre que a Jadlog não retorna preço)
Price per country: uma tabela com as colunas Country, Price, XS, S, M, L e XL, na moeda padrão da sua loja. Clique em + Add country para adicionar uma linha e no ícone de lixeira para remover uma. A coluna de tamanho é escolhida pelo peso do carrinho: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Price é usado quando a coluna de tamanho está vazia. Preço 0 significa frete grátis para esse país. Use * Default (other countries) para todos os demais países. As linhas sem nenhum preço são removidas ao salvar.
Fallback cost: usado quando nem a Jadlog nem a tabela fornecem um preço. Deixe em branco para ocultar a transportadora nesse caso.
Fixed price applies: Per order cobra o preço uma vez. Per item (price x quantity) multiplica o preço pela quantidade de itens no carrinho. Isso se aplica somente aos preços fixos e ao custo de contingência. Os preços da Jadlog já cobrem o carrinho inteiro.
Conditions
Minimum weight (kg): oculta as transportadoras quando o carrinho pesa menos. 0 significa sem limite.
Maximum weight (kg): oculta as transportadoras quando o carrinho pesa mais. Padrão: 150. 0 significa sem limite.
Minimum order amount: exibe as transportadoras somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) atinge este valor. Deixe em branco para exibi-las sempre.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega é gratuita. Deixe em branco se não houver frete grátis.
Availability without shipping zones
Ignore shipping zones: oferece a Jadlog para os países listados abaixo, mesmo que suas transportadoras não estejam vinculadas à zona deles. Quando você ativa a opção, as duas transportadoras são vinculadas a todas as zonas ativas, e as zonas criadas depois também são vinculadas. Quando você a desativa de novo, as transportadoras voltam às zonas que tinham antes.
Countries: os países de destino para esse modo, fora das zonas próprias das transportadoras. Deixe em branco para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativado.
Advanced
Debug log: registra cada requisição e resposta da Jadlog em logs/vfd_jdlg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. O token, o CNPJ e a conta nunca são registrados, e o CEP do cliente é encurtado. Desative o log quando terminar.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo exclui todas as configurações da Jadlog e as suas transportadoras. Quando desativado, desinstalar apenas desativa as transportadoras. Os preços em cache são sempre excluídos. Os pedidos nunca são alterados.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço de cada transportadora Jadlog. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro as condições: peso do carrinho e valor mínimo do pedido e, com Ignore shipping zones, os países permitidos. Se o subtotal do carrinho atingir Free shipping from, a entrega é gratuita e nenhum pedido de preço é enviado à Jadlog.
Para um endereço de entrega no Brasil com CEP completo de 8 dígitos, o módulo envia à Jadlog o CEP de origem e de destino, o peso, o seu CNPJ, a conta corrente, o contrato, o serviço, o tipo de seguro e o valor declarado do pedido. O preço retornado é convertido para a moeda padrão da loja e exibido na moeda do carrinho do cliente. Carrinhos sem peso são cotados como 0,1 kg. Se não houver preço em tempo real (sem token, endereço fora do Brasil, CEP incompleto, sem taxa de câmbio BRL, erro da Jadlog), o módulo usa a tabela Price per country e, depois, o Fallback cost. Se nenhum dos dois fornecer um preço, a transportadora fica oculta para esse carrinho.
Cada preço 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. Se a Jadlog não responder, retornar erro de servidor ou rejeitar o token, a API não é chamada de novo por 10 minutos. O tempo limite da API é de 10 segundos. O cliente nunca vê um erro da API. O motivo é registrado no log.
Se você editar uma transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.
O módulo somente calcula preços e lista pontos Pickup. Ele não cria envios na Jadlog, não imprime etiquetas, não solicita coletas, não cancela envios e não rastreia encomendas. Não mostra um mapa dos pontos Pickup e não solicita cotações internacionais à Jadlog. Para outros países, use preços fixos.
Pontos Pickup
A transportadora Jadlog Pickup é oferecida somente para endereços no Brasil, e somente quando o token da API está salvo. Quando o cliente informa um CEP completo de 8 dígitos, o módulo pede à Jadlog os pontos Pickup ativos mais próximos e lista até Points to show pontos abaixo da transportadora, cada um com seu preço, por exemplo "nome do ponto — preço (3 business days) — endereço". Se a lista ainda não estiver em cache, ela é carregada quando o cliente seleciona a transportadora, para que a etapa de envio não espere pela Jadlog.
O preço de cada ponto é solicitado à Jadlog. Se a Jadlog não informar preço para um ponto, o preço fixo é usado, e um ponto sem nenhum preço fica de fora. As listas de pontos ficam em cache por 12 horas. O preço da transportadora é o preço do ponto escolhido. Antes de um ponto ser escolhido, é o preço do ponto mais próximo que tenha preço. Um ponto sem preço não oculta a transportadora enquanto outros pontos tiverem preço. Depois que o cliente escolhe um ponto, a etapa de envio é atualizada com o novo preço.
O ponto é obrigatório. Sem ponto, o cliente não consegue continuar e vê Please select a Jadlog Pickup point. O módulo verifica se o ponto está na lista da Jadlog para o CEP de entrega. Se não estiver, o cliente vê The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. Quando o CEP está incompleto, não há pontos próximos ou a Jadlog está indisponível, uma mensagem aparece abaixo da transportadora.
Sem token de API, sem CEP de 8 dígitos, quando a Jadlog está indisponível ou quando não há pontos ativos próximos, a transportadora Jadlog Pickup fica oculta. Um pedido sem ponto não poderia ser enviado.
Pedidos
Quando um pedido é feito com uma transportadora Jadlog, o módulo salva o serviço Jadlog e, quando a Jadlog o devolveu, o prazo de entrega em dias úteis. Para um pedido Jadlog Pickup, ele também salva o nome, o endereço e o ID do ponto Pickup.
A página do pedido no admin mostra um bloco Jadlog com Jadlog service, Delivery time e, para o Jadlog Pickup, Pickup point, Pickup point address e Pickup point ID. O cliente vê o ponto escolhido na página de confirmação do pedido e nos detalhes do pedido. O ponto é acrescentado ao nome da transportadora no e-mail de confirmação do pedido. O e-mail de novo pedido da loja (se você usar o módulo de alertas por e-mail) também traz o ID do ponto.
Você mesmo deve criar o envio no sistema da Jadlog. O pedido mostra o serviço e o ID do ponto Pickup de que você precisa para isso.
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 Jadlog é o primeiro bloco em Modules > Module Manager > VibeFox Jadlog > 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 ficam a linha Product: presta-shipping-jadlog 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 único 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, as transportadoras Jadlog não são exibidas aos clientes na finalização de compra e nenhuma tarifa é calculada. A loja virtual do PrestaShop não sabe que você está logado no back office, então as transportadoras também ficam ocultas 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. Os 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 automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, 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 Jadlog não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable (ou Enable Jadlog Pickup) está ativado. Em Shipping > Carriers, confira se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones. Verifique os avisos no topo da página do módulo, os limites de peso e o Minimum order amount. Se o cliente ainda não informou um CEP completo de 8 dígitos, só é possível usar preços fixos, então adicione uma linha em Price per country ou um Fallback cost. Também é possível limitar produtos a determinadas transportadoras na página do produto.
Somente preços fixos são exibidos: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Ele mostra o motivo: sem CNPJ ou conta corrente, sem CEP de origem, CEP de destino incompleto, sem taxa de câmbio BRL ou a mensagem de erro da Jadlog.
HTTP 401 ou 403 no log: a Jadlog rejeitou o token da API. Confirme-o com a sua franquia Jadlog. A API fica pausada por 10 minutos após esse erro. Salvar as configurações cancela a pausa, então você pode tentar de novo imediatamente.
Os pontos Pickup não aparecem: a transportadora Jadlog Pickup precisa de Enable Jadlog Pickup, do token da API e de um CEP completo de 8 dígitos no Brasil. Se a Jadlog não tiver pontos ativos perto do CEP, a transportadora fica oculta. Verifique o log para ver o motivo.
Os preços aparecem em reais em vez da minha moeda: informe a BRL exchange rate (quanto vale 1 BRL na moeda padrão da sua loja).
Os preços parecem baixos ou altos demais: preencha os pesos e as dimensões dos produtos. Carrinhos sem peso são cotados como 0,1 kg, e o peso cubado precisa das dimensões.
Imposto está sendo somado aos preços da Jadlog: defina Tax status como None.
Os preços parecem desatualizados após uma mudança: clique em Save na página do módulo. Isso limpa os preços da Jadlog e as listas de pontos Pickup em cache.
A página informa que uma transportadora Jadlog não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Jadlog e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Os preços em cache e as listas de pontos Pickup são sempre excluídos. Se Remove data on uninstall estiver ativado, as duas transportadoras são excluídas (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, as transportadoras são apenas desativadas e todas as configurações são mantidas. Reinstalar o módulo devolve às transportadoras o status que tinham. O serviço Jadlog, o prazo de entrega e o ponto Pickup salvos com os pedidos são sempre mantidos.
A Jadlog é uma marca de seu respectivo titular. Este módulo não é afiliado à Jadlog nem endossado por ela.