VibeFox bpost Cubee for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Conta bpost Shipping Platform (somente para o seletor de ponto de retirada): o módulo pesquisa pontos de retirada pela API do 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-o ao suporte de e-commerce da bpost (eol@bpost.be). Você também precisa do ID da transportadora do seu contrato (68 = bpost). Sem chaves completas, a transportadora continua funcionando com preços fixos, mas os clientes não são solicitados 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 back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure, ou encontre VibeFox bpost Cubee depois na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Insira os seus preços e, para o seletor de ponto de retirada, as chaves de API da bpost (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora bpost parcel locker com o texto de prazo de entrega Pickup point or parcel locker. A transportadora fica vinculada à zona da Bélgica e a todos os grupos de clientes, sem regra de imposto. Você pode alterar zonas, grupos de clientes, prazo de entrega e logotipo em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox bpost Cubee > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa o token de API armazenado e as listas de pontos de retirada em cache.
A página mostra avisos quando algo oculta silenciosamente a transportadora 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 (BE) nem preço padrão; a última conexão com a API da bpost falhou; a unidade de peso da loja não é conhecida pelo módulo (defina-a em International > Localization, Local units); ou a transportadora bpost não foi encontrada. Ao salvar, as linhas de Country prices que não puderam ser lidas são listadas em um aviso, e também um valor de Size prices em que nenhum tamanho foi reconhecido. Um peso ou valor que não seja número ou seja negativo não é salvo: um aviso indica o campo e o valor anterior é mantido. Se Min weight (kg) for maior que Max weight (kg), os pesos também não são salvos.
Geral
Enable/Disable: liga ou desliga o envio com bpost parcel locker. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome do método de envio exibido ao cliente na finalização de compra (o nome da transportadora). Padrão: bpost parcel locker. Se deixar em branco, usa-se o padrão. No máximo 64 caracteres; um nome maior é recusado e nada é salvo.
Tax status: None significa que os preços são finais. Taxable com uma regra de imposto acrescenta o imposto dessa regra aos seus preços. A escolha é salva na transportadora.
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. Esvaziar este campo também remove a Passphrase salva.
Passphrase (private key): a chave privada usada para assinar cada requisição (HMAC-SHA256). Ela nunca é enviada à bpost nem gravada no log. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um novo valor apenas para alterá-lo.
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 ativas no seu contrato têm IDs próprios.
Seletor de ponto de retirada
Pickup points: exibe o seletor de ponto de retirada e de armário no checkout. Ativado por padrão. O seletor aparece, e um ponto de retirada é obrigatório, 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 padrão da sua loja, sem impostos; a bpost não retorna valores de frete por esta API)
Price by: como o preço é escolhido.
Country prices: uma linha por país no formato CC=PREÇO, por exemplo BE=4.95. A linha *=PREÇO define o preço para 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. Países sem preço (quando não há linha *) não recebem a opção de transportadora.
Size prices: usado quando Price by é tamanho do pacote, na forma 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.
Calculation: Per order cobra o preço uma vez. Per item (price x number of items) multiplica pelo número de itens no carrinho.
Os preços são arredondados para as casas decimais da sua moeda padrão e depois exibidos na moeda do carrinho do cliente.
Condições
Min weight (kg): o peso mínimo do carrinho para a transportadora aparecer. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. 0 significa sem limite.
Max weight (kg): a transportadora fica oculta 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 a transportadora somente quando o subtotal do carrinho atinge este valor. O subtotal conta os produtos que precisam de envio, após descontos, sem impostos. Deixe em branco para sempre exibir a transportadora.
Frete grátis
Free shipping: ativa a entrega gratuita a partir do valor abaixo.
Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) a partir do qual o frete é grátis. Usado somente quando Free shipping está ativado. O país ainda precisa de um preço, caso contrário a transportadora não é oferecida.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida nas suas zonas de envio em Shipping > Carriers. Na instalação, essa é a zona da Bélgica.
Ignore shipping zones: oferece a transportadora nos países abaixo sem adicioná-la a uma zona. A transportadora fica então vinculada a todas as zonas ativas, inclusive às zonas que você criar depois. Quando desligar a opção novamente, a transportadora recupera suas zonas anteriores.
Countries: os países de destino para esse modo. Padrão: Bélgica. Deixe em branco 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 de API e cálculos de preço em logs/vfd_bpst_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Erros de API são sempre registrados, mesmo com esta opção desligada. Chaves e tokens nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo apaga as suas configurações e a transportadora. Os pontos de retirada salvos nos pedidos são sempre mantidos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da bpost. Somente os produtos que precisam de envio contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica as condições: os países de Ignore shipping zones (se ativado), o peso do carrinho e o valor mínimo do pedido. Depois, pega o preço da lista de países ou por tamanho do pacote, multiplica pelo número de itens no modo por item e o zera quando o frete grátis se aplica. Nenhuma requisição é enviada à bpost para o preço.
Abaixo da transportadora bpost, o cliente vê um campo Postal code or city, um botão Search e uma lista de pontos de retirada. Quando o cliente escolhe a transportadora e ainda não pesquisou, o código postal do endereço de entrega é 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 é solicitada em holandês quando o idioma da loja é holandês, e em francês nos demais casos.
O cliente precisa escolher um ponto de retirada. Sem ele, Continue na etapa de entrega exibe Please select a bpost pickup point., e o botão Place order fica bloqueado na página com a mesma mensagem. Somente um ponto da lista da bpost para a pesquisa é aceito. Caso contrário, o cliente vê The selected bpost pickup point is not in the list of your search. Please choose another one. A pesquisa e a escolha são salvas com o carrinho, então uma atualização da página não as perde. Uma nova pesquisa apaga a escolha anterior.
Para listar os pontos de retirada, o módulo envia à bpost apenas o código postal ou a cidade pesquisados, o país e o ID da transportadora, assinados com as suas chaves. 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 módulo tenta novamente após 5 minutos. O tempo limite da API é de 15 segundos.
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.
O módulo 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
Quando o pedido é feito, o ponto de retirada escolhido (nome e endereço) e o seu ID são salvos com o pedido. Na página do pedido no back office, o bloco bpost pickup point mostra o ponto e o seu ID, ou No pickup point was selected for this order. Clique em Change, pesquise um código postal ou uma cidade, escolha outro ponto na lista e clique em Save. O pedido é atualizado imediatamente e a página exibe Pickup point updated. A alteração é gravada no log de depuração quando Debug log está ativado. O link Change fica disponível somente quando as chaves de API estão preenchidas. Salvar um novo ponto exige a permissão para editar pedidos; caso contrário, a página exibe Permission denied. Não é necessário acesso às páginas de Módulos.
Se o PrestaShop dividir um carrinho em vários pedidos, o ponto de retirada fica com o primeiro pedido. Os outros pedidos não têm ponto de retirada, e o log de depuração mostra um erro com o nome do primeiro pedido; defina o ponto desses pacotes manualmente na bpost.
Os clientes veem o ponto de retirada como bpost pickup point: na página de confirmação do pedido e nos detalhes do pedido na conta deles. Ele também é adicionado ao nome da transportadora no e-mail de confirmação do pedido. O e-mail de novo pedido para a loja (se você usar o módulo de alertas por e-mail) também contém o ID do ponto.
Para oferecer armário e entrega em domicílio juntos, use outra transportadora para a entrega em domicílio na mesma zona. O seletor de ponto de retirada aparece somente na transportadora bpost.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox bpost Cubee é o primeiro bloco em Modules > Module Manager > VibeFox bpost Cubee > Configure, acima das configurações. Insira a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-bpost-cubee e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on com uma data. Depois que o endereço da loja mudar, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a transportadora bpost não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Não é necessário cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A bpost não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou se Ignore shipping zones está ativado e o país está em Countries. Verifique se o país tem um preço ou se existe uma linha *=PREÇO, e confira os limites de peso e o Minimum order amount. Os produtos também podem estar limitados a certas transportadoras na página do produto. A página de configurações exibe um aviso quando a Bélgica não tem preço.
Sem 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 aparece na página de configurações e no log de depuração (campo Log na página do módulo). O módulo tenta novamente automaticamente 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 verifique o Carrier ID.
Preços com vírgula não são usados: tanto 5,50 quanto 5.50 são aceitos. As linhas de Country prices que não seguem o formato CC=PREÇO são ignoradas; o aviso após salvar as lista.
Os preços incluem imposto? Com Tax status em None, os preços são finais. Com uma regra de imposto Taxable, o PrestaShop adiciona esse imposto aos seus preços.
A página diz que a transportadora bpost não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Para desenvolvedores, os hooks actionVfdBpstApiUrl e actionVfdBpstApiLanguage alteram o endereço da API da bpost e o idioma da lista de pontos de retirada.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox bpost Cubee e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O token de API armazenado e as listas de pontos de retirada em cache são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e os pontos de retirada de carrinhos não concluídos são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Instalar o módulo novamente devolve à transportadora o status que ela tinha antes da desinstalação. Reset em Modules > Module Manager funciona da mesma forma, então uma transportadora desativada continua desativada. Os pontos de retirada salvos nos pedidos fazem parte do histórico de pedidos e nunca são apagados.
A bpost é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela bpost.