VibeFox bpost Cubee for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

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

PHP: 8.0 ou superior.

Conta bpost Shipping Platform (somente para o seletor de ponto de retirada): o plugin pesquisa pontos de retirada pela API da bpost Shipping Platform. Faça login na sua conta bpost Shipping Platform em plugins.bpost.be e crie as chaves em Settings > Key management. Você precisa de três valores: Account ID (chave pública), Passphrase (chave privada) e um App ID (X-APPID). O App ID é emitido pela bpost para a sua integração; peça ao suporte de e-commerce da bpost (eol@bpost.be). Também é necessário o ID da transportadora do seu contrato (68 = bpost). Sem chaves completas, o método continua funcionando como método de envio de preço fixo, mas o cliente não é solicitado a escolher um ponto de retirada.

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox bpost Cubee, 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. Informe seus preços e, para o seletor de ponto de retirada, as chaves de API da bpost (veja Configuração).

6. Adicione VibeFox bpost Cubee à sua zona de envio para a Bélgica 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 bpost Cubee. 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 na finalização de compra para esta zona. Deixe vazio para usar o Name global.

A página de configurações exibe avisos quando algo oculta silenciosamente o método ou o seletor: o seletor de ponto de retirada está ativado, mas as chaves de API estão incompletas; não há preço para a Bélgica; ou a última conexão com a API da bpost falhou. Sempre que você salva as configurações, o token de API armazenado e as listas de pontos de retirada em cache são apagados.

Geral

Enable/Disable: ativa ou desativa o envio para armários bpost 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: bpost parcel locker.

Tax status: Taxable acrescenta o imposto do WooCommerce aos seus preços; None significa que os preços são finais.

API da bpost (pesquisa de pontos de retirada) (necessária apenas para o seletor de ponto de retirada)

Account ID (public key): a chave pública da sua conta bpost Shipping Platform, em Key management em plugins.bpost.be.

Passphrase (private key): a chave privada usada para assinar cada requisição (HMAC-SHA256). Ela nunca é enviada à bpost nem gravada no log.

App ID (X-APPID): o identificador de aplicativo emitido pela bpost para a sua integração. Ele é enviado no cabeçalho X-APPID.

Carrier ID: a transportadora do seu contrato bpost Shipping Platform cujos pontos de retirada e armários são listados. Padrão: 68 (bpost). Outras transportadoras habilitadas no seu contrato têm IDs próprios.

Seletor de ponto de retirada

Pickup points: exibe o seletor de pontos de retirada e armários na finalização de compra. Ativado por padrão. O seletor aparece somente quando as três chaves de API estão preenchidas.

Search field width: a largura CSS do campo de código postal / cidade, por exemplo 100% ou 300px. Padrão: 100%.

Pickup point list width: a largura CSS da lista de pontos de retirada, por exemplo 100% ou 400px. Padrão: 100%.

Preços (na moeda da sua loja; a bpost não retorna preços de envio por esta API)

Price by: como o preço é escolhido.

Country prices: uma linha por país no formato CC=PRICE, por exemplo BE=4.95. A linha *=PRICE define o preço de todos os outros países, por exemplo *=9.95. Tanto o ponto quanto a vírgula são aceitos como separador decimal. Linhas inválidas são ignoradas e listadas em uma mensagem de erro ao salvar. Países sem preço (quando não há linha *) não recebem o método.

Size prices: usado quando Price by é tamanho do pacote, no formato S=3.50, M=4.50, L=6.00, XL=8.00. O tamanho vem do peso do carrinho: S até 2 kg, M até 5 kg, L até 10 kg, XL acima de 10 kg.

Calculation: Per order cobra o preço uma vez. Per item (price x number of items) multiplica pelo número de itens no carrinho.

Condições

Min weight (kg): o peso mínimo do carrinho para o método aparecer. 0 significa sem limite.

Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 30, porque os armários bpost aceitam pacotes de até 30 kg. 0 significa sem limite.

Minimum order amount: exibe o método somente quando o subtotal do carrinho (sem imposto) atinge este valor. Deixe vazio para exibir sempre.

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

Os pesos dos produtos são convertidos da unidade de peso da loja para quilogramas.

Frete grátis

Free shipping: ativa a entrega gratuita a partir do valor abaixo.

Free shipping from: o subtotal do carrinho (sem imposto) a partir do qual o envio é grátis. Usado somente quando Free shipping está ativado.

Disponibilidade sem zonas de envio

Ignore shipping zones: oferece o método nos países abaixo sem adicioná-lo a uma zona.

Countries: os países de destino para esse modo. Padrão: Bélgica. 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: registra requisições à API e cálculos de preço em WooCommerce > Status > Logs, origem vfd-bpost-cubee. Erros de API são sempre registrados, mesmo com esta opção desativada. Chaves, tokens e dados de clientes nunca são registrados.

Remove data on uninstall: quando ativado, excluir o plugin remove suas configurações e seus métodos de zona. Desativar o plugin nunca apaga dados. Os pontos de retirada salvos nos pedidos são sempre mantidos.

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: país de entrega, peso do carrinho, valor mínimo do pedido e classes de envio excluídas. Depois, pega o preço da lista de países ou pelo tamanho do pacote, multiplica pelo número de itens no modo por item e zera o valor quando o frete grátis se aplica.

Quando o cliente escolhe a tarifa bpost, aparecem abaixo dela um campo de pesquisa, um botão Search e uma lista de pontos de retirada. Se o campo de pesquisa estiver vazio, o código postal do endereço da finalização de compra é pesquisado automaticamente. O cliente pode digitar outro código postal ou o nome de uma cidade. Cada ponto é exibido com nome e endereço. São listados até 50 pontos. A lista de pontos de retirada é solicitada em holandês nos sites em holandês e em francês nos demais.

O cliente precisa escolher um ponto de retirada. Sem escolha, a finalização de compra clássica exibe Please select a bpost pickup point., e a finalização de compra em blocos recusa o pedido com a mesma mensagem. A escolha é mantida durante a sessão de compra, então recarregar a página não a perde.

Para listar os pontos de retirada, o plugin envia à bpost apenas o código postal ou a cidade pesquisados, o país e o ID da transportadora, assinados com as suas chaves. Nenhum nome, e-mail ou linha de endereço do cliente é enviado. O token de API é solicitado e renovado automaticamente. Se a bpost rejeitar um token, um novo é solicitado uma vez e a pesquisa é repetida. Os resultados da pesquisa ficam em cache por 6 horas. Se a bpost não responder, o cliente vê Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method., e o plugin tenta de novo após 5 minutos. O tempo limite da API é de 15 segundos.

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

O plugin usa somente preços fixos. Ele não obtém tarifas em tempo real da bpost, não cria envios, não imprime etiquetas nem rastreia pacotes. Os pontos de retirada são exibidos como lista, não em mapa. Crie os envios na sua conta bpost Shipping Platform ou Shipping Manager; o ID do ponto de retirada está no pedido.

Pontos de retirada

O ponto de retirada escolhido (nome e endereço) e o seu ID são salvos no pedido. Na tela de pedido do administrador, ele aparece abaixo do endereço de entrega como bpost pickup point. Clique em Change, pesquise um código postal ou uma cidade e escolha outro ponto na lista. O pedido é atualizado na hora e uma nota do pedido bpost pickup point changed to: … é adicionada. O link Change fica disponível somente quando as chaves de API estão preenchidas.

Os clientes veem o ponto de retirada na página de agradecimento e em My account > Orders. Ele também é incluído nos e-mails do pedido, tanto em HTML quanto em texto simples.

Para oferecer armário e entrega em domicílio juntos, adicione outro método de envio, por exemplo Flat rate, à mesma zona. O seletor de ponto de retirada aparece somente abaixo da tarifa bpost.

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 bpost Cubee. 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 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, o método bpost não é exibido aos clientes na finalização de compra. Os gerentes da loja conectados 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 renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A bpost 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). Verifique se o país tem preço ou uma linha *=PRICE, e confira os limites de peso, Minimum order amount e Excluded shipping classes. A página de configurações exibe um aviso quando a Bélgica não tem preço.

Nenhum seletor de ponto de retirada na finalização de compra: verifique se Pickup points está ativado e se Account ID (public key), Passphrase (private key) e App ID (X-APPID) estão todos preenchidos. A página de configurações exibe um aviso quando as chaves estão incompletas.

Os clientes veem "Pickup points cannot be loaded right now": a bpost não respondeu ou recusou as chaves. O motivo está em WooCommerce > Status > Logs (origem vfd-bpost-cubee) e na página de configurações. O plugin tenta novamente de forma automática após 5 minutos. Salvar as configurações tenta de imediato.

Nenhum ponto de retirada encontrado para este código postal ou cidade: a bpost não retornou pontos para essa pesquisa. Peça ao cliente que tente um código postal próximo ou o nome de uma cidade, e confira o Carrier ID.

Preços com vírgula não são usados: tanto 5,50 quanto 5.50 são aceitos. Linhas em Country prices que não seguem o formato CC=PRICE são ignoradas; a mensagem de erro após salvar as lista.

Os preços incluem imposto? Com Tax status em Taxable, o WooCommerce acrescenta o imposto aos seus preços. Com None, os preços são finais.

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

Desinstalação

Desativar o plugin mantém todas as configurações; ele apenas limpa o token de API e as listas de pontos de retirada em cache. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin, o token de API e os caches 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, eles permanecem para uma reinstalação futura. Os pontos de retirada salvos nos pedidos fazem parte do histórico de pedidos e nunca são excluídos.

bpost é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela bpost.