VibeFox Mercado Envios for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superiores (testado na 4.1.0.3).
PHP: 8.0 ou superior.
Conta do Mercado Pago (somente para tarifas em tempo real): as tarifas em tempo real vêm da calculadora do Mercado Envios da sua conta do Mercado Pago na Argentina, no Brasil ou no México. O Mercado Envios precisa estar ativado para a conta. Os pacotes são cotados a partir do endereço de envio configurado nessa conta. Você precisa do token de acesso de produção (ele começa com APP_USR-): no Mercado Pago Developers, abra a sua aplicação e as credenciais de produção. Não há botão de login: você cola o token nas configurações da extensão. Se você usar apenas preços por país, não precisa de uma conta do Mercado Pago.
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 do OpenCart 3 vfd_mercado_envios-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_mercado_envios.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 admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_mercado_envios-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. Encontre VibeFox Mercado Envios 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. Insira a sua chave de licença 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. Para tarifas em tempo real, cole o token de acesso, escolha o país do Mercado Envios e, se a moeda padrão da sua loja não for ARS, BRL ou MXN, a taxa de câmbio. Opcionalmente, preencha Country prices e Fallback cost (usados sem tarifas em tempo real). Ative Enable Mercado Envios shipping e clique em Save.
OpenCart 4
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_mercado_envios.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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 Mercado Envios, clique em Install (o botão verde +) e depois em Edit (o botão com o 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 Mercado Envios shipping e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações mantidas voltam a ser usadas.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas em cache do Mercado Envios e o último erro da API. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.
Os avisos na seção General (e após cada salvamento) mostram problemas de configuração: taxa de câmbio ausente, nenhum token de acesso e nenhum preço (então o método nunca é exibido), o último erro da API do Mercado Envios com a data, e uma unidade de peso ou de comprimento da loja que a extensão não reconhece (ela é então lida como kg ou cm). Se Name estiver vazio ou tiver mais de 64 caracteres, se Exchange rate não for um número positivo, se outro campo numérico não for um número igual ou maior que 0, ou se Min weight for maior que Max weight, a página mostra um erro e nada é salvo.
Geral
O cliente vê uma única tarifa do Mercado Envios. Você pode limitar o método a uma zona geográfica ou a países em Availability. Essas configurações valem para todas as zonas.
Enable Mercado Envios shipping: mostra ou oculta o Mercado Envios na finalização de compra. Padrão: desativado.
Name: o nome do método de envio mostrado aos clientes no carrinho e na finalização de compra. Padrão: Mercado Envios. Obrigatório, no máximo 64 caracteres.
Tax class: a classe de imposto do custo do frete, ou No tax (padrão). O Mercado Envios informa preços finais. No tax os mostra como informados; uma classe de imposto acrescenta por cima o imposto de frete da sua loja.
Sort order: a posição do Mercado Envios entre os métodos de envio na finalização de compra. Um número inteiro.
API do Mercado Envios (tarifas em tempo real) (sem token, somente os preços abaixo são usados)
Access token: o seu token de acesso de produção do Mercado Pago (APP_USR-...). Ele é enviado somente para api.mercadopago.com e nunca é registrado em log. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente para alterá-lo.
Remove the saved access token: ative e salve para excluir o token salvo. Somente os preços abaixo são usados então. Em vez disso, um token digitado acima substitui o salvo.
Mercado Envios country: o país da sua conta do Mercado Pago: Argentina (ARS) (padrão), Brazil (BRL) ou Mexico (MXN). As tarifas em tempo real são solicitadas somente para destinos desse país e cotadas na moeda dele.
Exchange rate: necessário somente quando a moeda padrão da loja for diferente da moeda do Mercado Envios: o preço de 1 ARS, BRL ou MXN na moeda padrão da loja, por exemplo 0.001. Sem ele, as tarifas em tempo real não são usadas. Deve ser um número positivo. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Preços sem tarifas em tempo real
Esses preços são usados quando não há token de acesso, para destinos fora do país do Mercado Envios e quando a API não fornece tarifa (uma requisição com falha é repetida após 5 minutos). Estão na moeda padrão da loja, sem impostos.
Country prices: uma tabela de países de destino e preços. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. Escolha * All other countries para todos os países que não têm linha própria. Price é o preço do país. As colunas XS (até 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) e XL (acima de 5 kg) o substituem para esse peso do carrinho. Uma coluna vazia ou 0 usa Price. Um Price de 0 significa frete grátis para esse país. Tanto 9.99 quanto 9,99 são aceitos. Valores que não são números são informados após salvar e apagados. Linhas sem nenhum preço são removidas ao salvar.
Fallback cost: usado quando nem a API nem Country prices fornecem um preço. Deixe vazio para ocultar o método nesse caso.
Calculation type: Per order (padrão) cobra o preço uma vez. Per item (each item priced by its own weight x quantity) busca em Country prices (ou no Fallback cost) o valor para o peso de cada produto e o multiplica pela quantidade. Se um produto não obtiver preço, o método fica oculto. As tarifas em tempo real do Mercado Envios sempre valem para o pacote inteiro.
Disponibilidade
Min weight (kg): o peso mínimo do carrinho para que este método apareça. 0 significa sem limite (padrão).
Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 25. Vazio significa 25 kg, 0 significa sem limite.
Minimum subtotal: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) é pelo menos este valor. Deixe vazio para sempre mostrar.
Geo zone: oferece o Mercado Envios somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. A zona geográfica não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore shipping zones: oferece o método para os países abaixo, independentemente da zona geográfica selecionada.
Countries: os países de destino para esse modo. Deixe vazio para todos os países ativados da loja. Este campo é usado somente quando Ignore shipping zones está ativado.
Frete grátis
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual este método é gratuito. Nenhuma requisição à API é feita nesse caso. Deixe vazio para desativar.
Avançado
Debug log: grava as requisições à API e o cálculo das tarifas em storage/logs/vfd_mrcv_debug.log.php (no OpenCart 4, system/storage/logs/vfd_mrcv_debug.log.php). O arquivo não pode ser lido pela web. Erros são sempre registrados, mesmo com esta opção desativada. O token de acesso e os endereços dos clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_mrcv_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 esvaziá-lo.
Remove data on uninstall: quando ativado, ao desinstalar a extensão as configurações e o log são excluídos. Quando desativado (padrão), eles são mantidos para uma reinstalação. As tarifas em cache são sempre removidas. Os dados do Mercado Envios dos pedidos feitos são sempre mantidos como histórico de pedidos.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O token de acesso não é exportado.
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. O token de acesso salvo é mantido.
Como funciona na finalização de compra
Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço do Mercado Envios. Se uma Geo zone estiver definida e o endereço estiver fora dela, o Mercado Envios não é oferecido (a menos que Ignore shipping zones esteja ativado; nesse caso, Countries decide). Somente produtos com Requires Shipping definido como Yes contam: outros produtos não somam peso e não entram no subtotal. A extensão então verifica o peso do carrinho e o subtotal mínimo. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vale-presente, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada ao Mercado Envios.
Para um destino no país do Mercado Envios com um código postal válido (4 dígitos na Argentina, também de um CPA como C1425ABC; 8 dígitos no Brasil; 5 dígitos no México), a extensão descreve o carrinho como um único pacote: a maior largura e o maior comprimento dos produtos, a soma das alturas de todos os produtos e o peso total em gramas. Pesos e dimensões dos produtos são convertidos a partir das suas classes de peso e comprimento do OpenCart. Cada lado e o peso são elevados aos mínimos do Mercado Envios do país, de modo que produtos sem dimensões ou peso também recebam uma tarifa. O valor do carrinho é enviado como preço do item na moeda do Mercado Envios. A opção mais barata retornada pelo Mercado Envios é convertida para a moeda padrão da sua loja, arredondada para as suas casas decimais e exibida na moeda do cliente com o imposto da Tax class selecionada.
Cada cotação fica em cache por até 1 hora (não mais que a duração do cache do OpenCart), para que o mesmo carrinho não dispare uma nova requisição. Uma cotação com falha não é repetida por 5 minutos. Se o Mercado Pago não puder ser acessado, rejeitar o token, limitar as requisições ou responder em outra moeda, todas as cotações em tempo real são pausadas por 5 minutos, para que a finalização de compra não espere pela API a cada atualização. O tempo limite da API é de 10 segundos.
Os preços sem tarifas em tempo real são usados no lugar quando não há token, o destino está fora do país do Mercado Envios, o código postal está ausente ou é inválido, a taxa de câmbio está ausente, o pacote é mais pesado que o limite do Mercado Envios do país (25 kg na Argentina, 15 kg no Brasil, 30 kg no México), ou o Mercado Envios retorna erro ou nenhuma opção para o endereço. Usa-se a linha do país (ou a linha *), senão o custo alternativo. Se não houver preço, o método fica oculto. O cliente nunca vê um erro da API.
No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe o Mercado Envios na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
A extensão calcula somente tarifas. Ela não cria envios, não imprime etiquetas nem rastreia pacotes. Crie o envio na sua conta do Mercado Libre ou do Mercado Pago. Ela mostra um único preço, a opção mais barata do Mercado Envios, não uma escolha entre todas as opções, e não tem seletor de ponto de retirada (agência).
Pedidos
Quando um pedido é feito com uma tarifa em tempo real do Mercado Envios, a extensão guarda o nome do serviço, o prazo estimado de entrega em dias e a tarifa em tempo real. Em Sales > Orders, a página do pedido mostra um bloco Mercado Envios com Mercado Envios service, Estimated delivery e Live rate (excl. tax). O bloco é exibido mesmo que o método seja desativado depois. Um cliente cadastrado vê Mercado Envios service e Estimated delivery abaixo do método de envio na página de pedido da conta dele, e as mesmas linhas são adicionadas ao e-mail de novo pedido. Pedidos feitos com preço de tabela ou com o custo alternativo não têm serviço. Pedidos já existentes não são afetados por mudanças posteriores de tarifas.
No OpenCart 4, o bloco Mercado Envios é exibido acima de History. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo: o serviço salvo é atualizado junto, e é removido quando o cliente troca para outro método de envio ou quando o pedido recebe um preço de tabela ou o custo de contingência.
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 Mercado Envios é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit, 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 estão a linha Product: opencart-shipping-mercado-envios e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão de modificação 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 com 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, 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 de domínio dela. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o Mercado Envios não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin 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 admin, 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 do admin ou a página Edit: 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
O Mercado Envios não aparece na finalização de compra: verifique se a licença está ativa e se Enable Mercado Envios shipping está ativado. Verifique Geo zone, ou ative Ignore shipping zones e verifique Countries. Verifique os avisos na página da extensão, os limites de peso e Minimum subtotal. O método precisa de um preço: um token de acesso válido para endereços no país do Mercado Envios, ou Country prices ou Fallback cost. Verifique se os produtos têm Requires Shipping definido como Yes.
As tarifas em tempo real não aparecem: ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Motivos comuns: sem token, destino fora do país do Mercado Envios, código postal ausente ou inválido, Exchange rate ausente, pacote acima do limite de peso ou nenhuma opção do Mercado Envios para o endereço.
HTTP 401 ou 403 nos avisos: o token de acesso é inválido ou expirou. Copie novamente o Access Token de produção no Mercado Pago Developers.
O Mercado Envios respondeu em outra moeda: o país da conta não corresponde a Mercado Envios country. Escolha o país da sua conta do Mercado Pago.
Em qual moeda estão os preços: Country prices, Fallback cost e os limites estão na moeda padrão da sua loja. As tarifas em tempo real chegam na moeda da sua conta do Mercado Pago e são convertidas com Exchange rate quando a loja usa outra moeda padrão.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as tarifas em cache.
A página mostra "Warning: You do not have permission to modify VibeFox Mercado Envios!": o 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_mercado_envios (OpenCart 3) ou extension/vfd_mercado_envios/shipping/vfd_mercado_envios (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API do Mercado Envios pode ser substituído pela configuração vfd_mrcv_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 Mercado Envios. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Mercado Envios shipping, Sort order, Tax class e Geo zone. As tarifas em cache e o último erro da API 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 voltam a ser usados quando você instalar a extensão novamente. Os dados do Mercado Envios dos pedidos feitos são sempre mantidos, e 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, depois da desinstalação acesse Extensions > Installer e clique em Uninstall (o botão laranja −) ao lado de VibeFox Mercado Envios na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
O Mercado Envios e o Mercado Pago são marcas registradas de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pelo Mercado Envios ou pelo Mercado Pago.