VibeFox 99Minutos 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.
Chave de API da 99minutos (somente para a verificação de cobertura): peça ao seu gerente de conta da 99minutos ou obtenha no portal de desenvolvedores da 99minutos (developers.99minutos.com). Chaves de sandbox e de produção são diferentes. Se você usa apenas a matriz de preços, não precisa de chave de API.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_99minutos para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox 99Minutos, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. 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 a seção “Configuração”).
6. Adicione VibeFox 99Minutos a uma zona de entrega em WooCommerce > Settings > Shipping > Shipping zones que cubra México, Colômbia, Chile ou Peru.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox 99Minutos. Elas valem para todas as zonas de entrega. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:
Method title (zone): o nome que os clientes veem nesta zona. Deixe vazio para usar o Method title global.
Ao salvar as configurações, a página avisa se a matriz de preços estiver vazia ou se um modo de verificação de cobertura for escolhido sem chave de API.
Geral
Enable/Disable: ativa a 99Minutos em todas as zonas de entrega de uma vez. O método também precisa ser adicionado a uma zona de entrega que cubra México, Colômbia, Chile ou Peru. Padrão: ativado.
Method title: o nome do método de entrega exibido ao cliente na finalização de compra. Uma zona pode substituí-lo. Padrão: 99Minutos.
Tax status: Taxable adiciona o imposto do WooCommerce ao custo de entrega, None não adiciona.
API da 99minutos (verificação de cobertura) (opcional)
A API é usada apenas para verificar se a 99minutos entrega no CEP do cliente. O preço sempre vem da matriz.
Coverage check: se e como o CEP é verificado.
Com a verificação de cobertura, o método 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. Somente o CEP é enviado à 99minutos.
API key: sua chave de API da 99minutos, enviada como token Bearer ao endpoint de verificação de cobertura da 99minutos. Obrigatória quando a verificação de cobertura está ativa. O campo fica mascarado.
Environment: Sandbox (test) (padrão) ou Production. Sandbox e produção usam chaves de API diferentes; escolha o ambiente que corresponde à sua chave.
Tarifas
Os preços são expressos na moeda da sua loja e usados como digitados, sem conversão.
Price matrix: uma tabela de países de destino e preços. Clique em + Add country para adicionar uma linha e no ícone de X para remover uma. Cada linha tem um Country, 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 igual a 0 usa o Base price. A linha * Default vale para os países sem linha própria. Tanto o ponto quanto a vírgula são aceitos como separador decimal; preços negativos são salvos como 0. Enquanto a matriz não tiver pelo menos uma linha, o método não é exibido na finalização de compra.
Calculation: Per order — size by the total cart weight (padrão) cobra um 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 apenas quando Free shipping está ativado.
Restrições
Min weight (kg): oculta o método se o carrinho for mais leve. 0 significa sem limite. Os pesos dos produtos são convertidos da unidade de peso da sua loja.
Max weight (kg): oculta o método se o carrinho for mais pesado. Padrão: 25. 0 significa sem limite.
Minimum subtotal: exibe o método somente se o subtotal do carrinho (após descontos, sem impostos) for pelo menos este valor. Deixe vazio para exibi-lo sempre.
Excluded shipping classes: oculta o método se algum item do carrinho tiver uma destas classes de entrega do WooCommerce.
Restrict countries: oferece o método apenas para os países abaixo. Este é um filtro adicional sobre as zonas de entrega: o método ainda precisa ser adicionado a uma zona. Útil quando uma zona cobre vários países.
Countries: escolha entre os países da 99minutos (México, Colômbia, Chile, Peru). Usado apenas quando Restrict countries está ativado. Deixe vazio para permitir todos os países da 99minutos.
Avançado
Debug log: registra os cálculos de tarifas em WooCommerce > Status > Logs (origem “vfd-99minutos”). Erros da API são registrados mesmo quando esta opção está desativada. Chaves de API e nomes e endereços de clientes nunca são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações e o cache de cobertura. Desativar não apaga nada. Os métodos de entrega nas zonas e os pedidos são mantidos em qualquer caso.
Como funciona na finalização de compra
O método é oferecido somente quando o país de entrega é México, Colômbia, Chile ou Peru (e está na lista Countries, se Restrict countries estiver ativado). Quando o cliente informa um endereço de entrega, o plugin verifica os limites de peso do carrinho, o Minimum subtotal e as Excluded shipping classes.
Se algum modo de verificação de cobertura estiver ativo, o plugin então consulta a API da 99minutos para saber se o CEP é atendido. O tempo limite da requisição é de 10 segundos e a resposta fica em cache, então o mesmo CEP não gera nova requisição. Erros da API nunca são mostrados ao cliente: no modo Strict, o método é ocultado; 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 vem da linha da matriz do país de entrega ou da linha * Default. Se nenhuma existir, o método é ocultado. Se Free shipping estiver ativado e o subtotal do carrinho atingir Free shipping from, a tarifa é 0.
O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin 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 normalmente.
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 99Minutos. 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 inserir 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 na sua conta em vibefox.net.
Sem uma chave ativa, a 99Minutos não é exibida aos clientes na finalização de compra. Gestores 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 aviso aparece na página Plugins e nas páginas do WooCommerce. Os 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 99Minutos 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 endereço do cliente. O país de entrega deve ser México, Colômbia, Chile ou Peru. Confirme se a Price matrix tem uma linha para esse país ou uma linha * Default, e verifique os limites de peso, Minimum subtotal, Excluded shipping classes e Restrict countries.
O método só aparece depois que um CEP é informado: isso é esperado com a verificação de cobertura. No modo Strict, ele só aparece quando a API confirma a cobertura.
O método fica sempre oculto no modo Strict: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs (origem “vfd-99minutos”). Um erro HTTP 401 ou 403 significa que a chave de API foi rejeitada: verifique a chave e se o Environment corresponde a ela (chaves de sandbox e de produção são diferentes). Use o modo Soft se os clientes devem receber 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. Um preço de tamanho vazio ou igual a 0 usa o Base price.
Outros países: desenvolvedores podem alterar a lista de países suportados com o filtro vfd_99m_supported_countries.
O bloco de licença mostra um erro: siga a mensagem exibida no 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 estiver acessível, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. 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 são sempre removidos. As configurações e o cache de cobertura só são removidos se Remove data on uninstall estava ativado. Caso contrário, ficam guardados para uma reinstalação futura. Os métodos de entrega nas zonas e os pedidos existentes são mantidos.
99minutos é uma marca de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela 99minutos.