VibeFox 99Minutos 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 mais antigas do PHP.
Chave de API da 99minutos (apenas para a verificação de cobertura): peça ao seu gerente de conta da 99minutos ou no portal de desenvolvedores da 99minutos (developers.99minutos.com). As chaves sandbox e de produção são diferentes. Se você usar apenas a matriz de preços, não precisa de chave de API.
Países: a 99minutos entrega no México, na Colômbia, no Chile e no Peru. Os países para os quais você envia devem estar ativos em International > Locations.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, acesse 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 99Minutos 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. Preencha a Price matrix (pelo menos uma linha, por exemplo “* Default”) e, opcionalmente, a chave de API e o modo de verificação de cobertura (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora 99Minutos com o texto de prazo de entrega Courier delivery. 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. As zonas do México, da Colômbia, do Chile e do Peru devem permanecer ativas para a transportadora. 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 99Minutos > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa os resultados de cobertura em cache. Após salvar, a página avisa se a matriz de preços está vazia, se tem linhas para países que a 99minutos não atende, se um modo de verificação de cobertura foi escolhido sem chave de API, ou se o módulo não reconhece a unidade de peso da loja (nesse caso, os pesos são considerados em quilogramas). Nada é salvo, e um erro é exibido, se Method title tiver mais de 64 caracteres, se um campo de peso ou valor não for um número igual ou maior que 0, ou se Min weight (kg) for maior que Max weight (kg). Se a página mostrar The 99Minutos carrier was not found — reset the module to create it again., veja Solução de problemas.
Geral
Enable 99Minutos: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido ao cliente no carrinho e na finalização de compra. Padrão: 99Minutos. Obrigatório, até 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. Com uma regra de imposto, o PrestaShop adiciona o imposto ao preço de frete da matriz.
API 99minutos (verificação de cobertura) (opcional)
A API é usada somente para verificar se a 99minutos entrega no CEP do cliente. O preço sempre vem da matriz.
Coverage check: se o CEP é verificado e como.
Com a verificação de cobertura, a transportadora só aparece depois que o cliente informa um CEP. Os resultados ficam em cache: atendido por 6 horas, não atendido por 30 minutos, erro da API por 5 minutos. Só o CEP é enviado à 99minutos, em maiúsculas e com apenas letras e números.
API key: sua chave de API da 99minutos, enviada como token Bearer ao endpoint de cobertura da 99minutos. Obrigatória quando a verificação de cobertura está ativa. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo. A chave é salva como foi digitada; apenas os espaços no início e no fim são removidos.
Remove the saved API key: aparece apenas quando uma chave está salva. Ative a opção e clique em Save para excluir a chave.
Environment: Sandbox (test) (padrão) ou Production. Sandbox e produção usam chaves de API diferentes, então escolha o ambiente que corresponde à sua chave.
Tarifas
Os preços estão na moeda padrão da sua loja, sem impostos, e são usados como foram informados. O preço final é exibido na moeda do carrinho do cliente.
Price matrix: uma tabela de países de destino e preços. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. Cada linha tem um Country (* Default, México, Colômbia, Chile ou Peru), um Base price e preços para os tamanhos XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Um preço de tamanho vazio ou 0 usa o Base price. A linha * Default vale para os países sem linha própria. Se um país tiver várias linhas, usa-se a primeira. Tanto o ponto quanto a vírgula são aceitos como separador decimal; preços vazios, inválidos ou negativos são salvos como 0. Enquanto a matriz não tiver pelo menos uma linha, a transportadora não é exibida na finalização de compra.
Calculation: Per order — size by the total cart weight (padrão) cobra um único preço pelo tamanho do pacote de todo o carrinho. Per item — each unit priced by its own weight precifica cada unidade pelo tamanho do próprio peso e soma os valores.
Free shipping: ativa o frete grátis a partir de um subtotal do carrinho.
Free shipping from: o subtotal do carrinho (após descontos, sem impostos) a partir do qual a tarifa é 0. Usado somente quando Free shipping está ativo.
Restrições
Min weight (kg): oculta a transportadora se o carrinho for mais leve. 0 significa sem limite. Não pode ser maior que Max weight (kg). Os pesos dos produtos são convertidos da unidade de peso da sua loja.
Max weight (kg): oculta a transportadora se o carrinho for mais pesado. Padrão: 25. 0 significa sem limite; um campo vazio significa 25 kg.
Minimum subtotal: exibe a transportadora somente se o subtotal do carrinho (após descontos, sem impostos) for pelo menos este valor. Deixe vazio para exibi-la sempre.
Restrict countries: oferece a transportadora somente para os países abaixo. É um filtro adicional sobre as zonas da transportadora. Útil quando uma zona abrange vários países.
Countries: uma escolha dos países da 99minutos (México, Colômbia, Chile, Peru). Segure Ctrl (Cmd) para selecionar vários. Usado somente quando Restrict countries está ativo. Deixe vazio para permitir todos os países da 99minutos.
Avançado
Debug log: grava os cálculos de tarifas em logs/vfd_99m_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são registrados mesmo quando esta opção está desligada. Chaves de API e nomes e endereços de clientes nunca são registrados. Desligue o log quando terminar.
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 ativo, desinstalar o módulo exclui as configurações, a transportadora, o cache de cobertura e o log. Quando desativado, tudo é mantido para uma reinstalação. Os pedidos são mantidos em qualquer caso.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da 99Minutos. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal do carrinho. A transportadora é oferecida somente quando o país de entrega é México, Colômbia, Chile ou Peru (e está na lista Countries se Restrict countries estiver ativo). Em seguida, o módulo verifica os limites de peso e o Minimum subtotal.
Se um modo de verificação de cobertura estiver ativo, o módulo pergunta à API da 99minutos se o CEP é atendido. A requisição tem tempo limite de 10 segundos e a resposta fica em cache, então o mesmo CEP não gera uma nova requisição. Erros da API nunca são mostrados ao cliente: no modo Strict a transportadora é ocultada; no modo Soft, usa-se o preço da matriz. O frete grátis não contorna a verificação de cobertura.
O preço é obtido da linha da matriz do país de entrega ou da linha * Default. Se nenhuma existir, a transportadora é ocultada. Se Free shipping estiver ativo e o subtotal do carrinho atingir Free shipping from, a tarifa é 0. O preço é calculado na moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente.
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 acompanha a nova versão automaticamente.
O módulo não obtém cotações de frete em tempo real da 99minutos: os preços sempre vêm da sua matriz. Ele não cria envios nem pedidos na 99minutos, não imprime etiquetas (guides), não rastreia pacotes, não oferece pontos de retirada Punto99 e não trabalha com pagamento na entrega. Crie os envios na sua conta da 99minutos como de costume.
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 99Minutos é o primeiro bloco da página Modules > Module Manager > VibeFox 99Minutos > 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-99minutos e o link Manage licenses and domains in your account, que abre sua conta vibefox.net. Somente funcionários com a permissão Configure para o 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 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 99Minutos 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. 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 inserida e depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
99Minutos não aparece na finalização de compra: verifique se a licença está ativa e se Enable 99Minutos está ligado. O país de entrega deve ser México, Colômbia, Chile ou Peru e estar ativo em International > Locations. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo dele. Confira se a Price matrix tem uma linha para esse país ou uma linha * Default, e verifique os limites de peso, o Minimum subtotal e o Restrict countries. Produtos também podem estar limitados a determinadas transportadoras na página do produto.
A transportadora só aparece depois que um CEP é informado: isso é esperado com a verificação de cobertura. No modo Strict, ela só aparece quando a API confirma a cobertura.
A transportadora fica sempre oculta no modo Strict: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Um erro HTTP 401 ou 403 significa que a chave de API foi recusada: verifique a chave e se o Environment corresponde a ela (chaves sandbox e de produção são diferentes). Use o modo Soft se os clientes devem continuar vendo o preço da matriz enquanto a API estiver indisponível.
O preço não é o que você esperava: verifique o Calculation (por pedido ou por item), os pesos dos produtos e a unidade de peso da sua loja (International > Localization). Um preço de tamanho vazio ou 0 usa o Base price. Com uma regra de imposto em Tax, o imposto é somado ao preço da matriz.
Os resultados de cobertura parecem desatualizados após uma mudança: clique em Save na página do módulo. Isso limpa os resultados de cobertura em cache.
A página diz que a transportadora 99Minutos não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para recriá-la. O mesmo vale para a mensagem The settings were saved, but the carrier could not be updated. Reset the module to create it again.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox 99Minutos e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O cache de cobertura também é sempre removido. 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 reinstalar o módulo, a transportadora salva recupera o status que tinha antes da desinstalação, então Reset não ativa uma transportadora desativada.
99minutos é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela 99minutos.