VibeFox 99Minutos 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.
Chave de API da 99minutos (somente para a verificação de cobertura): obtenha com o seu gerente de conta da 99minutos ou no portal de desenvolvedores da 99minutos (developers.99minutos.com). As 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.
Países: a 99minutos entrega no México, na Colômbia, no Chile e no Peru. Os países para os quais você envia precisam estar ativados em System > Localisation > Countries.
Chave de licença 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 para o OpenCart 3 vfd_99minutos-oc3-(version).ocmod.zip e o pacote para o OpenCart 4 vfd_99minutos.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 administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_99minutos-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. Localize VibeFox 99Minutos 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 VibeFox no campo License key do bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).
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 Configuração). Ative Enable 99Minutos e clique em Save.
OpenCart 4
1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_99minutos.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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 99Minutos, 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 99Minutos e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações da 99minutos que você manteve voltam a ser usadas.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit. As seções aparecem à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa os resultados de cobertura em cache. Se um valor estiver errado, nada é salvo e a página mostra o motivo, por exemplo Enter a method title (1 to 64 characters)., uma mensagem de que um campo deve ser um número igual ou maior que 0, ou de que Min weight (kg) não pode ser maior que Max weight (kg). Após salvar, avisos acima das configurações informam quando o método não pode funcionar com a configuração atual: a matriz de preços está vazia, um modo de verificação de cobertura foi escolhido sem chave de API, a matriz tem linhas para países que a 99minutos não atende, ou a loja não tem a classe de peso "kg" e sua unidade de peso não é reconhecida pela extensão (nesse caso, os pesos são considerados em quilogramas). Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Geral
As configurações valem para todas as zonas geográficas. A 99Minutos é oferecida somente para o México, a Colômbia, o Chile e o Peru como países de destino.
Enable 99Minutos: mostra ou oculta a 99Minutos na finalização de compra. Padrão: desligado.
Method title: o nome do método de envio mostrado ao cliente no carrinho e na finalização de compra. Padrão: 99Minutos. Obrigatório, até 64 caracteres.
Tax class: a classe de imposto do custo do envio, ou No tax (padrão). Com uma classe de imposto, o OpenCart adiciona o imposto ao preço da matriz.
Sort order: a posição da 99Minutos entre os métodos de envio na finalização de compra. Um número inteiro.
API da 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 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, mas nunca por mais tempo que a duração do cache do OpenCart (1 hora por padrão). Só o CEP é enviado à 99minutos, em letras maiúsculas e apenas com 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 valor novo somente se quiser alterá-la. A chave é salva como digitada; apenas os espaços em volta são removidos.
Remove the saved API key: aparece somente quando há uma chave salva. Ative e clique em Save para apagar 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 informados. O preço final é mostrado na moeda do cliente.
Price matrix: uma tabela de países de destino e preços. Clique em Add country para adicionar uma linha e no botão × para removê-la. 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, a primeira é usada. 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, o método não aparece 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 seu próprio peso e soma os valores.
Free shipping: ativa o frete grátis a partir de um valor de pedido.
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) a partir do qual a tarifa é 0. Usado somente quando Free shipping está ativo.
Restrições
Min weight (kg): oculta o método se o carrinho for mais leve. 0 significa sem limite (padrão). Não pode ser maior que Max weight (kg). Os pesos dos produtos são convertidos a partir da sua classe de peso.
Max weight (kg): oculta o método se o carrinho for mais pesado. Padrão: 25. 0 significa sem limite; um campo vazio significa 25 kg.
Minimum subtotal: mostra o método somente se o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) for pelo menos esse valor. Deixe em branco para sempre mostrá-lo.
Geo zone: oferece a 99Minutos 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.
Restrict countries: oferece o método somente para os países listados abaixo. É um filtro adicional sobre a Geo zone.
Countries: uma lista dos países da 99minutos (México, Colômbia, Chile, Peru). Usada somente quando Restrict countries está ativo. Deixe vazia para permitir todos os países da 99minutos.
Avançado
Debug log: grava os cálculos de tarifas em storage/logs/vfd_99m_debug.log.php. O arquivo não pode ser lido pela web. Erros da API são registrados mesmo com a opção desligada. Chaves de API, nomes e endereços dos clientes nunca são registrados. Desligue o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_99m_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 limpá-lo.
Remove data on uninstall: quando ativo, desinstalar a extensão apaga as configurações da 99minutos, o cache de cobertura e o log. Quando desativado (padrão), eles são mantidos para uma reinstalação. Os pedidos são mantidos em qualquer caso.
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 99Minutos. Se uma Geo zone estiver definida e o endereço estiver fora dela, a 99Minutos não é oferecida. Só contam os produtos com Requires Shipping definido como Yes: os demais não adicionam peso e não entram no valor do pedido. O método só é oferecido 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, a extensão verifica os limites de peso e o Minimum subtotal. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e sem impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados.
Se uma verificação de cobertura estiver ativa, a extensão pergunta à API da 99minutos 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 uma nova requisição. Erros da API nunca são mostrados ao cliente: no modo Strict o método fica oculto; no modo Soft é usado 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, o método fica oculto. Se Free shipping estiver ativo e o valor do pedido atingir Free shipping from, a tarifa é 0. O preço é calculado na moeda padrão da loja, arredondado para suas casas decimais e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.
A extensão não obtém cotações de frete em tempo real da 99minutos: os preços sempre vêm da sua matriz. Ela não cria envios ou pedidos na 99minutos, não imprime etiquetas (guias), não rastreia pacotes, não oferece os pontos de retirada Punto99 e não trabalha com pagamento na entrega. Ela não acrescenta nada aos pedidos: o pedido mostra o nome do método e o custo do envio como qualquer outro método do OpenCart. Crie os envios na sua conta da 99minutos normalmente.
No OpenCart 4 o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe a 99Minutos na janela Shipping method options. 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 VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox 99Minutos é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox 99Minutos > 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, há a linha Product: opencart-shipping-99minutos 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 administrador (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 for alterado, 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 ú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 vibefox.net.
Sem uma chave ativa, o método de envio 99Minutos não é mostrado aos clientes na finalização de compra, e nenhuma tarifa é calculada. Um usuário administrador que esteja conectado ao painel 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 enxerga o login do administrador, por isso, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel. 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 administrador: 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 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 ativado em System > Localisation > Countries. Verifique Geo zone e Restrict countries. Confirme que a Price matrix tem uma linha para esse país ou uma linha * Default, e verifique os limites de peso e o Minimum subtotal. Confirme que os produtos têm Requires Shipping definido como Yes. Os avisos exibidos após Save apontam para configurações que ocultam o método.
O método só aparece depois que um CEP é informado: isso é esperado com uma 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 Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Um erro HTTP 401 ou 403 significa que a API rejeitou a chave: verifique a chave e se Environment corresponde a ela (chaves de sandbox e de produção são diferentes). Use o modo Soft se os clientes devem continuar recebendo o preço da matriz quando a API estiver indisponível.
O preço não é o que você esperava: verifique Calculation (por pedido ou por item) e os pesos e classes de peso dos produtos. Um preço de tamanho vazio ou 0 usa o Base price. Com uma Tax class, 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 da extensão. Isso limpa os resultados de cobertura em cache.
A página diz "Warning: You do not have permission to modify VibeFox 99Minutos!": 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_99minutos (OpenCart 3) ou extension/vfd_99minutos/shipping/vfd_99minutos (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API da 99minutos pode ser substituído pela configuração vfd_99m_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 99Minutos. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable 99Minutos, Sort order, Tax class e Geo zone. Os resultados de cobertura em cache são sempre removidos. Se Remove data on uninstall estiver ativo, as configurações da 99minutos e o log de depuração também são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas 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 99Minutos na lista de extensões instaladas, depois em Delete (o botão vermelho com lixeira) para remover o pacote enviado.
99minutos é uma marca de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela 99minutos.