VibeFox Mercado Envios for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Conta do Mercado Pago (apenas 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 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 dela. Não há botão de login: você cola o token nas configurações. 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

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_mercado_envios para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Mercado Envios, 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. Para as tarifas em tempo real, cole o Access Token, escolha o país do Mercado Envios e, se a moeda da sua loja não for ARS, BRL ou MXN, informe a taxa de câmbio. Opcionalmente, preencha Country prices e Fallback cost (usados sem tarifas em tempo real).

6. Adicione o VibeFox Mercado Envios a uma zona de envio em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox Mercado Envios. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome desta opção no checkout. Deixe em branco para usar o Name geral.

Os avisos no topo da página mostram problemas de configuração: taxa de câmbio ausente, nenhum access token e nenhum preço, e o último erro da API do Mercado Envios com a data. Sempre que você salvar as configurações, as tarifas em cache são apagadas.

Geral

Enable/Disable: ativa ou desativa o envio pelo Mercado Envios em todas as zonas de uma vez.

Name: o nome do método de envio exibido aos clientes no checkout. Padrão: Mercado Envios.

Tax status: o Mercado Envios informa preços finais. None os exibe como informados; Taxable soma por cima o imposto de envio do WooCommerce.

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

Access token: o seu Access Token de produção do Mercado Pago (APP_USR-...). Ele é enviado somente ao Mercado Pago e nunca é registrado no log.

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 apenas para destinos desse país e são cotadas na moeda dele.

Exchange rate: só é necessário quando a moeda da loja é diferente da moeda do Mercado Envios: o preço de 1 ARS, BRL ou MXN na moeda da loja, por exemplo 0.001. Sem ele, as tarifas em tempo real não são usadas. 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.

Country prices: preços na moeda da loja. Clique em + Add country para adicionar uma linha e no X para remover uma. Escolha * All other countries para todos os países sem 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 igual a 0 usa o Price. 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 o Country prices fornecem um preço. Deixe em branco para ocultar o método nesse caso.

Calculation type: Per order cobra o preço uma única vez. Per item (each item priced by its own weight x quantity) busca em Country prices (ou no Fallback cost) o preço para o peso de cada item e o multiplica pela quantidade. 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.

Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 25. 0 significa sem limite.

Minimum subtotal: exibe o método somente quando o subtotal do carrinho é pelo menos este valor. Deixe em branco para exibi-lo sempre.

Excluded shipping classes: oculta o método quando algum item do carrinho pertence a uma destas classes de envio do WooCommerce.

Ignore shipping zones: oferece o método para os países indicados abaixo, mesmo sem tê-lo adicionado a uma zona de envio.

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

Frete grátis

Free shipping from: o subtotal do carrinho a partir do qual este método é grátis. Nesse caso, nenhuma requisição é enviada ao Mercado Envios. Deixe em branco para desativar.

Avançado

Debug log: registra as requisições à API e o cálculo das tarifas em WooCommerce > Status > Logs (origem vfd-mercado-envios). Os erros são sempre registrados, mesmo com esta opção desativada. O access token e os endereços dos clientes nunca são registrados.

Remove data on uninstall: quando ativada, excluir o plugin remove todas as suas configurações e os métodos das zonas. Desativar o plugin nunca apaga as configurações.

Como funciona no checkout

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: peso do carrinho, subtotal mínimo e classes de envio excluídas. Se o frete grátis se aplicar, o método custa 0 e nenhuma requisição é enviada ao Mercado Envios.

Para um destino no país do Mercado Envios com um CEP válido, o plugin descreve o carrinho como um único pacote: a maior largura e o maior comprimento dos itens, a soma das alturas de todos os itens e o peso total em gramas. Cada lado e o peso são elevados aos mínimos do Mercado Envios para o 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 da loja e exibida com o nome do seu método.

Cada cotação fica em cache por 1 hora, para que o mesmo carrinho não gere uma nova requisição. Uma cotação que falhou não é repetida por 5 minutos. Se o Mercado Pago não puder ser acessado ou rejeitar o token, todas as cotações em tempo real são pausadas por 5 minutos, para que o checkout não espere pela API a cada atualização. O timeout 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 não é válido, a taxa de câmbio está ausente, o pacote excede o limite de peso do Mercado Envios do país (25 kg na Argentina, 15 kg no Brasil, 30 kg no México), ou o Mercado Envios retorna um erro ou nenhuma opção para o endereço. Usa-se a linha do país (ou a linha *) e, se não houver, o custo de reserva. Se não houver preço algum, o método fica oculto. O cliente nunca vê um erro da API.

O método funciona no checkout clássico e nos blocos de Carrinho e de Finalização de compra. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin calcula apenas as 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 uma tarifa por método, 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 o pedido é feito com uma tarifa em tempo real, o nome do serviço e o prazo de entrega estimado em dias são salvos na linha de envio do pedido como Mercado Envios service e Estimated delivery. Os pedidos existentes mantêm suas linhas de envio.

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 Mercado Envios. 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 no vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta no vibefox.net.

Sem uma chave ativa, o Mercado Envios não é exibido aos clientes no checkout. Os gerentes da loja que estiverem logados ainda o veem, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete 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 a renovação. O status é verificado novamente em segundo plano, automaticamente.

Solução de problemas

O Mercado Envios não aparece no checkout: verifique se a licença está ativa, se o Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se o Ignore shipping zones está ativado e o país é permitido). Confira os avisos no topo da página de configurações, os limites de peso, o Minimum subtotal e as Excluded shipping classes. O método precisa de um preço: um access token válido para endereços no país do Mercado Envios, ou então Country prices ou Fallback cost.

As tarifas em tempo real não aparecem: ative o Debug log, recarregue o checkout e abra WooCommerce > Status > Logs, origem vfd-mercado-envios. 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 ao Mercado Envios country. Escolha o país da sua conta do Mercado Pago.

Em qual moeda estão os preços: Country prices e Fallback cost estão na moeda da loja. As tarifas em tempo real chegam na moeda da sua conta do Mercado Pago e são convertidas com o Exchange rate quando a loja usa outra moeda.

As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as tarifas em cache.

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 do 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 puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todas as configurações. Apenas o cache de tarifas é limpo. 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, as tarifas em cache e o último erro da API são sempre removidos. As configurações e os métodos das zonas são removidos somente se a opção Remove data on uninstall estava ativada. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas linhas de envio.

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