VibeFox Loggi for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Conta Loggi (somente 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 a 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 somente 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 WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_loggi para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Loggi, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Informe o e-mail da API da Loggi, a chave de API, o Shop ID e o endereço de coleta e, se a moeda 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).

6. Adicione VibeFox Loggi a uma zona de entrega para o Brasil em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações estão em uma só página: WooCommerce > Settings > Shipping > VibeFox Loggi. Elas valem para todas as zonas de entrega. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome que o cliente vê para esta zona. Deixe vazio para usar o Method title global.

Os avisos no topo da página indicam configuração incompleta: sem credenciais de API, sem endereço de coleta ou sem taxa de câmbio BRL. Sempre que você salva as configurações, os preços da Loggi em cache são apagados.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.

Method title: o nome do método de frete exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: Loggi.

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

API e-mail: o e-mail da sua conta Loggi. A chave de API pertence a ela.

API key: a sua chave de API da Loggi. Ela é enviada somente à Loggi e nunca é registrada em log.

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

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 WooCommerce > Settings > General se ele estiver no Brasil. 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 da sua loja for BRL, este campo não é necessário. 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. Tanto o ponto quanto a vírgula são aceitos como separador decimal.

Preços fixos (na moeda da sua loja)

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 recusada, 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 X para remover uma. 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 o método nesse caso.

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

Condições

Minimum weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.

Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite.

Minimum order amount: mostra o método somente quando o subtotal do carrinho (após descontos, antes de impostos) atinge este valor. Deixe vazio para sempre mostrar.

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

Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de entrega do WooCommerce.

Tax status: Taxable adiciona o imposto do WooCommerce ao custo do frete, None não adiciona. Escolha None se os seus preços e o preço da Loggi já incluem impostos.

Disponibilidade sem zonas de entrega

Ignore shipping zones: oferece a Loggi para os países abaixo, mesmo que o método não esteja adicionado a nenhuma zona de entrega.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais você envia. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: registra cada cálculo de frete e cada requisição à Loggi em WooCommerce > Status > Logs (origem vfd-loggi). 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.

Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações da Loggi e os métodos das zonas. Desativar o plugin nunca apaga as configurações.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma taxa de frete ao plugin. O plugin primeiro verifica as condições: país de entrega, peso do carrinho, valor mínimo do pedido e classes de entrega excluídas. Se o frete grátis se aplicar, o cliente vê o método sem custo e nenhuma requisição é enviada à Loggi.

Para um endereço no Brasil com CEP completo de 8 dígitos, o plugin monta os 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 plugin envia à Loggi o seu Shop ID, o endereço de coleta, o endereço de entrega e os pacotes, converte o total da Loggi de BRL para a moeda da sua loja e o exibe.

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 gere uma nova requisição. Uma estimativa com falha fica em cache por 10 minutos. Se a Loggi não puder ser acessada de modo algum, 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 tempo limite 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, a taxa de câmbio BRL está faltando, um produto é maior que um pacote da Loggi, o carrinho precisa de mais de 10 pacotes, ou a Loggi retorna erro, pacote recusado, endereço fora da cobertura ou total zero. Se também não houver preço fixo, o método fica oculto. O cliente nunca vê um erro da API. O motivo é gravado no log.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e de Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin calcula somente preços. Ele não cria pedidos nem 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 plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Loggi. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Loggi não é exibida aos clientes na finalização de compra. Gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A Loggi não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Confira os avisos no topo da página de configurações, os limites de peso, Minimum order amount e Excluded shipping classes. Se o cliente ainda não informou um CEP completo ou a Loggi não retorna preço, o método precisa de um preço fixo: uma linha para o país, uma linha * ou Price for countries not in the table.

Só são exibidos preços fixos: abra WooCommerce > Status > Logs, origem vfd-loggi. Erros são sempre registrados. Ative Debug log para ver cada etapa. 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, ainda sem CEP completo de 8 dígitos, um produto maior que 55 cm ou mais pesado que 20 kg, ou um endereço fora da cobertura da Loggi.

HTTP 401 ou 403 no log: a Loggi recusou o e-mail ou a chave da API. Confirme-os com a Loggi e verifique 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 a BRL exchange rate (quanto vale 1 BRL na moeda da sua loja). Os preços fixos estão sempre na moeda da sua loja.

Os preços não estão precisos: 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 a preços fixos.

Os preços parecem desatualizados após uma mudança: salve a página de configurações. Isso limpa os preços da Loggi em cache.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todas as configurações. Somente os preços da Loggi em cache são apagados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin, assim como os preços em cache, são sempre removidos. Configurações e métodos das zonas são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas linhas de frete.

A Loggi é uma marca de propriedade de seu respectivo titular. Este plugin não é afiliado à Loggi nem endossado por ela.