VibeFox GIG Logistics for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Credenciais da API da GIG Logistics (somente para preços ao vivo): os preços ao vivo usam a API de terceiros da GIG Logistics. A GIG Logistics fornece a clientes comerciais um nome de usuário de API (geralmente um endereço de e-mail) e uma senha. Solicite-os na página para desenvolvedores da GIG Logistics (giglogistics.com/developer). Credenciais de teste funcionam somente com a API de teste. Se você usa apenas a tabela de preços e o custo de contingência, não precisa de credenciais de API.

Nigéria na sua loja: os preços ao vivo são solicitados somente para endereços de entrega na Nigéria. O OpenCart já tem o país Nigéria com seus 37 estados; ele precisa estar ativado em System > Localisation > Countries.

Chave de licença do 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_gig_logistics-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_gig_logistics.ocmod.zip. Instale apenas 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, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_gig_logistics-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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox GIG Logistics e clique em Install (o botão verde +).

3. Clique em Edit (o botão de lápis) para abrir a página de configurações.

4. Informe sua chave de licença do 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. Preencha a tabela de preços e/ou o custo de contingência. Para preços ao vivo, informe também o nome de usuário e a senha da API, o telefone de coleta, a rua, a cidade e o estado, e a taxa de conversão de moeda se a moeda padrão não for o NGN (veja Configuração). Ative Enable/Disable e clique em Save.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_gig_logistics.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox GIG Logistics, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as configurações como nos passos 4 e 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Depois da instalação, o método fica desativado até que você ative Enable/Disable e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações mantidas serão usadas de novo.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit. As seções ficam listadas à esquerda. Um único botão Save no final salva a página inteira sem recarregá-la. Cada salvamento também limpa os preços, tokens da API e coordenadas dos endereços em cache da GIG Logistics. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

No topo da página, e de novo após cada salvamento, a extensão mostra avisos quando os preços ao vivo não podem ser usados: somente o nome de usuário ou a senha da API está preenchido, o Sender phone ou a cidade e o estado de coleta estão faltando, ou a moeda padrão não é o NGN e nenhum Currency conversion rate está definido. Ela também avisa quando a loja não tem uma classe de peso com a unidade kg (System > Localisation > Weight Classes); os pesos dos produtos são então convertidos pelo nome da unidade (kg, g, lb, oz), e as demais unidades são lidas como kg. Ao salvar, um número inválido é informado (um valor negativo, um Currency conversion rate igual a 0, uma latitude fora de -90 a 90, uma longitude fora de -180 a 180), um Min weight (kg) maior que o Max weight (kg), um Method title vazio ou inválido, uma ordem de exibição que não é um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida, e nada é salvo.

Geral

O método é oferecido para a zona geográfica selecionada em Conditions, ou para os países de Ignore shipping zones. As configurações desta página se aplicam a todas as zonas.

Enable/Disable: mostra ou oculta a GIG Logistics na finalização de compra (o status desta extensão). Padrão: desativado.

Method title: o nome do método de envio exibido no carrinho e na finalização de compra. Padrão: GIG Logistics. Obrigatório, de 1 a 64 caracteres, sem os caracteres < > ; = # { }.

Tax class: a classe de imposto do custo de envio, ou No tax. Uma classe de imposto soma o seu imposto de envio ao custo. Escolha No tax se o preço da GIG já incluir tudo o que você quer cobrar.

Sort order: a posição do método entre os métodos de envio. Um número inteiro.

API da GIG Logistics (preços ao vivo) (opcional)

Com credenciais de API, o preço é solicitado à GIG Logistics para cada endereço na Nigéria e fica em cache por uma hora. Sem credenciais, ou quando a API não retorna preço, são usados a tabela de preços e o custo de contingência. A seção tem um link para a página para desenvolvedores da GIG Logistics.

API username: seu nome de usuário da API de terceiros da GIG Logistics, geralmente seu endereço de e-mail.

API password: sua senha da API de terceiros da GIG Logistics. Ela é usada somente para fazer login na API e nunca é registrada. Após salvar, o campo fica vazio e exibe Saved — leave empty to keep it. To remove it, clear the API username and save. Digite um valor novo apenas para alterá-la.

Test mode: usa a API de teste (dev) da GIG Logistics. Credenciais de teste funcionam somente com a API de teste. Desative para obter preços reais. Padrão: desativado.

Currency conversion rate: a GIG Logistics retorna preços em NGN. Se a moeda padrão da sua loja não for o NGN, informe quanto vale 1 NGN na sua moeda padrão (1 NGN = ? da sua moeda, por exemplo 0.0006). A taxa deve ser maior que 0. Sem ela, os preços ao vivo da GIG não são usados. Se a moeda padrão for o NGN, o campo informa isso e ele não é necessário.

Endereço de coleta (remetente)

Onde a GIG Logistics coleta os pacotes, na Nigéria. O OpenCart não tem um endereço de loja estruturado, então informe aqui a rua e a cidade. Quando o país da loja é a Nigéria, um State vazio usa a região da loja definida em System > Settings > Store > Local.

Sender name: o nome do remetente enviado à GIG Logistics. Se vazio, usa-se o nome da loja.

Sender phone: seu número de telefone, por exemplo 08030000000. A GIG Logistics exige para os preços ao vivo.

Street address: a rua da coleta, por exemplo 1 Adeola Odeku Street.

City / area: a cidade ou bairro da coleta, por exemplo Victoria Island. Obrigatório para os preços ao vivo.

State: o estado nigeriano do endereço de coleta, escolhido entre os 37 estados. A opção padrão, Store region (System > Settings > Store > Local), usa a região da sua loja quando ela está na Nigéria. Obrigatório para os preços ao vivo.

Pickup latitude: latitude opcional do ponto de coleta no mapa, por exemplo 6.4281. A GIG Logistics calcula os preços pela distância. Vazio significa que as coordenadas são buscadas a partir do endereço.

Pickup longitude: longitude opcional do ponto de coleta no mapa, por exemplo 3.4219.

Address lookup: busca as coordenadas no mapa dos endereços com o OpenStreetMap (Nominatim). A GIG Logistics calcula o preço a partir das coordenadas de coleta e de entrega. A rua, a cidade e o estado do cliente são enviados para nominatim.openstreetmap.org, e os resultados ficam em cache por 30 dias. Sem essa opção, apenas o texto do endereço é enviado, e a GIG Logistics pode não retornar um preço. Padrão: ativado.

Tabela de preços e contingência

Usada para outros países, quando os preços ao vivo não estão configurados ou quando a GIG Logistics não retorna preço. Os preços estão na moeda padrão da sua loja, sem impostos.

Country prices: uma tabela com um preço base por país. Clique em Add country para adicionar uma linha. Escolha * Any other country para todos os países sem linha própria. As colunas XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg são preços opcionais por faixa de peso: um preço de faixa acima de 0 substitui o preço base para carrinhos nessa faixa. Um preço de 0 significa frete grátis. Células de preço vazias ou inválidas são salvas como 0, então preencha o preço base de cada linha que adicionar. Os valores corrigidos são listados após o salvamento, em um aviso que começa com Country prices:. Países sem linha (quando não há linha *) não recebem preço da tabela.

Fallback cost: usado quando nem a GIG Logistics nem a tabela fornecem um preço. Vazio significa que o método fica oculto nesse caso.

Table / fallback price is: Per order cobra o preço uma vez. Per item (multiplied by the number of items) o multiplica pelo número de itens no carrinho. Os preços ao vivo da GIG são sempre para o pedido inteiro.

Condições

Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após o cupom, sem impostos) a partir do qual o frete é grátis. Vazio significa nunca grátis.

Minimum subtotal: exibe o método somente quando o subtotal do carrinho atinge este valor. Vazio significa sempre.

Min weight (kg): o peso mínimo do carrinho em kg. Os pesos dos produtos são convertidos pela classe de peso deles. 0 significa sem limite.

Max weight (kg): o peso máximo do carrinho em kg. Padrão: 30. 0 significa sem limite.

Geo zone: ofereça o método somente para endereços desta zona geográfica. All zones significa sem limite. Não é usada com Ignore shipping zones. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Disponibilidade sem zonas de envio

Ignore shipping zones: ofereça o método para os países abaixo, independentemente da zona geográfica. A Geo zone em Conditions então não é verificada.

Countries: os países de destino para esse modo, escolhidos entre os países ativos da sua loja. Vazio significa todos os países para os quais você envia. Usada somente com Ignore shipping zones.

Avançado

Debug log: grava os cálculos de preço em storage/logs/vfd_gigl_debug.log.php (no OpenCart 4, system/storage/logs/vfd_gigl_debug.log.php). O arquivo não pode ser lido pela web. Erros da API e da busca de endereços são sempre registrados, mesmo com o log desativado. Senhas, tokens e endereços de clientes não são gravados. Quando o arquivo atinge 5 MB, ele é movido para vfd_gigl_debug.old.log.php e um novo log é iniciado.

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 ativado, ao desinstalar a extensão são excluídas as configurações e os logs. Quando desativado, tudo é mantido para uma reinstalação. Os preços em cache são sempre removidos. Os pedidos são sempre mantidos.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha da 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 senha da 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 GIG Logistics. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no subtotal. O subtotal é o preço desses produtos após o desconto do cupom, sem impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados. A extensão verifica primeiro as condições: o país de entrega (com Ignore shipping zones), o peso do carrinho e o subtotal mínimo. Se o subtotal atingir Free shipping from, o preço é 0 e nenhuma solicitação é enviada à GIG Logistics.

Em seguida, o preço vem da primeira fonte que fornecer um. Primeiro, o preço ao vivo da GIG Logistics, se as credenciais da API estiverem informadas, o endereço estiver na Nigéria, o endereço tiver cidade ou estado, o telefone, a cidade e o estado de coleta estiverem definidos, e uma taxa de conversão estiver definida para lojas cuja moeda padrão não seja o NGN. A extensão acessa a API da GIG Logistics e envia os endereços e coordenadas de coleta e de entrega e os itens do carrinho com nomes, quantidades, pesos e valores. Produtos sem peso são enviados como 1 kg. O preço é solicitado para entrega de bicicleta. Segundo, a tabela Country prices. Terceiro, o Fallback cost. Se nenhuma fonte fornecer um preço, o método fica oculto para aquele carrinho. O preço é calculado na moeda padrão, arredondado conforme as casas decimais dela e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.

Cada resposta da GIG fica em cache por 1 hora, para que o mesmo carrinho não dispare uma nova solicitação. Uma solicitação com falha ou um login com falha fica em cache por 10 minutos, para que a finalização de compra não espere pela GIG Logistics a cada atualização. O token de login é mantido por 30 minutos e renovado automaticamente quando a GIG o rejeita. As coordenadas dos endereços são mantidas por 30 dias, e um endereço não encontrado por 1 dia. O tempo limite da API é de 10 segundos, e o da busca de endereços de 5 segundos.

Se a GIG Logistics retornar um erro ou um preço zero, o cliente não vê erro algum. O preço da tabela ou o custo de contingência é usado, e o erro é gravado no log de depuração.

A extensão calcula somente preços. Ela não cria envios, conhecimentos de transporte ou etiquetas da GIG Logistics, não agenda coletas, não rastreia pacotes e não permite que os clientes escolham um centro de serviço. 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. Os preços ao vivo são solicitados somente para endereços nigerianos. Para outros países, use a tabela de preços.

No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de finalização de compra e escolhe a GIG Logistics na janela Shipping method options, onde a opção mostra o título do método e o preço, por exemplo GIG Logistics - $4.50. O método funciona da mesma forma que no OpenCart 3.

Chave de licença

A extensão funciona com uma chave de licença do VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox GIG Logistics é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit, acima das configurações. Informe 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 informar outra chave, e Remove key, para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-gig-logistics e o link Manage licenses and domains in your account, que abre a sua conta do 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 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 seguido de uma data. Depois que o endereço da loja mudar, 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 na configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta do vibefox.net.

Sem uma chave ativa, o método de envio da GIG Logistics não é exibido aos clientes na finalização de compra, e nenhum preço é calculado. Um usuário administrador conectado ao admin no mesmo navegador ainda vê o método na loja, marcado 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 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 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 novamente de forma automática quando você abre o Dashboard ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário 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 GIG Logistics não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ligado. Verifique a Geo zone, ou Ignore shipping zones e Countries, os limites de peso e o Minimum subtotal. Verifique se a tabela (o país ou *) ou o Fallback cost fornece um preço para o país. Verifique se os produtos têm Requires Shipping definido como Yes.

O preço vem da tabela, e não da GIG Logistics: os preços ao vivo exigem nome de usuário e senha da API, Sender phone, cidade e estado de coleta, um endereço de entrega nigeriano com cidade ou estado e, para lojas cuja moeda padrão não seja o NGN, o Currency conversion rate. Veja os avisos no topo da página Edit. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão para ver o motivo. Uma solicitação com falha é repetida após 10 minutos.

Falha de login no log: a GIG Logistics rejeitou o nome de usuário ou a senha da API. Verifique-os e verifique o Test mode: credenciais de teste funcionam somente com a API de teste. Salve as configurações para tentar novamente de imediato.

A GIG Logistics não retorna preço: a GIG calcula os preços pela distância. Mantenha o Address lookup ativado, ou informe Pickup latitude e Pickup longitude. Confirme os preços com a sua conta da GIG Logistics antes de entrar em operação.

O aviso de cidade e estado de coleta continua aparecendo: escolha um estado em State e preencha City / area. A região da loja só é usada quando o país da loja em System > Settings > Store > Local é a Nigéria.

Há imposto cobrado sobre o preço da GIG: defina Tax class como No tax se o preço da GIG já incluir tudo o que você quer cobrar.

Os preços parecem desatualizados após uma mudança: clique em Save na página da extensão. Isso limpa os preços, tokens e coordenadas em cache.

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

Para desenvolvedores: o endereço da API da GIG Logistics e o da busca de endereços podem ser substituídos pelas configurações vfd_gigl_api_base_url e vfd_gigl_geocode_url (para testes); eles não têm campos na página de configurações.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox GIG Logistics. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort order, Tax class e Geo zone. Os preços, tokens e coordenadas em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as demais configurações e o log de depuração também são excluídos. Se estiver desativado, eles são mantidos e usados 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, acesse Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox GIG Logistics na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

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