VibeFox bpost Cubee for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado com 3.0.5.0) ou 4.0.2 e posteriores (testado com 4.1.0.3).
PHP: 8.0 ou superior.
Conta bpost Shipping Platform (apenas para o seletor de ponto de retirada): a extensão pesquisa pontos de retirada pela API da bpost Shipping Platform. Entre na sua conta bpost Shipping Platform em plugins.bpost.be e crie as chaves em Settings > Key management. São necessários 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). Você também precisa do ID da transportadora do seu contrato (68 = bpost). Sem chaves completas, o método continua funcionando com preços fixos, 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 único domínio.
Instalação
O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote do OpenCart 3 vfd_bpost_cubee-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_bpost_cubee.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_bpost_cubee-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então você não precisa atualizar Extensions > Modifications. Em vez do Installer, você também pode copiar o conteúdo da pasta upload do pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox bpost Cubee e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações.
4. Informe sua chave de licença VibeFox em License key no bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).
5. Informe seus preços, por exemplo BE=4.95 e *=9.95, e, para o seletor de ponto de retirada, as chaves de API da bpost (veja Configuração). Ative Enable/Disable e clique em Save.
OpenCart 4
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_bpost_cubee.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.
2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.
3. Acesse Extensions > Extensions e escolha o tipo Shipping. Localize VibeFox bpost Cubee, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Informe a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.
Depois da instalação, o método fica desativado até que você o ative e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações que você manteve voltam a ser usadas.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa o token de API armazenado e as listas de pontos de retirada em cache. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.
Alguns erros interrompem o salvamento e nada é gravado: um Name com mais de 64 caracteres, um Sort Order que não é um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida. Outros problemas são informados como avisos e o restante é salvo: um peso ou valor que não é número ou é negativo não é salvo e o valor anterior é mantido; se Min weight (kg) for maior que Max weight (kg), os pesos não são salvos; linhas de Country prices que não puderam ser lidas são listadas e ignoradas; um valor de Size prices em que nenhum tamanho foi reconhecido é informado.
No topo da página aparece um aviso 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 (BE) nem preço padrão (*=PREÇO), a última conexão com a API da bpost falhou, ou a loja não tem uma classe de peso com a unidade "kg" (System > Localisation > Weight Classes). Nesse último caso, os pesos dos produtos são lidos pelo nome da unidade (kg, g, lb ou oz).
Geral
Enable/Disable: ativa ou desativa o envio para armários de encomendas bpost na finalização da compra. Padrão: desativado.
Name: o nome do método de envio exibido ao cliente na finalização da compra. Padrão: bpost parcel locker. Se você deixar em branco, o padrão é usado. No máximo 64 caracteres.
Tax Class: o imposto desta classe é somado aos seus preços. --- None --- (padrão) significa que os preços são definitivos.
Sort Order: a posição do método na lista de métodos de envio.
API da bpost (busca 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, disponível em Key management em plugins.bpost.be. Limpar este campo também remove a passphrase salva.
Passphrase (private key): a chave privada usada para assinar cada solicitação (HMAC-SHA256). Ela nunca é enviada à bpost nem gravada no log. Após 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 aplicação 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 ponto de retirada e de armário na finalização da compra. Ativado por padrão. O seletor aparece, e a escolha de um ponto é obrigatória, somente quando Account ID, Passphrase e App ID estão todos preenchidos.
Search field width: a largura CSS do campo CEP / 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 preços de envio 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 o método.
Size prices: usado quando Price by é tamanho de pacote, no formato S=3.50, M=4.50, L=6.00, XL=8.00. O tamanho é definido pelo peso do carrinho: S até 2 kg, M até 5 kg, L até 10 kg, XL acima.
Calculation: Per order (padrão) cobra o preço uma vez. Per item (price x number of items) o multiplica pelo número de itens no carrinho.
Os preços são arredondados para as casas decimais da moeda padrão da loja e depois exibidos na moeda do cliente.
Condições
Min weight (kg): o peso mínimo do carrinho para o método aparecer. Os pesos dos produtos são convertidos para kg. 0 significa sem limite (padrão).
Max weight (kg): o método fica oculto acima deste peso do carrinho. Padrão: 30, porque os armários da bpost aceitam pacotes de até 30 kg. 0 significa sem limite.
Minimum order amount: exibe o método somente quando o subtotal do carrinho atinge este valor. O subtotal considera os produtos que precisam de envio, após cupons, sem impostos. Deixe em branco para sempre exibir o método.
Frete grátis
Free shipping: ativa a entrega gratuita a partir do valor indicado abaixo.
Free shipping from: o subtotal do carrinho (produtos que precisam de envio, após cupons, sem impostos) a partir do qual o frete é grátis. Usado somente quando Free shipping está ativado. O país ainda precisa ter um preço, senão o método não é oferecido.
Disponibilidade
Normalmente o método é oferecido na zona geográfica selecionada abaixo. Com Ignore geo zone, ele é oferecido nos países da lista.
Geo Zone: oferece o método somente para endereços nesta zona geográfica. All Zones (padrão) significa em todos os lugares. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore geo zone: oferece o método nos países da lista, independentemente da zona geográfica.
Countries: os países de destino para esse modo. Padrão: Belgium. Deixe em branco para permitir todos os países. Usado somente quando Ignore geo zone está ativado.
Avançado
Debug log: grava as solicitações à API e os cálculos de preço em storage/logs/vfd_bpst_debug.log.php. O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Chaves e tokens nunca são registrados.
Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, ao desinstalar a extensão são excluídos as configurações, o log e as escolhas de pontos de retirada de finalizações de compra não concluídas. Pontos de retirada salvos nos pedidos são sempre mantidos. Padrão: desativado.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A passphrase não é exportada.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. A passphrase salva é mantida.
Como funciona na finalização da compra
Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da bpost. Se uma Geo Zone estiver definida (e Ignore geo zone estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Somente produtos com Requires Shipping definido como Yes são considerados: os demais produtos não somam peso e não entram no valor do pedido. A extensão verifica as condições: os países de Ignore geo zone (se ativado), o peso do carrinho e o valor mínimo do pedido. Em seguida, obtém o preço da lista de países ou por tamanho de pacote, multiplica pelo número de itens no modo por item e zera quando o frete grátis se aplica. Nenhuma solicitação é enviada à bpost para o preço.
Abaixo da opção 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 bpost e a lista ainda não foi carregada, o CEP do endereço de entrega (ou a última pesquisa do cliente) é pesquisado automaticamente. O cliente pode digitar outro CEP 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 é o holandês, e em francês nos demais casos.
O cliente precisa escolher um ponto de retirada. Sem um ponto, Continue na etapa do método de envio exibe Please select a bpost pickup point. Só é aceito um ponto da lista da bpost para a pesquisa. 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 para a finalização da compra, então recarregar a página não as perde. Uma nova pesquisa apaga a escolha anterior.
No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização da compra e escolhe a bpost na janela Shipping method options. A pesquisa e a lista de pontos de retirada aparecem nessa janela, sob a opção bpost. Continue na janela sem ponto de retirada exibe Please select a bpost pickup point. O restante funciona como no OpenCart 3.
Para listar os pontos de retirada, a extensão envia à bpost apenas o CEP 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 de pesquisa ficam em cache por até 6 horas, mas não além da duração do cache do OpenCart (1 hora por padrão). 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 a extensão tenta novamente após 5 minutos. O tempo limite da API é de 15 segundos.
A extensão usa apenas preços fixos. Ela não obtém tarifas em tempo real da bpost, não cria envios, não imprime etiquetas e não rastreia encomendas. Os pontos de retirada são exibidos como lista, não em um mapa. Crie os envios na sua conta bpost Shipping Platform ou Shipping Manager; o ID do ponto de retirada está na página do pedido no admin.
Pontos de retirada
Quando o pedido é feito, o ponto de retirada escolhido é adicionado ao método de envio do pedido como bpost pickup point: com o nome e o endereço do ponto, por exemplo "bpost parcel locker - bpost pickup point: …". Assim, o cliente o vê na confirmação do pedido, no histórico de pedidos da conta dele, nos e-mails de pedido e na fatura. O ponto completo, com o seu ID, também é salvo em uma tabela separada da extensão. No OpenCart 4, a finalização da compra mantém um único pedido: quando o cliente confirma o pedido novamente, por exemplo depois de escolher outro ponto de retirada, o ponto do pedido é atualizado.
No admin, a página do pedido em Sales > Orders mostra o painel bpost pickup point com o ponto e o seu ID, ou No pickup point was selected for this order. Clique em Change, pesquise um CEP ou uma cidade, escolha outro ponto da lista e clique em Save. O pedido e o texto do método de envio são atualizados imediatamente e a página exibe Pickup point updated. Se o ponto não estiver na lista da bpost para a pesquisa, a página exibe Pickup point not found in the bpost list of this search. A alteração é gravada no log de depuração quando Debug log está ativado. Change só fica disponível quando as chaves de API estão preenchidas e o usuário administrador pode modificar pedidos; não é necessário acesso às configurações da extensão.
Para oferecer armário e entrega em domicílio juntos, use outro método de envio para a entrega em domicílio. O seletor de ponto de retirada aparece somente sob a opção bpost.
Chave de licença
A extensão 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 Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit, acima das configurações. Cole 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-bpost-cubee e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 seguido de uma data. Depois de alterar o endereço da loja, 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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere-a na sua conta vibefox.net.
Sem uma chave ativa, a bpost não é exibida aos clientes na finalização da compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin no mesmo navegador ainda vê o método na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não vê o login do admin, então sem uma chave ativa o método fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete no Dashboard do admin. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.
Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática ao abrir o Dashboard do admin ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão 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 da compra: verifique se a licença está ativa e se Enable/Disable está ativado. Verifique a Geo Zone, ou se Ignore geo zone está ativado e o país está em Countries. Confira se o país tem um preço ou se existe uma linha *=PREÇO, e verifique os limites de peso e o Minimum order amount. Confirme que os produtos têm Requires Shipping definido como Yes. A página de configurações mostra um aviso quando a Bélgica não tem preço.
Nenhum seletor de ponto de retirada na finalização da 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 mostra 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 no topo da página de configurações e no log de depuração (campo Log na página da extensão). A extensão tenta novamente automaticamente após 5 minutos. Salvar as configurações tenta de imediato.
Nenhum ponto de retirada encontrado para este CEP ou cidade: a bpost não retornou pontos para essa pesquisa. Peça ao cliente que tente um CEP 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 de Country prices que não seguem o formato CC=PREÇO são ignoradas; o aviso após salvar as enumera.
Os preços incluem imposto? Com Tax Class em --- None ---, os preços são definitivos. Com uma classe de imposto, o OpenCart soma esse imposto aos seus preços.
A página diz "Warning: You do not have permission to modify VibeFox bpost Cubee!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_bpost_cubee (OpenCart 3) ou extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API da bpost pode ser substituído pela configuração vfd_bpst_api_url (para testes); ela não tem campo na página de configurações.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox bpost Cubee. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort Order, Tax Class e Geo Zone. O token de API salvo e as listas de pontos de retirada em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações, o log e os pontos de retirada de finalizações não concluídas também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os pontos de retirada salvos nos pedidos fazem parte do histórico de pedidos e nunca são excluídos. Os pedidos existentes mantêm o método de envio e o custo.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox bpost Cubee na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com lixeira) para remover o pacote enviado.
A bpost é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela bpost.