VibeFox Jadlog for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 ou superior (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Contrato com a Jadlog (para preços em tempo real e pontos de retirada): os preços em tempo real e a lista de pontos de retirada vêm da API Embarcador da Jadlog. A sua franquia Jadlog emite o acesso depois que o contrato é assinado. 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 você usa apenas preços fixos, não precisa de contrato com a Jadlog.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_jadlog-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_jadlog.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_jadlog-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ê também 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 Jadlog e clique em Install (o botão verde +).
3. Clique em Edit (o botão com lápis) para abrir a página de configurações.
4. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).
5. 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 reserva, se quiser (veja Configuração).
6. Ative Enable Jadlog home delivery, Enable Jadlog Pickup ou ambas, e clique em Save.
OpenCart 4
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_jadlog.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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 Jadlog, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).
4. Insira a chave de licença e as configurações como nas etapas 4 a 6 do OpenCart 3. A página de configurações e os campos dela são iguais nas duas versões.
Após a instalação, as duas opções ficam desativadas até que você as ative e salve. Se você reinstalar a extensão depois de desinstalá-la, as configurações da Jadlog que você manteve serão usadas novamente.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Jadlog > Edit. Elas se aplicam às duas opções da Jadlog. As seções aparecem à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa os preços da Jadlog e as listas de pontos de retirada em cache. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.
No topo da página, a extensão mostra avisos de configuração incompleta: sem token de API (são usados somente preços fixos, e os pontos de retirada 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, e sem classe de peso "kg" ou classe de comprimento "cm" na loja (nesse caso, pesos e dimensões são convertidos pelo nome da unidade da classe; confira System > Localisation > Weight Classes e Length Classes).
Ao salvar, um título inválido de qualquer uma das duas opções (vazio, com mais de 64 caracteres ou com < > ; = # { }), um Sort order que não seja um número inteiro, ou uma classe de imposto ou zona geográfica inexistente interrompem o salvamento com um erro. Outros valores incorretos são salvos com uma observação acima das configurações: um número inválido ou menor que 0 não é salvo, um peso mínimo maior que o peso máximo mantém os dois pesos salvos, uma taxa de câmbio BRL que não seja um número positivo é apagada, um CEP sem 8 dígitos ou um CNPJ sem 14 dígitos (ou 11 para um CPF) é salvo como digitado, com um aviso, e na tabela de preços uma linha com país desconhecido é removida e um preço inválido fica vazio.
Geral
A Jadlog tem duas opções de entrega: Jadlog home delivery (esta seção) e Jadlog Pickup (uma seção própria). As configurações desta página valem para as duas.
Enable Jadlog home delivery: oferece a entrega Jadlog no endereço do cliente com o serviço escolhido abaixo. Padrão: off.
Method title: o nome da opção de entrega em domicílio mostrado ao cliente na finalização de compra. Padrão: Jadlog. Obrigatório, no máximo 64 caracteres.
Sort order: a posição da Jadlog entre os métodos de envio na finalização de compra. Um número inteiro.
Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Os preços da Jadlog são preços finais da transportadora. Escolha No tax se o OpenCart não deve acrescentar imposto a eles. Vale para as duas opções.
Preços em tempo real da Jadlog
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 exibe Saved - leave empty to keep it. Digite um novo valor somente para alterá-lo. Quando nenhum token estiver salvo, a página exibe No token saved.
Remove the saved API token: marque e clique em Save para apagar o token salvo.
CNPJ: o CNPJ (14 dígitos) ou CPF (11 dígitos) do remetente cadastrado no contrato da Jadlog, por exemplo 00.000.000/0000-00.
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 os 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, 8 dígitos (00000-000). Obrigatório para os preços em tempo real: o OpenCart não tem CEP da loja, então sem este campo somente os preços fixos são usados.
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). Jadlog Pickup (40) é a segunda opção.
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 valor entre o peso real e o peso cúbico.
BRL exchange rate: a Jadlog cota em reais brasileiros. Se a moeda padrão da sua loja for BRL, este campo não é necessário. Caso contrário, informe quanto vale 1 BRL na sua moeda padrão, 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.
Delivery time: exibe o prazo de entrega retornado pela Jadlog na finalização de compra, ao lado do título da entrega em domicílio (por exemplo "Jadlog (3 business days)") e ao lado de cada ponto de retirada. Ativado por padrão. O prazo de entrega é sempre salvo com o pedido.
Jadlog Pickup
Uma segunda opção de entrega com o serviço Jadlog Pickup (40). Ela exige o token da API. Sem pontos, a opção fica oculta.
Enable Jadlog Pickup: oferece entrega em um ponto de retirada Jadlog escolhido na finalização de compra. Padrão: off.
Jadlog Pickup title: o nome desta opção na finalização de compra. Padrão: Jadlog Pickup. Obrigatório, no máximo 64 caracteres.
Points to show: quantos pontos de retirada oferecer, de 1 a 10. Padrão: 5.
Preços fixos (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 um 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 botão × 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. Um preço 0 significa frete grátis para esse país. Use * Default (other countries) para todos os outros países.
Fallback cost: usado quando nem a Jadlog nem a tabela fornecem um preço. Deixe em branco para ocultar o método nesse caso.
Fixed price applies: Per order (padrão) cobra o preço uma vez. Per item (price x quantity) o multiplica pelo número de itens no carrinho. Isso se aplica somente aos preços fixos e ao custo de reserva. Os preços da Jadlog já cobrem o carrinho inteiro.
Condições
Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão).
Maximum weight (kg): oculta o método acima deste peso do carrinho. Padrão: 150. 0 significa sem limite.
Minimum order amount: exibe o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe em branco para exibi-lo sempre.
Free shipping from: o subtotal (após o cupom, antes dos impostos) a partir do qual a entrega é gratuita. Deixe em branco para não ter frete grátis.
Disponibilidade
Geo zone: ofereça a Jadlog somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. A zona geográfica não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore shipping zones: quando ativado, a Geo zone não é verificada e a Jadlog é oferecida para os países abaixo. Quando desativado (padrão), apenas a Geo zone se aplica.
Countries: os países de destino para esse modo. Deixe em branco para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra cada requisição e resposta da Jadlog em storage/logs/vfd_jdlg_debug.log.php (no OpenCart 4, system/storage/logs/vfd_jdlg_debug.log.php). O arquivo não pode ser lido pela web. Erros da API e pedidos Jadlog Pickup sem ponto são sempre registrados, mesmo quando esta opção está desativada. O token, o CNPJ e a conta nunca são registrados, e o CEP do cliente é abreviado. Desative o log quando terminar.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão apaga todas as configurações da Jadlog, o log e as escolhas de ponto das finalizações de compra que nunca viraram pedidos. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. Os preços em cache são sempre removidos. Os dados Jadlog dos pedidos nunca são apagados.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O token da API não é exportado.
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. O token da API salvo é mantido.
Como funciona na finalização de compra
Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço de cada opção da Jadlog: a entrega em domicílio e o Jadlog Pickup aparecem como duas escolhas dentro de um mesmo método Jadlog. Com Ignore shipping zones ativado, a Jadlog é oferecida somente quando o país é permitido (a zona geográfica não é verificada). Caso contrário, se uma Geo zone estiver definida e o endereço estiver fora dela, a Jadlog não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no valor do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. A extensão verifica o peso do carrinho e o valor mínimo do pedido. Se o subtotal atingir Free shipping from, a entrega é gratuita e nenhuma solicitação de preço é enviada à Jadlog.
Para um endereço de entrega no Brasil com CEP completo de 8 dígitos, a extensão 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. Os pesos dos produtos são convertidos da classe de peso do OpenCart para kg, e as dimensões da classe de comprimento para cm. Carrinhos sem peso são cotados como 0.1 kg. O preço retornado é convertido para a moeda padrão, arredondado conforme as casas decimais dela e exibido na moeda do cliente com o imposto da Tax class selecionada. Se não houver preço em tempo real (sem token, endereço fora do Brasil, CEP incompleto, sem taxa BRL, erro da Jadlog), a extensão usa a tabela Price per country e, depois, o Fallback cost. Se nenhum deles fornecer um preço, a opção 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 recusar o token, a API não é chamada novamente por 10 minutos. O tempo limite da API é de 10 segundos. O cliente nunca vê um erro da API. 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 uma opção da Jadlog na janela Shipping method options. Os preços são os mesmos do OpenCart 3.
A extensão calcula apenas os preços e lista apenas os pontos de retirada. Ela não cria envios Jadlog, não imprime etiquetas, não solicita coletas, não cancela envios nem rastreia encomendas. Não exibe um mapa dos pontos de retirada e não solicita cotações internacionais à Jadlog. Use preços fixos para os demais países.
Pontos de retirada
A opção Jadlog Pickup é oferecida somente para endereços no Brasil, e somente quando Enable Jadlog Pickup está ativado e o token da API está salvo. Quando o cliente informa um CEP completo de 8 dígitos, a extensão pede à Jadlog os pontos de retirada ativos mais próximos e lista até Points to show pontos sob a opção, cada um com o 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 em segundo plano quando o cliente seleciona Jadlog Pickup, para que a etapa de método de entrega não espere pela Jadlog.
O preço de cada ponto é solicitado à Jadlog. Se a Jadlog não fornecer preço para um ponto, o preço fixo é usado, e um ponto sem nenhum preço é deixado de fora. As listas de pontos ficam em cache por 12 horas. O preço da opção é o preço do ponto escolhido. Antes de um ponto ser escolhido, é o preço do ponto mais próximo que tenha preço. Depois que o cliente escolhe um ponto, o preço exibido ao lado de Jadlog Pickup é atualizado.
Um ponto é obrigatório. Quando o cliente clica em Continue na etapa de método de entrega sem um ponto, vê Please select a Jadlog Pickup point. A extensão verifica no servidor 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 é exibida sob a opção.
Sem token de API, quando a Jadlog está indisponível ou quando não há pontos ativos próximos, a opção Jadlog Pickup fica oculta. Um pedido sem ponto não poderia ser enviado.
No OpenCart 4, a lista de pontos de retirada aparece na janela Shipping method options, abaixo da opção Jadlog Pickup. Ela é carregada em segundo plano, primeiro a partir do cache e depois com os preços dos demais pontos da Jadlog. Depois que o cliente escolhe um ponto, o preço ao lado de Jadlog Pickup na janela é atualizado. O botão Continue da janela não avança sem um ponto válido, com as mesmas mensagens.
Pedidos
Quando um pedido é feito com uma opção da Jadlog, a extensão salva o serviço da Jadlog e, quando a Jadlog o retornou, o prazo de entrega em dias úteis. Para um pedido Jadlog Pickup, também salva o nome, o endereço e o ID do ponto de retirada. No OpenCart 4, para cada finalização de compra é mantido um único pedido, que é atualizado sempre que o cliente confirma novamente, e os dados da Jadlog desse pedido são atualizados junto com ele. Se o cliente trocar esse pedido por outro método de envio, os dados da Jadlog dele são removidos.
O ponto é adicionado ao método de envio do pedido após o título da opção, por exemplo Jadlog Pickup: seguido do nome e do endereço do ponto. Este texto aparece nas páginas de pedidos do admin e da conta do cliente, nos e-mails do pedido e na nota fiscal.
A página do pedido no admin (Sales > Orders) exibe um painel Jadlog com Jadlog service, Delivery time e, para Jadlog Pickup, Pickup point, Pickup point address e Pickup point ID. No OpenCart 4, o painel aparece acima da seção History.
Agende o envio no sistema da Jadlog por conta própria. O pedido mostra o serviço e o ID do ponto de retirada de que você precisa para isso.
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 Jadlog é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Jadlog > Edit, 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 de novo, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-jadlog 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 de modificação da extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 com uma data. Depois de mudar o endereço da loja, ou depois de 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 único domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, as opções de envio da Jadlog não são exibidas aos clientes na finalização de compra e nenhum frete é calculado. Um usuário administrador conectado ao admin no mesmo navegador ainda as vê na loja, marcadas com (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 do admin, então, sem uma chave ativa, as opções da Jadlog ficam ocultas para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. 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 de novo automaticamente quando você abre o Dashboard do admin ou a página Edit: uma vez por dia nos primeiros 14 dias após a inserção da chave, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão 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 Jadlog home delivery (ou Enable Jadlog Pickup) está ativado. Confira Geo zone ou ative Ignore shipping zones e confira Countries. Verifique os avisos no topo da página da extensão, os limites de peso, o Minimum order amount e se os produtos têm Requires Shipping definido como Yes. 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 de Price per country ou um Fallback cost.
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 da extensão. 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 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 de retirada não aparecem: a opção Jadlog Pickup exige Enable Jadlog Pickup, o token da API e um CEP completo de 8 dígitos no Brasil. Se a Jadlog não tiver pontos ativos perto do CEP, a opção fica oculta. Veja o log para saber 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 cúbico exige as dimensões.
Imposto sendo acrescentado aos preços da Jadlog: defina Tax class como No tax.
Os preços parecem desatualizados após uma alteração: clique em Save na página da extensão. Isso limpa os preços da Jadlog e as listas de pontos de retirada em cache.
A página diz "Warning: You do not have permission to modify VibeFox Jadlog!": o seu grupo de usuários administradores pode ter apenas permissão de visualização das configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_jadlog (OpenCart 3) ou extension/vfd_jadlog/shipping/vfd_jadlog (OpenCart 4) em System > Users > User Groups.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Jadlog. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine o status da extensão, Sort order, Tax class e Geo zone. Os preços em cache e as listas de pontos de retirada são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da Jadlog e o log também são apagados. Se estiver desativado, as demais configurações são mantidas e reutilizadas quando você reinstalar a extensão. O serviço da Jadlog, o prazo de entrega e o ponto de retirada salvos com os pedidos são sempre mantidos, e os pedidos existentes preservam 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 Jadlog na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para apagar o pacote enviado.
A Jadlog é uma marca de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Jadlog.