VibeFox Envioclick for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não ativa sem ele.

PHP: 8.0 ou superior.

Conta na Envioclick (somente para tarifas em tempo real): uma conta na Envioclick no México ou na Colômbia com acesso à API. A chave de API está na sua conta da Envioclick, em Mi cuenta (no canto superior direito) > Información del API. Se você usa apenas preços fixos, não precisa de conta na Envioclick.

User-Agent (somente México): a Envioclick México exige um valor de User-Agent em cada requisição à API. Solicite-o ao suporte da Envioclick (soporte.tecnico@envioclick.com).

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_envioclick para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Envioclick, 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. Insira a chave de API, escolha o país da API, informe o User-Agent (México), o código postal ou o código DANE de origem e o endereço de origem. Se a moeda da sua loja não for MXN ou COP, informe a taxa de conversão.

6. Opcionalmente, adicione preços fixos por país e um custo alternativo.

7. Adicione VibeFox Envioclick 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 Envioclick. 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 que os clientes veem nesta zona. Deixe vazio para usar o Method title global.

Quando uma chave de API está definida, o plugin mostra avisos no topo da página se as tarifas em tempo real não puderem funcionar: sem taxa de conversão para uma moeda da loja diferente de MXN ou COP, sem User-Agent para o México, sem código postal ou código DANE de origem, ou sem endereço de origem para a Colômbia. Sempre que você salva as configurações, as cotações em cache são apagadas. Os campos numéricos aceitam tanto ponto quanto vírgula como separador decimal.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas ao mesmo tempo. Padrão: ativado.

Method title: o nome do método de envio exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: Envioclick Shipping.

Carrier in the title: exibe a transportadora e o prazo de entrega estimado ao lado do título nas tarifas em tempo real, por exemplo “Envioclick Shipping (Estafeta Express, 1 day)”. A transportadora é salva no pedido e exibida nos e-mails de pedido de qualquer forma. Padrão: ativado.

API Envioclick (tarifas em tempo real)

Opcional. Sem chave de API, apenas os preços fixos são usados. As tarifas em tempo real são solicitadas somente para destinos no país da API. Envios para outros países usam os preços fixos.

API key: sua chave de API da Envioclick, em Mi cuenta > Información del API.

API country: o país da sua conta na Envioclick.

User-Agent (México): o valor emitido pelo suporte da Envioclick (soporte.tecnico@envioclick.com). Obrigatório para o México; sem ele, as tarifas em tempo real para o México não são solicitadas. Opcional para a Colômbia.

Escolha da transportadora: Cheapest (padrão) ou Fastest (then cheapest). A Envioclick retorna cotações de várias transportadoras, e o cliente recebe uma única tarifa.

Branch pickup rates: considera também as tarifas “Ocurre”, nas quais o cliente retira o pacote na agência da transportadora. Quando desativado, somente as tarifas de entrega em domicílio são usadas. Serviços de pagamento na entrega (COD) nunca são usados. Padrão: desativado.

Currency conversion rate: a Envioclick cota em MXN (México) ou COP (Colômbia). Se a moeda da sua loja for outra, informe o valor de 1 MXN ou 1 COP na moeda da loja, por exemplo 0.05. O valor declarado do pacote é convertido da mesma forma. Deixe vazio se a moeda da loja for MXN ou COP. Sem ela, as tarifas em tempo real não são usadas em outra moeda.

Origem do envio

Usado para as tarifas em tempo real. Os campos vazios são preenchidos com o endereço da loja em WooCommerce > Settings > General, se a loja estiver no país da API.

Origin postcode / DANE code: México: o código postal de 5 dígitos. Colômbia: o código DANE de 8 dígitos do município, por exemplo 11001000 para Bogotá.

Origin address: rua e número do endereço de coleta. Obrigatório para a Colômbia, opcional para o México.

Preços fixos

Usados quando não há tarifa em tempo real: sem chave de API, destino fora do país da API, erro da API ou nenhuma transportadora para a rota.

Price per country: uma tabela de países e preços na moeda da loja. Clique em + Add country para adicionar uma linha e no X para remover uma. A linha * Default se aplica a todos os países sem linha própria.

Fallback cost: usado quando não há tarifa em tempo real e nenhuma linha da tabela corresponde. Deixe vazio para ocultar o método nesse caso.

Fixed price applies: Per order cobra o preço uma vez. Per item (price × quantity) multiplica pelo número de itens no carrinho. As tarifas em tempo real da Envioclick são sempre por envio.

Condições

Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite.

Maximum weight (kg): oculta o método acima deste peso do carrinho. Padrão: 25. 0 significa sem limite.

Minimum order amount: exibe o método somente se o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para exibir sempre.

Free shipping from: frete grátis quando o subtotal do carrinho (após descontos, antes dos impostos) atingir este valor. Nenhuma requisição é feita à API nesse caso. Deixe vazio para nunca oferecer frete grátis.

Excluded shipping classes: oculta o método se o carrinho contiver um produto de qualquer uma destas classes de envio do WooCommerce.

Tax status: Taxable adiciona o imposto do WooCommerce ao custo de envio; None não adiciona. As cotações da Envioclick já incluem os impostos das transportadoras, então escolha None para não cobrar imposto sobre o envio duas vezes.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece a Envioclick para os países listados abaixo, mesmo que ela não tenha sido adicionada a uma zona de envio.

Countries: os países de destino para este modo. Deixe vazio para usar todos os países para os quais você envia. Usado somente quando Ignore shipping zones está ativado.

Avançado

Debug log: registra os cálculos de tarifas e os erros da API em WooCommerce > Status > Logs, origem vfd_envioclick. A chave de API e os endereços dos clientes não são registrados. Desative quando terminar.

Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações da Envioclick, os métodos de zona e as cotações em cache. Desativar o plugin nunca apaga as configurações.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro o peso do carrinho, o valor mínimo do pedido e as classes de envio excluídas. Se o frete grátis se aplicar, o método é exibido com preço zero e nenhuma requisição é enviada à Envioclick.

Se houver uma chave de API e o destino estiver no país da API, o plugin pede cotações à Envioclick. No México, a requisição é feita assim que o cliente informa um código postal de 5 dígitos. Na Colômbia, é feita quando o departamento e o município são reconhecidos (acentos e maiúsculas não fazem diferença, “Bogotá D.C.” funciona). O plugin escolhe a cotação de entrega em domicílio mais barata ou mais rápida que não seja pagamento na entrega e a converte para a moeda da sua loja.

O pacote é sempre uma caixa só: o peso total convertido em kg e o comprimento e a largura do item maior, com uma altura que comporta o volume total de todos os itens. Produtos sem dimensões são considerados 10 × 10 × 10 cm. Um carrinho sem peso é enviado como 0,5 kg. O valor declarado é o subtotal do carrinho.

Cada cotação fica em cache por 1 hora para a mesma rota e o mesmo pacote. Uma requisição com falha fica em cache por 10 minutos, para que uma API indisponível não atrase cada atualização da finalização de compra. O tempo limite da API é de 10 segundos. Se a Envioclick retornar erro ou não houver transportadora para a rota, o cliente não vê erro algum: o preço fixo é usado ou o método é ocultado. O motivo é registrado no log de depuração.

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 apenas calcula tarifas. Ele não cria guias ou etiquetas, não solicita coletas e não rastreia nem cancela envios. Oferece uma tarifa, não uma escolha entre transportadoras, e não usa serviços de pagamento na entrega, seguros extras nem cotações para vários pacotes. As cotações em tempo real são somente nacionais.

Pedidos

Quando um pedido é feito com uma tarifa em tempo real da Envioclick, a transportadora e o serviço são salvos no pedido. A tela de pedidos do administrador mostra Envioclick carrier com o prazo de entrega estimado abaixo do endereço de entrega. A página de pedido do cliente e os e-mails de pedido (HTML e texto simples) mostram Shipping carrier. O ID da tarifa Envioclick da cotação é armazenado com a linha de envio do pedido como dado oculto; ele não aparece na tela do pedido. Crie a guia na sua conta da Envioclick.

Pedidos feitos com preço fixo não têm transportadora.

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 Envioclick. 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em 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 em vibefox.net.

Sem uma chave ativa, a Envioclick não é exibida aos clientes na finalização de compra. Os gerentes 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 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 renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A Envioclick 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 país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Confira os limites de peso, Minimum order amount e Excluded shipping classes. Sem tarifa em tempo real, o método precisa de um preço fixo para o país, de uma linha * Default ou de um Fallback cost.

As tarifas em tempo real não aparecem: leia os avisos no topo da página de configurações, depois ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd_envioclick. Motivos comuns: sem taxa de conversão (a moeda da loja não é MXN nem COP), sem User-Agent (México), sem código postal ou código DANE de origem, código postal do cliente (México) ou cidade (Colômbia) ainda não informados, destino fora do país da API ou nenhuma transportadora para a rota.

Por que uma taxa de conversão? A Envioclick retorna preços somente em pesos mexicanos ou colombianos. O plugin nunca exibe um valor em pesos como se fosse outra moeda.

Colômbia: a cidade não é reconhecida: o cliente deve escolher o departamento e digitar o nome do município. Um código DANE de 8 dígitos digitado no campo de código postal também funciona. Desenvolvedores podem fornecer um código DANE com o filtro vfd_evc_dane_code.

O imposto é cobrado duas vezes no envio: as cotações da Envioclick já incluem os impostos das transportadoras. Defina Tax status como None.

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

Filtros para desenvolvedores: vfd_evc_quotation_request (corpo da requisição), vfd_evc_api_url, vfd_evc_dane_code, vfd_evc_default_dimensions e vfd_evc_package_description.

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 todas as configurações e os métodos de zona; apenas as cotações em cache são apagadas. 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. Configurações, métodos de zona e cotações em cache são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação posterior. A transportadora salva em pedidos antigos é mantida, e os pedidos existentes continuam com suas linhas de envio.

A Envioclick é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Envioclick.