VibeFox Instabee 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.

Credenciais da API Budbee (somente para a seleção de caixa): uma chave de API e um segredo de API. A Instabee as emite para comerciantes com contrato de entrega. Peça ao seu contato na Instabee ou use o portal do comerciante da Instabee. A documentação da API está em developer.budbee.com. Sem credenciais, o método continua funcionando com preços fixos, mas os clientes não escolhem uma caixa.

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Instabee, 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. Preencha a seção Preços e, para o seletor de caixa, a sua API key e o seu API secret da Budbee (veja Configuração).

6. Adicione VibeFox Instabee às zonas de entrega dos países em que você entrega (por exemplo, Suécia) em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox Instabee. Elas valem para todas as zonas de entrega. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:

Title: o nome desta tarifa na finalização de compra nesta zona. Deixe vazio para usar o Method name global.

Os avisos acima das configurações informam quando só uma das credenciais de API foi preenchida, quando não há nenhuma credencial, quando não há preços por país nem custo alternativo e quando a última requisição à API da Budbee falhou (com data, hora e motivo). Sempre que você salva as configurações, as listas de caixas em cache e o último erro de API são apagados.

Geral

Enable/Disable: liga ou desliga o método em todos os lugares, inclusive nas zonas de entrega. Padrão: ligado.

Method name: o nome do método de envio exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo pelo próprio Title. Padrão: Instabee parcel box.

Tax status: Taxable adiciona o imposto do WooCommerce ao custo de envio; None não adiciona.

Seletor de caixa (API Budbee)

Com as credenciais de API, o cliente escolhe na finalização de compra uma caixa perto do seu CEP, e a caixa fica salva no pedido. Os dois campos são necessários. O seletor permanece desligado até que ambos sejam preenchidos.

API key: a sua chave de API da Budbee (o nome de usuário do HTTP Basic).

API secret: o seu segredo de API da Budbee (a senha do HTTP Basic).

Test environment: usa a API de homologação da Budbee (api.staging.budbee.com). Ative somente com credenciais de homologação da Instabee. Lojas em produção deixam desligado (api.budbee.com). Padrão: desligado.

Preços (o título da seção mostra a moeda da sua loja)

Todos os preços estão na moeda da loja. Vírgula e ponto decimal são aceitos (49,90 = 49.90). Um valor que não é número não é salvo, e uma mensagem de erro indica o campo.

Calculation type: como o preço é aplicado.

Country prices: uma tabela com as colunas Country, Price, XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Clique em + Add country para adicionar uma linha e no x para remover uma. Escolha * Any other country para uma linha que vale para todos os países sem linha própria. Uma faixa vazia ou 0 usa a coluna Price. Um Price de 0 significa entrega grátis. Se a linha do país não tiver preço para o peso do carrinho, usa-se a linha * e, depois, o Fallback cost. Os pesos são convertidos da unidade de peso da loja para kg.

Fallback cost: usado quando nem a linha do país de destino nem a linha * fornecem um preço. Deixe vazio para ocultar o método nesses países.

Condições

Min weight (kg): oculta o método quando o carrinho pesa menos. Padrão: 0 (sem limite).

Max weight (kg): oculta o método quando o carrinho pesa mais. As caixas aceitam até cerca de 20 kg. Padrão: 20. 0 significa sem limite.

Minimum order amount: mostra o método somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para sempre mostrar.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual o método é grátis. Deixe vazio para nunca torná-lo grátis.

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

Disponibilidade sem zonas de entrega

Normalmente você adiciona o VibeFox Instabee a uma zona de entrega. Como alternativa, você pode ativá-lo aqui para uma lista de países.

Ignore shipping zones: oferece o método nos países abaixo, mesmo onde nenhuma zona de entrega o inclui.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais você envia. Este campo é usado somente quando Ignore shipping zones está ativado.

Avançado

Debug log: grava mensagens de depuração em WooCommerce > Status > Logs (origem vfd-instabee). Erros de API são sempre registrados, mesmo com esta opção desligada. Chaves de API e dados de clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove as configurações e as tarifas por zona deste método. Desativar o plugin nunca apaga as configurações. As caixas salvas nos pedidos são mantidas.

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 as condições: peso do carrinho, valor mínimo do pedido e classes de envio excluídas. Se o subtotal do carrinho atingir Free shipping from, a tarifa é grátis. Caso contrário, o preço vem da linha Country prices do país de destino, da linha * ou do Fallback cost. Se não houver preço, o método fica oculto.

Quando o cliente seleciona a tarifa Instabee e as credenciais de API estão definidas, aparece um seletor Parcel box abaixo da tarifa para Suécia, Finlândia, Dinamarca, Países Baixos e Bélgica. Ele lista as caixas perto do CEP do endereço de entrega, ordenadas por distância, com nome, endereço e distância. O cliente pode digitar outro CEP e clicar em Search. Até que um CEP seja informado, o seletor pede um. Se nenhuma caixa for encontrada, o cliente é orientado a tentar outro CEP ou escolher outro método de envio.

A caixa é obrigatória. Ao fazer o pedido, o plugin verifica no servidor se a caixa escolhida está na lista da Budbee para aquele CEP. Caso contrário, o cliente vê Please choose an Instabee parcel box. O nome da caixa vem da lista da Budbee, e não do navegador.

O plugin envia à Budbee apenas o país de destino e o CEP, nunca nomes, endereços, e-mails ou dados do pedido. As listas de caixas ficam em cache por 12 horas por CEP, um CEP sem caixas por 1 hora e uma requisição com falha por 5 minutos, para que uma API lenta ou fora do ar não atrase cada atualização da finalização de compra. O tempo limite da API é de 10 segundos.

Se a API da Budbee não estiver acessível, o cliente é informado de que o pedido pode ser feito sem escolher uma caixa. O pedido é então marcado, e você escolhe a caixa ao reservar o envio. Uma caixa escolhida antes que não possa ser verificada naquele momento é mantida e marcada como não verificada.

O seletor funciona na finalização de compra clássica e nos blocos de Carrinho e de Finalização de compra. O plugin é compatível com o HPOS (High-Performance Order Storage) do WooCommerce.

O plugin não calcula tarifas em tempo real, não agenda envios, não imprime etiquetas, não fornece números nem e-mails de rastreio, não oferece horários de entrega Budbee Home nem exibe mapa. Agende o pacote para a caixa escolhida nas suas ferramentas de comerciante da Instabee / Budbee.

Pontos de retirada

A caixa escolhida é salva no pedido e mostrada nestes lugares:

Tela do pedido no admin: abaixo do endereço de entrega, como Instabee parcel box com o nome da caixa, o endereço e o Box ID. Se a caixa não puder ser verificada na finalização de compra, ela aparece marcada como not verified (Budbee API was unavailable at checkout). Se nenhuma caixa foi escolhida porque a API estava indisponível, a tela informa isso e lembra você de escolher a caixa ao agendar o envio.

Página de agradecimento e página do pedido em Minha conta: o nome e o endereço da caixa.

E-mails do pedido: em HTML e texto simples. Os e-mails para a loja também mostram o ID da caixa. Se nenhuma caixa foi escolhida porque a API estava indisponível, apenas os e-mails para a loja mencionam isso.

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 Instabee. 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 a sua conta em 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 em vibefox.net.

Sem uma chave ativa, a Instabee não aparece para os clientes na finalização de compra. Administradores 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. 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 Instabee não aparece na finalização de compra: confira se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ligado e o país está permitido). Confira se o país tem preço, ou se existe uma linha * ou um Fallback cost. Confira os limites de peso, Minimum order amount e Excluded shipping classes. Um aviso acima das configurações informa quando nenhum preço está configurado.

Os clientes não veem a lista de caixas: a lista aparece somente quando API key e API secret estão preenchidos, para Suécia, Finlândia, Dinamarca, Países Baixos e Bélgica, e depois que um CEP é informado. O último erro de API é mostrado acima das configurações. Os detalhes estão em WooCommerce > Status > Logs (origem vfd-instabee). Ative o Debug log para mais detalhes.

HTTP 401 ou 403 no log: a Budbee recusou a chave ou o segredo de API. Confira os dois e veja se o Test environment corresponde às suas credenciais (credenciais de homologação só com o ambiente de teste ligado).

Nenhuma caixa para um CEP: a Budbee não atende esse CEP. O cliente pode pesquisar outro CEP ou escolher outro método de envio.

Listas de caixas antigas após uma mudança: salve a página de configurações. Isso limpa as listas de caixas em cache.

Outros países para a busca de caixas: desenvolvedores podem alterar a lista de países com o filtro vfd_ibee_box_countries.

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 para o 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 apenas limpa as listas de caixas em cache. Para removê-lo, desative-o e exclua-o na página Plugins. A chave e o status de licença deste plugin, as listas de caixas em cache e o último erro de API são sempre removidos. Configurações, métodos das zonas e dados de versão são removidos somente se Remove data on uninstall estava ativado. Caso contrário, eles ficam guardados para uma reinstalação posterior. As caixas salvas nos pedidos são sempre mantidas, e os pedidos existentes mantêm suas linhas de envio.

A Instabee e a Budbee são marcas registradas de seus respectivos proprietários. Este plugin não é afiliado nem endossado pela Instabee ou pela Budbee.