VibeFox Blue Express 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 Blue Express (apenas para tarifas em tempo real): as tarifas em tempo real exigem uma conta de e-commerce da Blue Express e a sua chave de API (x-api-key). Solicite-a à Blue Express: developers.bluex.cl ou gpo.integraciones@bx.cl. O serviço que você usa (EX, PY ou MD) deve estar habilitado no seu contrato com a Blue Express. Se você usar apenas preços fixos, não precisa de chave de API.
Pontos de retirada: o mapa da Blue Express é carregado a partir de widget-pudo.blue.cl no navegador do cliente.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_blue_express para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Blue Express, ou clique em Settings abaixo do nome do plugin na página 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. Informe a chave de API, o serviço, o código do distrito de origem (por exemplo, SCL), a taxa de câmbio CLP se a moeda da sua loja não for o CLP, e os preços fixos (por exemplo, CL=4500). Consulte Configuração.
6. Acesse WooCommerce > Settings > Shipping > Shipping zones e adicione VibeFox Blue Express à sua zona do Chile. Nas configurações do método, escolha o título e o tipo de entrega (entrega em casa ou retirada em um ponto Blue Express). Adicione o método duas vezes para oferecer as duas opções.
Configuração
As configurações principais ficam em WooCommerce > Settings > Shipping > VibeFox Blue Express. Elas valem para todas as zonas de envio. Avisos sobre configurações que ocultariam o método ou a tarifa em tempo real (sem chave de API, sem taxa de câmbio CLP, tabela de preços fixos vazia) aparecem no topo da página. Salvar as configurações limpa o cache.
Janela da zona (ao adicionar o método a uma zona de envio)
Title: o nome do método de envio exibido ao cliente nesta zona. Deixe vazio para usar o Name global.
Delivery type: As in the global settings (padrão), Home delivery ou Pickup at a Blue Express point (PUDO). Adicione o método duas vezes a uma zona para oferecer entrega em casa e retirada.
Geral
Enable/Disable: liga ou desliga o método em todos os lugares, em todas as zonas de envio.
Name: o nome do método de envio exibido na finalização de compra. Uma zona pode definir o próprio título. Padrão: Blue Express.
Tax status: os preços da Blue Express incluem IVA. Escolha None se o WooCommerce não deve acrescentar imposto por cima, ou Taxable se deve.
API Blue Express (necessária para tarifas em tempo real)
API key: a sua chave de API da Blue Express (cabeçalho x-api-key). Sem ela, apenas os preços fixos são usados.
Service: o serviço da Blue Express usado para a tarifa: Express (EX) (padrão), Prioritario (PY) ou SameDay (MD). Deve estar habilitado no seu contrato com a Blue Express.
Origin district code: o código de distrito da Blue Express do local de onde você envia, por exemplo SCL para Santiago (padrão). Em caso de dúvida, pergunte à Blue Express.
CLP per 1 (your currency): os preços da Blue Express são em pesos chilenos (CLP). Se a sua loja usa outra moeda, informe quantos CLP vale uma unidade dela, por exemplo 1050. Sem esse valor, as tarifas em tempo real não são usadas. É ignorado quando a moeda da loja é o CLP.
Preço
Rate source: como o preço é calculado.
Fixed prices: uma linha por país no formato COUNTRY_CODE=PRICE, na moeda da sua loja, por exemplo CL=4500 em uma loja em CLP ou CL=4.50 em uma loja em EUR. Vírgula ou ponto são aceitos como separador decimal. Linhas inválidas são informadas ao salvar. Os preços fixos podem ser usados para qualquer país.
Fixed price per: Order cobra o preço uma vez. Item (price x quantity) multiplica o preço pelo número de itens no carrinho. Isso vale apenas para o preço fixo. A tarifa da API sempre se refere à encomenda inteira.
Condições
Min weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.
Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 100. 0 significa sem limite.
Minimum order subtotal: mostra o método somente a partir deste subtotal do carrinho (moeda da loja). Deixe vazio para mostrá-lo sempre.
Excluded shipping classes: se algum item do carrinho pertencer a uma classe de envio do WooCommerce selecionada, o método fica oculto.
Frete grátis
Free shipping: ativa o frete grátis a partir de um subtotal do carrinho.
Free from subtotal: o subtotal do carrinho (moeda da loja) a partir do qual o envio é gratuito.
Retirada em pontos Blue Express (PUDO)
Pickup point by default: quando ativado, os métodos Blue Express entregam em um ponto Blue Express escolhido pelo cliente. Este é o padrão para métodos de zona com Delivery type = As in the global settings. O cliente precisa escolher um ponto para concluir o pedido.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o método mesmo quando ele não foi adicionado à zona de envio correspondente. Nesse caso, usa as configurações globais (sem título de zona nem tipo de entrega).
Countries: os países de destino para este modo. Deixe vazio para usar todos os países para os quais você envia. Usado apenas com Ignore shipping zones.
Avançado
Debug log: registra solicitações e decisões em WooCommerce > Status > Logs, origem "vfd-blue-express". Erros da API são sempre registrados. A chave de API e os endereços dos clientes nunca são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove as suas configurações e os métodos de zona. Desativar nunca apaga as configurações. Os pontos de retirada salvos nos pedidos são mantidos.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o plugin verifica o peso do carrinho, o Minimum order subtotal e as Excluded shipping classes. Se o frete grátis se aplicar, a tarifa é 0 e nenhuma solicitação é enviada à Blue Express.
Para uma tarifa em tempo real, o endereço precisa estar no Chile, com região e cidade (comuna). O plugin primeiro pede à Blue Express que reconheça a comuna e depois solicita o preço para o serviço, o distrito de origem, o destino e as encomendas. Cada produto é enviado com peso e dimensões convertidos para kg e cm. Produtos sem peso ou tamanho são enviados como 0,01 kg, 10 x 10 x 10 cm. O valor declarado é enviado em CLP. O preço em CLP é convertido para a moeda da sua loja.
As tarifas ficam em cache por 1 hora e os dados das comunas por 12 horas. Uma chamada à API que falhou fica registrada por 5 minutos, e o tempo limite é de 10 segundos, para que uma API lenta ou indisponível não atrase cada atualização da finalização de compra. Erros da API nunca são mostrados ao cliente: o método fica oculto ou, no modo de alternativa, usa-se o preço fixo. O motivo é gravado no log.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalizar compra. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin não cria envios nem etiquetas na Blue Express, não atribui números de rastreamento e não exibe atualizações de rastreamento. Crie o envio na sua conta da Blue Express. Não existem tabelas de tarifas regionais por comuna: use a tarifa da API da Blue Express ou um preço fixo por país. As tarifas em tempo real funcionam somente para o Chile.
Pontos de retirada
Com o tipo de entrega Pickup at a Blue Express point (PUDO), o cliente vê Choose pickup point abaixo da opção Blue Express, tanto na finalização de compra clássica quanto na de blocos. O botão abre o mapa oficial da Blue Express, onde o cliente escolhe um ponto. O ponto escolhido é exibido com nome e endereço, e o botão muda para Change pickup point. Em seguida, a tarifa é recalculada com o preço de retirada Blue Express (PUDO).
O pedido não pode ser concluído sem um ponto: o cliente vê Please choose a Blue Express pickup point. Isso é verificado no servidor.
O ponto escolhido é salvo no pedido com o código de agência, o nome e o endereço da Blue Express. Na tela de pedido do administrador, ele aparece abaixo do endereço de entrega como Blue Express pickup point. Clique em Edit para escolher outro ponto no mapa da Blue Express ou para informar à mão o código de agência, o nome e o endereço, e depois clique em Save pickup point. A alteração é registrada em uma nota do pedido. O cliente vê o ponto na página do pedido e nos e-mails de pedido (HTML e texto simples). Os e-mails enviados à loja também mostram o código de agência. Pedidos já existentes mantêm os dados do ponto de retirada.
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 Blue Express. 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 de novo, 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 domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Blue Express 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, automaticamente, em segundo plano.
Solução de problemas
A Blue Express não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do endereço do cliente (ou se Ignore shipping zones está ligado e o país é permitido). Leia os avisos no topo da página de configurações. Confira os limites de peso, o Minimum order subtotal e as Excluded shipping classes, e se Fixed prices tem uma linha para o país, caso você use preços fixos ou a alternativa.
As tarifas em tempo real não aparecem: com Blue Express API only, o método fica oculto quando não há tarifa. Ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs (origem "vfd-blue-express"). Motivos comuns: falta a chave de API, a moeda da loja não é CLP sem taxa de câmbio, região ou comuna ausente no endereço, comuna não reconhecida pela Blue Express ou erro da API (por exemplo HTTP 401 ou 403 quando a chave de API é rejeitada). Com Blue Express API, fixed price if the API gives no rate, os clientes continuam recebendo o preço fixo enquanto você corrige o problema.
O imposto é acrescentado sobre o preço da Blue Express: os preços da Blue Express incluem IVA. Defina Tax status como None se o WooCommerce não deve acrescentar imposto por cima.
O mapa não abre: o mapa é carregado a partir de widget-pudo.blue.cl no navegador do cliente, então esse endereço precisa estar acessível e não bloqueado no seu site.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as tarifas e os dados das comunas 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 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 limpa apenas o cache. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença, o status da licença deste plugin e o cache são sempre removidos. Configurações e métodos de zona são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pontos de retirada salvos nos pedidos nunca são removidos.
A Blue Express é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Blue Express.