VibeFox Mercado Envios for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

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 na conta. Os pacotes são cotados a partir do endereço de envio configurado nessa conta. Você precisa do Access Token de produção (ele começa com APP_USR-): no painel de desenvolvedores do Mercado Pago, 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 do módulo. Se você usa 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 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, depois, encontre VibeFox Mercado Envios na lista de módulos e clique em Configure.

3. Insira a 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. Para tarifas em tempo real, cole o Access Token, 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). Clique em Save.

Na instalação, o módulo cria a transportadora Mercado Envios com o texto de prazo de entrega Mercado Envios delivery. A transportadora é atribuída a todas as zonas e a todos os grupos de clientes, sem regra de imposto. 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 estão na página do módulo: Modules > Module Manager > VibeFox Mercado Envios > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas do Mercado Envios em cache e o último erro da API.

Os avisos no topo da página mostram problemas de configuração: taxa de câmbio ausente, nenhum access token e nenhum preço, o último erro da API do Mercado Envios com a data, e uma unidade de peso ou de dimensão da loja que o módulo não reconhece (nesse caso ela é lida como kg ou cm). Se a transportadora foi excluída, a seção General informa: The Mercado Envios carrier was not found — reset the module to create it again.

General

Adicione as zonas dos seus clientes à transportadora Mercado Envios em Shipping > Carriers, ou use Ignore shipping zones abaixo. Estas configurações valem para todas as zonas.

Enable Mercado Envios shipping: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Name: o nome da transportadora exibido aos clientes na finalização de compra. Padrão: Mercado Envios. Obrigatório, no máximo 64 caracteres.

Tax: a regra de imposto da transportadora, ou No tax (padrão). O Mercado Envios informa preços finais. No tax os exibe como informados; uma regra de imposto acrescenta o seu imposto de frete por cima.

API do Mercado Envios (tarifas em tempo real) (sem token, somente os preços abaixo são usados)

Access token: o seu Access Token de produção do Mercado Pago (APP_USR-...). Ele é enviado somente para api.mercadopago.com e nunca é registrado em log. Depois de salvar, o campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para deixar de usar tarifas em tempo real, marque Remove the saved access token (only the prices below are used then) e salve.

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 nesse país e são cotadas na moeda dele.

Exchange rate: só é necessária quando a moeda padrão da loja é 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 ela, 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á access token, para destinos fora do país do Mercado Envios e quando a API não retorna nenhuma tarifa. Eles 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 ícone de lixeira para remover 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 aquele peso do carrinho. Uma coluna vazia ou com 0 usa Price. Um Price de 0 significa frete grátis para aquele país. Tanto 9.99 quanto 9,99 são aceitos. Valores que não são números são informados após o salvamento e apagados. Linhas sem nenhum preço são descartadas ao salvar.

Fallback cost: usado quando nem a API nem Country prices fornecem um preço. Deixe vazio para ocultar a transportadora nesse caso.

Calculation type: Per order cobra o preço uma única vez. Per item (each item priced by its own weight x quantity) procura em Country prices (ou no Fallback cost) o preço do peso de cada produto e o multiplica pela quantidade. Se um produto não receber preço, a transportadora fica oculta. As tarifas em tempo real do Mercado Envios são sempre para o pacote inteiro.

Disponibilidade

Min weight: o peso mínimo do carrinho em kg para que esta transportadora apareça. 0 significa sem limite.

Max weight: oculta a transportadora quando o carrinho pesa mais, em kg. Vazio significa 25 kg, 0 significa sem limite. Um Min weight maior que o Max weight é recusado ao salvar.

Minimum subtotal: mostra a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrá-la sempre.

Ignore shipping zones: oferece a transportadora para os países abaixo sem configurar as zonas dela. Ao salvar, a transportadora é adicionada a todas as zonas, e as zonas criadas depois também. Desligar a opção remove as zonas que ela adicionou, e a transportadora mantém as zonas próprias.

Countries: os países de destino para esse modo. Deixe vazio para todos os países ativos da loja. Este campo só é usado quando Ignore shipping zones está ativado.

Frete grátis

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual esta transportadora é gratuita. Nesse caso, nenhuma requisição é feita à API. Deixe vazio para desativar.

Avançado

Debug log: grava as requisições à API e o cálculo das tarifas em logs/vfd_mrcv_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com esta opção desligada. O access token e os endereços dos clientes nunca são registrados.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativada, desinstalar o módulo apaga as configurações, a transportadora, as tarifas em cache e os logs. Quando desativada, tudo é mantido para uma nova instalação.

Como funciona na finalização de compra

No passo de envio, o PrestaShop pede ao módulo o preço do Mercado Envios. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e subtotal mínimo. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição vai ao Mercado Envios.

Para um destino no país do Mercado Envios com um CEP válido, o módulo 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. 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 recebem 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 loja e depois exibida na moeda do carrinho do cliente.

Cada cotação fica em cache por 1 hora, então o mesmo carrinho não gera uma nova requisição. Uma cotação que falhou não é repetida por 5 minutos. Se o Mercado Pago não puder ser acessado, recusar o token ou limitar as requisições, todas as tarifas em tempo real são pausadas por 5 minutos, para que a finalização de compra não espere a 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 CEP 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 de reserva. Se não houver nenhum preço, a transportadora fica oculta. O cliente nunca vê um erro da API.

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 calcula somente tarifas. Ele não cria envios, não imprime etiquetas e não rastreia encomendas. Crie o envio na sua conta do Mercado Libre ou do Mercado Pago. Ele mostra um único preço, a opção mais barata do Mercado Envios, e 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, o módulo guarda o nome do serviço, o prazo de entrega estimado em dias e a tarifa em tempo real. No back office, a página do pedido mostra um bloco Mercado Envios com Mercado Envios service, Estimated delivery e Live rate (excl. tax). O cliente vê Mercado Envios service e Estimated delivery na página de detalhes do pedido da conta dele. Pedidos existentes não são afetados por mudanças posteriores de tarifa.

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 Mercado Envios é o primeiro bloco de Modules > Module Manager > VibeFox Mercado Envios > 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-mercado-envios e o link Manage licenses and domains in your account, que abre a 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 Mercado Envios 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 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, 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

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á 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 avisos no topo da página do módulo, os limites de peso e o Minimum subtotal. A transportadora precisa de um preço: um access token funcionando para endereços no país do Mercado Envios, ou Country prices ou Fallback cost. Além disso, os produtos podem estar limitados a determinadas transportadoras na página do produto.

As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Motivos comuns: sem token, destino fora do país do Mercado Envios, CEP 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 access token é inválido ou expirou. Copie novamente o Access Token de produção no painel de desenvolvedores do Mercado Pago.

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 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 do módulo. Isso limpa as tarifas em cache.

A página diz que a transportadora do Mercado Envios não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Restaure 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 Mercado Envios e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e os dados de serviço salvos dos pedidos são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações e os dados de serviço dos pedidos são mantidos. Ao instalar o módulo novamente, a transportadora volta ao status que tinha antes da desinstalação.

O Mercado Envios e o Mercado Pago são marcas registradas de seus respectivos titulares. Este módulo não é afiliado nem endossado pelo Mercado Envios ou pelo Mercado Pago.