VibeFox Loggi for OpenCart — Ajuda

Requisitos

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

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. Solicite-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 API da nova 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 uma conta Loggi.

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 para o OpenCart 3 vfd_loggi-oc3-(version).ocmod.zip e o pacote para o OpenCart 4 vfd_loggi.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 painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_loggi-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 Loggi 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. Cole 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. 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 padrão da sua loja não for BRL, a taxa de câmbio para BRL. Adicione preços fixos como rede de segurança (veja Configuração), ative Enable Loggi e clique em Save.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_loggi.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 Loggi, 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 do OpenCart 3. A página de configurações e os seus campos são os mesmos nas duas versões.

Na instalação, a extensão cria uma pequena tabela para os preços da Loggi em cache. O método fica desativado até você ativar Enable Loggi e salvar. Se você instalar a extensão novamente após uma desinstalação, as configurações da Loggi que você manteve serão usadas novamente.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Loggi > Edit. As seções ficam listadas à esquerda. Elas se aplicam a todas as zonas geográficas. Um botão Save na parte inferior salva a página inteira sem recarregá-la. Cada salvamento também limpa os preços da Loggi em cache. Se um valor for inválido, por exemplo um número negativo, um e-mail inválido ou um Shop ID que não seja um número, a página mostra um erro e nada é salvo. 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) apontam uma configuração incompleta: nenhuma credencial de API (apenas preços fixos são usados), nenhuma credencial de API e nenhum preço fixo (o método nunca é mostrado), nenhum endereço de coleta ou nenhuma taxa de câmbio para BRL. Outro aviso aparece quando a loja não tem uma classe de peso com a unidade kg ou uma classe de comprimento com a unidade cm, e a unidade da classe padrão não é reconhecida. Os pesos dos produtos são então contados em kg e as dimensões em cm. Adicione as classes em System > Localisation > Weight Classes e Length Classes.

Geral

Enable Loggi: mostra ou oculta a Loggi na finalização de compra. 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: Loggi. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.

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

API da Loggi (preço em tempo real) (deixe as credenciais em branco 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. Limpá-lo também limpa a chave de API salva.

API key: a sua chave de API da Loggi. Ela é enviada somente à Loggi e nunca é registrada no log. 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 somente para alterá-lo. Se você alterar API e-mail, informe também a chave de API do novo e-mail, caso contrário a página mostra um erro e nada é salvo.

Shop ID: o ID numérico (pk) da sua loja no painel da Loggi, por exemplo 12345. Qualquer outro valor é rejeitado com um erro.

Staging: use o ambiente de testes (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. Obrigatório para os preços em tempo real: o endereço da loja no OpenCart é texto livre, então ele nunca é usado no lugar. Sem um endereço de coleta, a Loggi não pode estimar e somente os preços fixos são usados.

BRL exchange rate: os preços da Loggi estão em reais brasileiros. 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. Somente 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 um CEP completo, e sempre que a Loggi não retorna um 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 botão de remover para excluir 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 até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 5 kg. Uma coluna de peso vazia (ou 0) usa o preço base. Um preço base de 0 significa frete grátis. "9.99" e "9,99" são aceitos. Linhas vazias e uma segunda linha para o mesmo país são removidas 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 (e não há linha *). Deixe em branco 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 que isto. 0 significa sem limite (padrão).

Maximum weight (kg): oculta o método quando o carrinho pesa mais que isto. Padrão: 30. 0 significa sem limite. Minimum weight não pode ser maior que Maximum weight.

Minimum order amount: mostra 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 sempre mostrá-lo.

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual o envio pela Loggi é grátis. Deixe em branco se não houver frete grátis.

Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Escolha No tax se os seus preços e o preço da Loggi já incluírem impostos.

Geo zone: ofereça a Loggi somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. A zona geográfica não é verificada quando Ignore shipping zones está ativado.

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

Países

O OpenCart não tem zonas de transportadora: a Geo zone limita o método aos endereços de uma zona geográfica. Em vez disso, você pode ativar Ignore shipping zones e escolher uma lista de países.

Ignore shipping zones: ofereça a Loggi para os países abaixo, independentemente da Geo zone. A zona geográfica não é verificada neste modo. Padrão: desativado.

Countries: os países de destino para esse modo. Deixe em branco para permitir todos os países ativados na loja. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de tarifa e as solicitações à Loggi em storage/logs/vfd_lggi_debug.log.php (no OpenCart 4, system/storage/logs/vfd_lggi_debug.log.php). O arquivo não pode ser lido pela web. Os 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. Quando o arquivo chega a 5 MB, ele é movido para vfd_lggi_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 da Loggi e o log. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. Os preços em cache são sempre removidos.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API não é exportada.

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. A chave de API salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Loggi. Se houver uma Geo zone definida, Ignore shipping zones estiver desativado e o endereço estiver fora da zona geográfica, a Loggi não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os outros não adicionam peso e não entram no valor do pedido. A extensão então verifica as condições: países permitidos (com Ignore shipping zones), peso do carrinho e valor mínimo 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. Vales-presente, pontos de recompensa e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Loggi.

Para um endereço no Brasil com CEP completo de 8 dígitos, a extensão monta pacotes da Loggi: cada item é girado para que o lado menor fique como altura, e os itens são empilhados em um mesmo pacote enquanto ele permanece dentro de 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 solicitações e os totais são somados. A extensão envia à Loggi o seu Shop ID, o endereço de coleta, o endereço de entrega (rua, cidade, estado e CEP) e os pacotes, e converte o total da Loggi de BRL para a moeda padrão da sua loja. O preço é arredondado conforme as casas decimais dessa moeda e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

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 solicitação. Uma estimativa com falha fica em cache por 10 minutos. Se a Loggi não puder ser acessada de forma alguma, as solicitaçõ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 um CEP completo, falta a taxa de câmbio para 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 um erro, um pacote rejeitado, um endereço fora da área de cobertura ou um total zero. Se também não houver preço fixo, o método é ocultado. O cliente nunca vê um erro da API. O motivo é gravado no log de depuração.

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

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

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 Loggi é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Loggi > 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 novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-loggi e o link Manage licenses and domains in your account, que abre a sua conta 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 que o endereço da loja mudar, 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a sua vaga de domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, o método de envio da Loggi 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 vê o login do administrador, então, sem uma chave ativa, o método fica oculto para todos. Depois que você 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 quando você abre o Dashboard do painel administrativo 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. Nenhum cron job é necessário. Desinstalar a extensão 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á ativado. Verifique Geo zone, Ignore shipping zones e Countries, os avisos no topo da página da extensão, 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, 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. Verifique se os produtos têm Requires Shipping definido como Yes.

Somente preços fixos são mostrados: veja o campo Log na página da extensão. Os 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, ainda sem um 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 rejeitou o e-mail ou a chave da API. Verifique-os com a Loggi e confirme que 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 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.

Por 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 alteração: clique em Save na página da extensão. Isso limpa os preços da Loggi em cache.

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

Para desenvolvedores: o endereço da API da Loggi pode ser substituído pela configuração vfd_lggi_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Loggi. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Loggi, Sort order, Tax class e Geo zone. Os preços da Loggi em cache (com a respectiva tabela) são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações da Loggi 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 Loggi na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Loggi é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Loggi.