VibeFox Loggi for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a instalar em versões mais antigas do PHP.

Conta Loggi (apenas para preços em tempo real): o preço em tempo real usa a API GraphQL da Loggi com uma chave de API que a Loggi emite para contas empresariais. Peça ao seu gerente de conta da Loggi ou ao suporte de integrações da Loggi (integracoes@loggi.com); veja também a documentação da API da Loggi em docs.api.loggi.com. Você precisa de três valores: o e-mail da sua conta Loggi, a chave de API e o ID numérico da sua loja. Se sua conta Loggi tiver apenas credenciais para a nova API da plataforma REST da Loggi (client ID e secret), o preço em tempo real não está disponível e os preços fixos são usados. Se você usa apenas preços fixos, não precisa de conta Loggi.

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 upload terminar, clique em Configure, ou encontre VibeFox Loggi depois 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. Insira o e-mail da API Loggi, a chave de API, o Shop ID e o endereço de coleta e, se a moeda padrão da sua loja não for BRL, a taxa de câmbio BRL. Adicione preços fixos como rede de segurança (veja Configuração) e clique em Save.

5. Adicione o Brasil às zonas da transportadora Loggi em Shipping > Carriers, ou ative Ignore shipping zones e escolha os países.

Na instalação, o módulo cria a transportadora Loggi com o texto de prazo de entrega Courier delivery in Brazil. 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, logo 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 Loggi > Configure. Elas se aplicam a todas as zonas da transportadora. 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 Loggi em cache.

Avisos no topo da página mostram uma configuração incompleta: sem credenciais de API (só preços fixos são usados), sem credenciais de API e sem preços fixos (a transportadora nunca é exibida), sem endereço de coleta, sem taxa de câmbio BRL, ou uma unidade de peso ou dimensão da loja que o módulo não reconhece (ela é então contada como kg ou cm; defina as unidades em International > Localization). Se um valor for inválido, por exemplo um número negativo, a página mostra um erro e nada é salvo.

Geral

Enable Loggi: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Method title: o nome da transportadora mostrado ao cliente no carrinho e na finalização de compra. Padrão: Loggi. Obrigatório, máximo de 64 caracteres.

API Loggi (preço em tempo real) (deixe as credenciais vazias para usar apenas preços fixos)

API e-mail: o e-mail da sua conta Loggi. A chave de API pertence a ele. Deve ser um endereço de e-mail válido.

API key: sua chave de API da Loggi. Ela é enviada somente à Loggi e nunca é registrada. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it; clear the API e-mail to remove it. Digite um novo valor apenas para alterá-la. Se você alterar API e-mail, informe também a chave de API do novo e-mail, senão a página mostra um erro e nada é salvo. Para remover a chave salva, limpe API e-mail e salve.

Shop ID: o ID numérico (pk) da sua loja no painel da Loggi. Só um número positivo é aceito. Outro valor é rejeitado com erro.

Staging: usa o ambiente de staging da Loggi com credenciais de teste. Staging e produção têm contas e chaves diferentes. Padrão: desativado.

Pickup address: onde a Loggi coleta os pacotes, em uma linha: rua e número, bairro, cidade, estado e CEP, por exemplo Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Deixe vazio para usar o endereço da loja de Shop Parameters > Contact > Stores, se ele estiver no Brasil e tiver endereço e cidade. Sem endereço de coleta, a Loggi não consegue estimar e só os preços fixos são usados.

BRL exchange rate: os preços da Loggi são em reais. Se a moeda padrão da sua loja for BRL, este campo não é necessário e a página informa isso. Caso contrário, informe quanto vale 1 BRL na moeda da sua loja, por exemplo 0.16. Sem ele, os preços em tempo real não são usados. Só um número positivo é aceito. Tanto o ponto quanto a vírgula são aceitos como separador decimal.

Preços fixos (na moeda padrão da sua loja, sem impostos)

Os preços fixos são usados quando a API da Loggi não está configurada, para destinos fora do Brasil ou sem CEP completo, e sempre que a Loggi não retorna preço (API indisponível, chave rejeitada, endereço fora da área de cobertura).

Price table: uma linha por país de destino. Clique em Add country para adicionar uma linha e no ícone de lixeira para removê-la. Escolha * All other countries para todos os países sem linha própria. Cada linha tem um Base price e colunas de peso: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Uma coluna de peso vazia (ou 0) usa o preço base. Preço base 0 significa frete grátis. Tanto "9.99" quanto "9,99" são aceitos. Linhas vazias e uma segunda linha para o mesmo país são descartadas ao salvar.

Price for countries not in the table: usado quando não há preço em tempo real da Loggi e a tabela não tem linha para o país de destino (nem linha *). Deixe vazio para ocultar a transportadora nesse caso.

Fixed price applies: a forma como os preços fixos são calculados. Um preço em tempo real da Loggi já cobre o carrinho inteiro e nunca é multiplicado.

Condições

Minimum weight: oculta a transportadora quando o carrinho pesa menos, em kg. 0 significa sem limite.

Maximum weight: oculta a transportadora quando o carrinho pesa mais, em kg. Padrão: 30. 0 significa sem limite. Minimum weight não pode ser maior que Maximum weight.

Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (após descontos, sem impostos) atinge este valor. Deixe vazio para mostrar sempre.

Free shipping from: o subtotal do carrinho (após descontos, sem impostos) a partir do qual a entrega pela Loggi é grátis. Deixe vazio para não ter frete grátis.

Tax: a regra de imposto da transportadora, ou No tax. Escolha No tax se seus preços e o preço da Loggi já incluem impostos.

Para os limites de peso e as colunas de peso, um produto sem peso conta como 0 kg.

Disponibilidade sem zonas de entrega

Ignore shipping zones: oferece a Loggi para os países abaixo, independentemente da zona correspondente. Ao salvar com esta opção ativa, a transportadora é adicionada a todas as zonas, e às zonas criadas depois. Desativá-la remove essas zonas adicionadas, para que a transportadora volte a ter as próprias zonas.

Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países ativos da sua loja. Este campo é usado somente quando Ignore shipping zones está ativo.

Avançado

Debug log: grava os cálculos de preço e as requisições à Loggi em logs/vfd_lggi_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. A chave de API e os endereços dos clientes nunca são registrados.

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

Remove data on uninstall: quando ativa, desinstalar o módulo apaga as configurações da Loggi, a transportadora, os preços em cache e os logs. Quando desativada, tudo é mantido para uma reinstalação.

Como funciona na finalização de compra

Na etapa de frete, o PrestaShop pede ao módulo o preço da Loggi. Só 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: países permitidos (com Ignore shipping zones), peso do carrinho e valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Loggi.

Para um endereço no Brasil com CEP completo de 8 dígitos, o módulo monta pacotes da Loggi: cada item é girado para que seu lado menor seja a altura, e os itens são empilhados em um mesmo pacote enquanto ele couber em 55 × 55 × 55 cm e 20 kg. Produtos sem peso ou dimensões contam como 1 cm por lado, e cada pacote pesa pelo menos 100 g. A Loggi aceita 2 pacotes por estimativa, então carrinhos maiores são enviados em várias requisições e os totais são somados. O módulo envia à Loggi o seu Shop ID, o endereço de coleta, o endereço de entrega e os pacotes, e converte o total da Loggi de BRL para a moeda padrão da sua loja. O preço é então exibido na moeda do carrinho do cliente.

Cada preço da Loggi fica em cache por 1 hora por carrinho, endereço, conta e ambiente, para que o mesmo carrinho não dispare uma nova requisição. Uma estimativa com falha fica em cache por 10 minutos. Se a Loggi não puder ser acessada de forma alguma, as requisições são pausadas por 2 minutos, para que a finalização de compra não espere pela Loggi a cada atualização. O timeout da API é de 10 segundos.

Os preços fixos são usados no lugar quando a API não está configurada, o endereço está fora do Brasil ou ainda não tem CEP completo, falta a taxa de câmbio BRL, não há endereço de coleta, um produto é maior que um pacote da Loggi, o carrinho precisa de mais de 10 pacotes, ou a Loggi retorna erro, pacote rejeitado, endereço fora da cobertura ou total zero. Se também não houver preço fixo, a transportadora fica oculta. O cliente nunca vê um erro da API. O motivo é gravado no log de depuração.

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 apenas preços. Ele não cria pedidos ou envios na Loggi, não imprime etiquetas, não rastreia encomendas, não mostra o prazo de entrega na finalização de compra e não oferece pontos de coleta ou armários. Crie os envios no painel da Loggi. A Loggi entrega somente dentro do Brasil. Use os preços fixos para outros países.

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 Loggi é o primeiro bloco em Modules > Module Manager > VibeFox Loggi > 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-loggi 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 Loggi 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 Loggi não aparece na finalização de compra: verifique se a licença está ativa e se Enable Loggi 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á ativo e o país é permitido). Confira 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 ou a Loggi não retorna preço, a transportadora precisa de um preço fixo: uma linha para o país, uma linha * ou Price for countries not in the table. Produtos também podem ser limitados a certas transportadoras na página do produto.

Só aparecem preços fixos: veja o campo Log na página do módulo. Erros são sempre registrados. Ative o Debug log para cada etapa e recarregue a finalização de compra. Motivos comuns: e-mail, chave ou Shop ID da API ausentes, sem endereço de coleta, sem BRL exchange rate para uma moeda de loja diferente de BRL, sem CEP completo de 8 dígitos ainda, produto maior que 55 cm ou mais pesado que 20 kg, ou endereço fora da cobertura da Loggi.

HTTP 401 ou 403 no log: a Loggi rejeitou o e-mail ou a chave da API. Verifique com a Loggi e confira se Staging corresponde às credenciais: as chaves de staging e de produção são diferentes.

Minha loja vende em euros ou dólares: a Loggi responde em BRL. Informe o BRL exchange rate (quanto vale 1 BRL na moeda padrão da sua loja). Os preços fixos estão sempre na moeda padrão da sua loja.

Os preços não estão corretos: preencha o peso e as dimensões dos seus produtos. Sem eles, os produtos contam como 1 cm por lado e cada pacote como pelo menos 100 g.

Per item não multiplica o preço da Loggi: isso é intencional. Um preço em tempo real da Loggi cobre o carrinho inteiro. Per item se aplica somente aos preços fixos.

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 Loggi em cache.

A página diz que a transportadora Loggi 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 Loggi e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Os preços da Loggi em cache são sempre removidos. Se Remove data on uninstall estiver ativo, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, a transportadora salva recupera o status que tinha antes da desinstalação.

A Loggi é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Loggi.