VibeFox Andreani 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 na Andreani (somente para tarifas em tempo real): as tarifas em tempo real usam a API de cotações da Andreani. A Andreani fornece aos clientes empresariais credenciais de API, um código de cliente e números de contrato, normalmente a partir de cerca de 300 envios por mês. Consulte developers.andreani.com ou escreva para ventapyme@andreani.com. Você precisa do nome de usuário e da senha da API, do código de cliente e do número do contrato. A Andreani emite um contrato separado para cada serviço (entrega em casa, retirada em filial). Sem acesso à API, use preços fixos. O seletor de filial funciona sem credenciais.
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_andreani para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Andreani, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Defina o nome, a origem das tarifas, os preços por país (por exemplo AR=5000) e, para tarifas em tempo real, as credenciais da API, o código de cliente e o número do contrato (veja Configuração).
6. Acesse WooCommerce > Settings > Shipping > Shipping zones, abra ou crie uma zona para a Argentina e adicione VibeFox Andreani. Na janela da zona, você pode definir o título, a modalidade de entrega e um contrato diferente para esta opção. Também é possível ativar Ignore shipping zones e escolher países.
Configuração
As configurações principais ficam em WooCommerce > Settings > Shipping > VibeFox Andreani. Elas valem para todas as zonas de envio. Avisos sobre configurações ausentes (credenciais da API, número do contrato, taxa de câmbio, nenhum preço para a Argentina) aparecem no topo da página. Sempre que você salva as configurações, o token, a lista de filiais e as tarifas em cache são limpos.
Janela da zona (ao adicionar o método a uma zona de envio)
Title: o nome desta opção na finalização de compra. Deixe vazio para usar o Name global.
Delivery modality: Use global setting ou uma das quatro modalidades (veja abaixo). Adicione o método duas vezes a uma zona, por exemplo porta a porta e retirada em filial, para oferecer as duas.
Contract number: o contrato da Andreani para esta opção. Deixe vazio para usar o contrato global.
Geral
Enable/Disable: ativa ou desativa o envio pela Andreani em todas as zonas de uma vez.
Name: o nome do método de envio exibido ao cliente na finalização de compra. Padrão: Andreani.
Tax status: Taxable significa que o WooCommerce adiciona imposto ao custo do envio, então a tarifa da API é usada sem IVA. None significa que a tarifa da API é usada com o IVA incluído.
API Andreani (necessária para tarifas em tempo real)
Environment: Sandbox / QA (apisqa.andreani.com) (padrão) ou Production (apis.andreani.com). Use o ambiente ao qual pertencem as suas credenciais.
API username: o nome de usuário da sua API da Andreani.
API password: a senha da sua API da Andreani.
Client code: o código de cliente fornecido pela Andreani, por exemplo CL0000000.
Contract number: o contrato do serviço usado para as tarifas, por exemplo entrega em casa. Uma zona pode usar outro contrato, por exemplo para a retirada em filial.
Origin branch code: filial de origem opcional (sucursalOrigen) para as cotações de tarifas. Deixe vazio para usar a filial configurada no seu contrato.
Entrega e tarifas
Delivery modality: a primeira parte indica de onde a Andreani retira a encomenda (o seu endereço ou uma filial onde você a deixa). A segunda parte indica onde o cliente a recebe.
Rate source: como o preço é calculado.
Country prices: um preço fixo por país de destino na moeda da sua loja, um por linha no formato CC=PRICE, por exemplo AR=5000. Usado no modo fixo e como alternativa quando a API falha. Linhas em outro formato são ignoradas, e um aviso as lista ao salvar.
ARS exchange rate: a Andreani faz cotações em pesos argentinos. Só é necessário se a moeda da sua loja não for ARS: o preço de 1 ARS na moeda da sua loja, por exemplo 0.001. Sem ele, as tarifas da API não são usadas. Os preços fixos são sempre na moeda da sua loja.
Default product weight (kg): usado para produtos sem peso ao solicitar tarifas da API e verificar os limites de peso. Padrão: 0.5.
Calculation type: Per order cobra o preço uma única vez. Per item (price x number of items) multiplica o preço fixo de Country prices pelo número de itens do carrinho. Uma tarifa em tempo real da Andreani já é para o carrinho inteiro e não é multiplicada.
Disponibilidade
Min weight (kg): o peso mínimo do carrinho para que o método apareça. 0 significa sem limite.
Max weight (kg): o peso máximo do carrinho. O método fica oculto se ele for ultrapassado. Padrão: 100. 0 significa sem limite.
Minimum subtotal: mostra o método somente quando o subtotal do carrinho for pelo menos este valor. Deixe vazio para mostrar sempre.
Excluded shipping classes: se algum item do carrinho pertencer a uma classe de envio selecionada do WooCommerce, o método fica oculto.
Ignore shipping zones: oferece o método para os países abaixo, mesmo sem tê-lo adicionado a uma zona de envio.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Usado somente quando Ignore shipping zones está ativado.
Frete grátis
Free shipping: ativa o limite para frete grátis.
Free shipping from: o subtotal do carrinho a partir do qual o envio é grátis. Requer que Free shipping esteja ativado.
Seletor de filial na finalização de compra (exibido para Door to branch e Branch to branch)
Province select width: a largura CSS da lista de províncias, por exemplo 100% ou 300px. Padrão: 100%.
Branch select width: a largura CSS da lista de filiais, por exemplo 100% ou 400px. Padrão: 100%.
Avançado
Debug log: registra as requisições à API e os cálculos de tarifas em WooCommerce > Status > Logs (origem "vfd-andreani"). Erros são sempre registrados. Credenciais e tokens nunca são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as suas configurações e métodos nas zonas. Desativar nunca apaga nada. Os dados de filial salvos nos pedidos são sempre mantidos.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o plugin verifica o peso do carrinho (os pesos dos produtos são convertidos para kg; produtos sem peso usam Default product weight (kg)), o Minimum subtotal e as Excluded shipping classes.
No modo fixo, o preço é obtido de Country prices. Nos modos em tempo real, o plugin faz login na API da Andreani e solicita uma cotação com o CEP de destino, o contrato, o código de cliente, o peso em kg, o volume calculado a partir das dimensões dos produtos e o valor declarado (o subtotal do carrinho em ARS). Uma tarifa em tempo real só é solicitada para um CEP argentino válido. O valor em ARS é convertido com ARS exchange rate quando a moeda da sua loja não é ARS.
O token de login fica em cache por 23 horas e é renovado automaticamente quando a Andreani o rejeita. As cotações ficam em cache por 1 hora. Uma chamada à API que falhou não é repetida por 5 minutos. Erros da API nunca são mostrados ao cliente: o método fica oculto ou, no modo de alternativa, é usado o preço fixo. O motivo é gravado no log.
Se Free shipping estiver ativado e o subtotal do carrinho atingir Free shipping from, a tarifa é 0. O frete grátis se aplica apenas onde o método tem preço: se a API da Andreani não retornar tarifa (e não houver preço fixo para usar como alternativa), o método não é exibido. Com Per item, o preço fixo é multiplicado pelo número de itens.
O método funciona na finalização de compra clássica e nos blocos de Carrinho e de Finalização de compra. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin não cria envios da Andreani, não imprime etiquetas e não rastreia encomendas. Para isso, use o portal web da Andreani.
Pontos de retirada
Com Door to branch ou Branch to branch, uma lista de províncias e uma lista de filiais aparecem abaixo da opção da Andreani na finalização de compra, tanto na finalização clássica quanto no bloco de Finalização de compra. A província é pré-selecionada a partir do endereço de envio. A lista de filiais vem da API pública de filiais da Andreani e fica em cache por 12 horas. Filiais que não entregam encomendas não aparecem na lista. Se não houver filiais disponíveis, o cliente vê uma mensagem e pode escolher outro método de envio.
O pedido não pode ser feito sem uma filial: o cliente vê Please select an Andreani pickup branch. Isso é verificado no servidor para as duas finalizações de compra.
A filial escolhida é salva no pedido. Na tela de pedidos do administrador, a modalidade e a filial são exibidas abaixo do endereço de envio. Clique em Edit para escolher outra província e filial. O cliente vê a filial como Andreani pickup branch na página do pedido e nos e-mails de pedido (HTML e texto simples). Pedidos existentes mantêm os dados de filial.
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 Andreani. 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 na vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, a Andreani não é exibida aos clientes na finalização de compra. Os gerentes da loja que estiverem logados 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 de Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Andreani 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 endereço do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Verifique se Country prices tem uma linha para o país (para preços fixos ou como alternativa) e confira os limites de peso, o Minimum subtotal e as Excluded shipping classes. Leia os avisos no topo da página de configurações.
As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs (origem "vfd-andreani"). Ele mostra o motivo: credenciais ou número do contrato ausentes, falha no login (usuário, senha ou ambiente incorretos), nenhum CEP argentino válido ainda, nenhuma taxa de câmbio ou um erro HTTP da Andreani. Com Andreani API, fixed price if the API fails, os clientes continuam recebendo o preço fixo enquanto você resolve o problema.
Minha loja não está em pesos argentinos: defina ARS exchange rate com o valor de 1 ARS na moeda da sua loja.
O imposto do envio parece errado: com Tax status em Taxable, é usada a tarifa da Andreani sem IVA e o WooCommerce adiciona o próprio imposto. Com None, é usada a tarifa com IVA e o WooCommerce não adiciona imposto. Se você usar Taxable, confira se os impostos do WooCommerce estão configurados.
Nenhuma filial na lista: a API de filiais da Andreani não respondeu. Uma requisição que falhou é repetida após 5 minutos. Verifique o log.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa o token, a lista de filiais e 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 da 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 e apenas limpa os caches. Para removê-lo, desative-o e exclua-o na página de Plugins. A chave de licença e o status da licença deste plugin, além do token, da lista de filiais e das tarifas em cache, são sempre removidos. Configurações e métodos nas zonas são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os dados de filial salvos nos pedidos nunca são excluídos.
A Andreani é uma marca registrada do respectivo titular. Este plugin não é afiliado nem endossado pela Andreani.