VibeFox GIG Logistics for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Credenciais da API da GIG Logistics (somente para preços em tempo real): os preços em tempo real usam a API de terceiros da GIG Logistics. A GIG Logistics fornece a clientes empresariais 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 reserva, não precisa de credenciais de API.
Nigéria na sua loja: os preços em tempo real são solicitados apenas para endereços de entrega na Nigéria, por isso o país Nigéria precisa existir e estar ativo em International > Locations > Countries.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 envio terminar, clique em Configure ou encontre depois o VibeFox GIG Logistics na lista de módulos e clique em Configure.
3. Cole 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. Preencha a tabela de preços e/ou o custo de reserva. Para preços em tempo real, informe também o nome de usuário e a senha da API, o telefone, a cidade e o estado de coleta, e a taxa de conversão de moeda caso sua moeda padrão não seja NGN (veja Configuração). Clique em Save.
5. Se o campo Nigerian states mostrar o botão Add Nigerian states, clique nele (veja Configuração).
Na instalação, o módulo cria a transportadora GIG Logistics com o texto de prazo de entrega Courier delivery. A transportadora fica vinculada à zona da Nigéria (em uma loja padrão, a África) e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo 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 ficam na página do módulo: Modules > Module Manager > VibeFox GIG Logistics > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa os preços em cache da GIG Logistics, os tokens da API e as coordenadas de endereços.
Acima das seções, a página exibe avisos quando os preços em tempo real não podem ser usados: apenas um entre o nome de usuário e a senha da API está preenchido, faltam o Sender phone ou a cidade ou o estado de coleta, ou sua moeda padrão não é NGN e nenhuma Currency conversion rate foi definida. A página também avisa quando a transportadora GIG Logistics não é encontrada, e quando a unidade de peso da sua loja (International > Localization > Local units) não é conhecida pelo módulo; nesse caso, os pesos dos produtos são lidos como kg. Ao salvar, é informado um número inválido (um valor negativo, uma 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, ou uma regra de imposto desconhecida, e nada é salvo.
General
As configurações desta página se aplicam a todas as zonas da transportadora.
Enable/Disable: liga ou desliga a transportadora. É a mesma chave do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido no carrinho e na finalização de compra. Padrão: GIG Logistics. Obrigatório.
Tax: a regra de imposto da transportadora, ou No tax. Uma regra de imposto acrescenta o seu imposto de entrega ao custo. Escolha No tax se o preço da GIG já incluir tudo o que você quer cobrar.
GIG Logistics API (live prices) (opcional)
Com credenciais de API, o preço é solicitado à GIG Logistics para cada endereço na Nigéria. Sem credenciais, ou quando a API não retorna um preço, são usados a tabela de preços e o custo de reserva.
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 apenas para entrar na API e nunca é registrada em log. Após salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la. Para remover a senha, apague o API username e salve.
Test mode: usa a API de teste (dev) da GIG Logistics. Credenciais de teste funcionam somente com a API de teste. Desligue para obter preços reais. Padrão: desligado.
Currency conversion rate: a GIG Logistics retorna os preços em NGN. Se a moeda padrão da sua loja não for NGN, informe quanto vale um 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 em tempo real da GIG não são usados. Se sua moeda padrão for NGN, o campo informa isso e ele não é necessário. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Pickup (sender) address
Onde a GIG Logistics coleta os pacotes, na Nigéria. Se sua loja estiver na Nigéria, os campos vazios de rua, cidade e estado usam o endereço da loja em Shop Parameters > Contact > Stores.
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 o campo para preços em tempo real.
Street address: o endereço da rua de coleta.
City / area: a cidade ou bairro de coleta, por exemplo Victoria Island. Obrigatório para preços em tempo real.
State: o estado nigeriano do endereço de coleta, escolhido entre os 37 estados. A opção padrão, Shop state (Shop parameters > Contact > Stores), usa o estado do endereço da loja. Obrigatório para preços em tempo real.
Pickup latitude: latitude opcional do ponto de coleta no mapa, por exemplo 6.4281. A GIG Logistics calcula os preços por distância. Se vazio, 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: encontra 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 a 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: ligado.
Nigerian states: o estado do endereço de entrega é enviado à GIG Logistics e à busca de endereços. O PrestaShop não tem estados da Nigéria por padrão; sem eles, são usados apenas rua e cidade. O botão Add Nigerian states adiciona os 37 estados (códigos LA, FC etc.), ativa Contains states para a Nigéria e adiciona o campo de estado ao formulário de endereço da Nigéria. Estados que já existem (pelo código ou pelo nome) não são adicionados de novo. Quando tudo estiver pronto, o campo mostra quantos estados os endereços da Nigéria possuem. Nada é alterado até você clicar no botão.
Price table and fallback
Usada para outros países, quando os preços em tempo real não estão configurados ou quando a GIG Logistics não retorna um preço. Os preços sã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 e no ícone de lixeira para removê-la. Escolha * Any other country para todos os países sem linha própria. As colunas XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg) são preços opcionais por faixa de peso: um preço de faixa maior que 0 substitui o preço base para carrinhos nessa faixa. Um preço de 0 significa entrega grátis. Células de preço vazias são salvas como 0, então preencha o preço base de cada linha que adicionar. Se um país aparecer duas vezes, a linha posterior é mantida. Os valores corrigidos são listados em um aviso após o salvamento. 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. Se vazio, a transportadora fica oculta nesse caso.
Table / fallback price is: Per order cobra o preço uma única vez. Per item (multiplied by the number of items) o multiplica pelo número de itens no carrinho. Os preços em tempo real da GIG sempre valem para o pedido inteiro.
Conditions
Free shipping from: o subtotal do carrinho (produtos que precisam de entrega, após descontos, sem impostos) a partir do qual a entrega é grátis. Se vazio, nunca é grátis.
Minimum subtotal: exibe a transportadora somente quando o subtotal do carrinho atinge este valor. Se vazio, é sempre exibida.
Min weight (kg): o peso mínimo do carrinho em kg. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. 0 significa sem limite.
Max weight (kg): o peso máximo do carrinho em kg. Padrão: 30. 0 significa sem limite.
Availability without shipping zones
Ignore shipping zones: oferece a transportadora para os países listados abaixo, mesmo que as zonas dela não os incluam. Ao ligar, a transportadora é vinculada a todas as zonas ativas, e as zonas criadas depois também são vinculadas. Ao desligar, a transportadora volta a ter as zonas anteriores.
Countries: os países de destino para esse modo. Se vazio, valem todos os países para os quais você envia. Usado somente com Ignore shipping zones.
Advanced
Debug log: grava os cálculos de preço em logs/vfd_gigl_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 o log desligado. Senhas, tokens ou endereços de clientes não são gravados.
Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ligada, desinstalar o módulo apaga as configurações do módulo, a transportadora, os caches e os logs. Quando desligada, tudo é mantido para uma reinstalação. Os pedidos são sempre mantidos.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da GIG Logistics. Só contam os produtos que precisam de entrega: produtos virtuais não somam peso e não entram no subtotal. O módulo 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.
Depois, o preço vem da primeira fonte que fornecer um. Primeiro, o preço da GIG Logistics em tempo real, 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, para lojas cuja moeda padrão não seja NGN, houver uma taxa de conversão definida. O módulo entra na API da GIG Logistics e envia os endereços e coordenadas de coleta e de entrega, além dos 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, a transportadora fica oculta para aquele carrinho. O preço é calculado na sua moeda padrão e depois exibido na moeda do carrinho do cliente.
Cada resposta da GIG fica em cache por 1 hora, então o mesmo carrinho não gera uma nova solicitação. Uma solicitação ou um login com falha ficam em cache por 10 minutos, para que a finalização de compra não espere pela GIG Logistics a cada atualização da página. O token de login é mantido por 30 minutos e renovado automaticamente quando a GIG o rejeita. O tempo limite da API é de 10 segundos, e o da busca de endereço, de 5 segundos.
Se a GIG Logistics retornar um erro ou um preço zero, o cliente não vê nenhum erro. É usado o preço da tabela ou o custo de reserva, e o erro é gravado no log de depuração.
Se você editar a transportadora em Shipping > Carriers depois de ela ter 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 envios, conhecimentos de transporte ou etiquetas da GIG Logistics, não agenda coletas, não rastreia encomendas e não permite que os clientes escolham um centro de atendimento. Os pedidos são despachados pela sua conta da GIG Logistics, como de costume. Os preços em tempo real são solicitados somente para endereços na Nigéria. Para outros países, use a tabela de preços.
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 GIG Logistics é o primeiro bloco em Modules > Module Manager > VibeFox GIG Logistics > Configure, acima das configurações. Cole 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 deles ficam a linha Product: presta-shipping-gig-logistics e o link Manage licenses and domains in your account, que abre a sua conta em 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 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, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, também em configurações multiloja. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a transportadora GIG Logistics não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A loja 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 testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 informada, 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 GIG Logistics não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones e confira Countries. Verifique os limites de peso e o Minimum subtotal. Confira se a tabela (o país ou *) ou o Fallback cost fornece um preço para o país. Produtos também podem ser limitados a certas transportadoras na página do produto.
O preço vem da tabela, não da GIG Logistics: os preços em tempo real exigem nome de usuário e senha da API, o Sender phone, a cidade e o estado de coleta, um endereço de entrega na Nigéria com cidade ou estado e, para lojas cuja moeda padrão não seja NGN, a Currency conversion rate. Veja os avisos no topo da página Configure. Ligue o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo para descobrir o motivo. Uma solicitação com falha é repetida após 10 minutos.
Login failed no log: a GIG Logistics rejeitou o nome de usuário ou a senha da API. Confira ambos e verifique o Test mode: credenciais de teste funcionam somente com a API de teste. Salve as configurações para tentar novamente imediatamente.
A GIG Logistics não retorna um preço: a GIG calcula os preços por distância. Mantenha o Address lookup ligado ou informe Pickup latitude e Pickup longitude. Clique em Add Nigerian states para que o estado de entrega também seja enviado. Confirme os preços com sua conta da GIG Logistics antes de entrar em produção.
O aviso de cidade e estado de coleta continua aparecendo: escolha um estado em State e preencha City / area. O endereço da loja só é usado quando o país da loja é a Nigéria, e o estado da loja só é conhecido depois que os estados da Nigéria forem adicionados e escolhidos em Shop Parameters > Contact > Stores.
O imposto é cobrado sobre o preço da GIG: defina Tax 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 do módulo. Isso limpa os preços, tokens e coordenadas em cache.
A página informa que a transportadora GIG Logistics 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 GIG Logistics e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Os preços, tokens e coordenadas de endereços em cache são sempre removidos. Se Remove data on uninstall estiver ligado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desligado, a transportadora apenas é desativada e todas as configurações são mantidas. Instalar o módulo novamente devolve à transportadora salva o status anterior. Os estados da Nigéria adicionados com Add Nigerian states permanecem na sua loja nos dois casos.
GIG Logistics é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela GIG Logistics.