VibeFox Instabee for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões mais antigas do PHP.
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, a transportadora continua funcionando com preços fixos, mas os clientes não conseguem escolher uma caixa de pacotes.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o upload terminar, clique em Configure ou encontre VibeFox Instabee mais tarde 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. Preencha a seção Prices e, para o seletor de caixas, a sua API key e o seu API secret da Budbee (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora Instabee parcel box com o texto de prazo de entrega Delivery to an Instabee parcel box. A transportadora é associada a todos os grupos de clientes e às zonas da Suécia, Finlândia, Dinamarca, Países Baixos e Bélgica. 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 Instabee > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira.
Os avisos acima das configurações informam quando apenas uma das credenciais da API foi inserida, quando não há credenciais da API, quando não há preços por país nem custo alternativo, quando a última requisição à API da Budbee falhou (com data, hora e motivo), quando a transportadora Instabee não é encontrada e quando a unidade de peso da loja não é reconhecida (defina kg, g, lb ou oz em International > Localization, Local units). Sempre que você salva as configurações, as listas de caixas em cache e o último erro da API são apagados. Se o nome do método ou o status de imposto não forem válidos, ou se Min weight (kg) for maior que Max weight (kg), nada é salvo e um erro é exibido.
General
Enable/Disable: ativa ou desativa a transportadora. É a mesma chave do status da transportadora em Shipping > Carriers.
Method name: o nome da transportadora que o cliente vê no checkout. Padrão: Instabee parcel box. Obrigatório, no máximo 64 caracteres.
Tax status: None significa que os preços abaixo são finais. Taxable com uma regra de imposto significa que o PrestaShop acrescenta sobre os preços abaixo o imposto de frete dessa regra.
Seletor de caixa de pacotes (API Budbee)
Com as credenciais da API, o cliente escolhe uma caixa perto do seu CEP no checkout, e a caixa é salva no pedido. Os dois campos são necessários. O seletor permanece desativado até que ambos estejam 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). Ele nunca é gravado no log.
Depois de salvar, os dois campos ficam vazios e exibem Saved - leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para apagar as credenciais salvas, marque Remove the saved API key and secret e salve. Quando nada está salvo, a página mostra No credentials saved.
Test environment: usa a API de staging da Budbee (api.staging.budbee.com). Ative-o somente com credenciais de staging fornecidas pela Instabee. Lojas em produção deixam desativado (api.budbee.com). Padrão: desativado.
Preços (o título da seção mostra a moeda padrão da sua loja)
Todos os preços estão na moeda padrão da loja, sem impostos. São aceitas a vírgula e o ponto decimal (49,90 = 49.90). O preço é mostrado ao cliente na moeda do carrinho.
Calculation type: como o preço é aplicado.
Country prices: uma tabela com as colunas Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. Escolha * Any other country para uma linha que se aplica a todos os países sem linha própria. Uma faixa vazia ou 0 usa a coluna Price. Um Price de 0 significa entrega gratuita. 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. Um preço que não seja número é apagado e um aviso o lista. 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 preço. Deixe vazio para ocultar a transportadora nesses países.
Condições
Min weight (kg): oculta a transportadora abaixo deste peso do carrinho. Padrão: 0 (sem limite).
Max weight (kg): oculta a transportadora acima deste peso do carrinho. As caixas de pacotes aceitam até cerca de 20 kg. Padrão: 20. 0 significa sem limite. Não pode ser menor que Min weight (kg).
Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) atinge este valor. Deixe vazio para mostrar sempre.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a transportadora é gratuita. Deixe vazio para nunca torná-la gratuita.
Se um valor nesses campos ou em Fallback cost não for um número, ele não é salvo, o valor anterior permanece e um aviso indica o campo.
Disponibilidade sem zonas de entrega
Normalmente a transportadora é oferecida nas zonas de entrega às quais está vinculada em Shipping > Carriers. Alternativamente, você pode ativá-la aqui para uma lista de países.
Ignore shipping zones: oferece a transportadora nos países abaixo, mesmo onde as suas zonas não os incluem. A transportadora é vinculada a todas as zonas ativas, inclusive às criadas depois. Quando você desativa a opção de novo, a transportadora recupera as zonas que tinha antes.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava mensagens de depuração em logs/vfd_ibee_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Chaves de API e dados de clientes nunca são registrados.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações e a transportadora. Quando desativado, desinstalar apenas desativa a transportadora. Caixas de pacotes salvas em pedidos são sempre mantidas.
Como funciona no checkout
Na etapa de envio, o PrestaShop pede ao módulo o preço da Instabee. Só produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica as condições: peso do carrinho e valor mínimo do pedido e, com Ignore shipping zones, os países permitidos. Se o subtotal do carrinho atingir Free shipping from, o preço é 0. Caso contrário, o preço é obtido da linha Country prices do país de destino, da linha * ou do Fallback cost. Se não houver preço, a transportadora fica oculta.
Quando o cliente seleciona a transportadora Instabee e as credenciais da API estão definidas, aparece um bloco Parcel box abaixo da transportadora 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 (ou pressionar Enter). Até que um CEP seja informado, o bloco o solicita. Se nenhuma caixa for encontrada, o cliente é convidado a tentar outro CEP ou a escolher outro método de envio. Para outros países, a transportadora é oferecida sem caixa.
A caixa é obrigatória. A caixa escolhida só é salva no carrinho se estiver na lista da Budbee para aquele CEP. Quando o cliente clica em Continue na etapa de entrega, o módulo verifica a caixa novamente no servidor. Caso contrário, o cliente vê Please choose an Instabee parcel box. O nome da caixa vem da lista da Budbee, não do navegador. Se o cliente alterar o país de entrega ou o CEP do endereço, a escolha anterior é descartada.
O módulo 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 deixe cada atualização do checkout mais lenta. A página de checkout nunca espera pela Budbee: a lista é carregada em segundo plano assim que a transportadora é selecionada. O tempo limite da API é de 10 segundos.
Se a API da Budbee não estiver acessível, o cliente vê Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. 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 com os temas Classic e Hummingbird. Se você editar a transportadora em Shipping > Carriers depois que ela já 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 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 mostra um mapa. Reserve o pacote para a caixa escolhida nas suas ferramentas de comerciante Instabee / Budbee.
Pontos de retirada
Ao criar o pedido, a caixa é verificada mais uma vez e salva no pedido. A partir daí, a loja virtual não pode alterá-la. A caixa é mostrada nestes lugares:
Página do pedido no back office: um bloco Instabee parcel box com o nome da caixa, o endereço e o Box ID. Se a caixa não pôde ser verificada no checkout, ela aparece marcada como not verified (Budbee API was unavailable at checkout). Se nenhuma caixa foi escolhida porque a API estava indisponível, o bloco diz Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.
Página de confirmação do pedido e detalhes do pedido na conta do cliente: Instabee parcel box: com o nome e o endereço da caixa.
E-mails do pedido: a caixa é acrescentada ao nome da transportadora no e-mail de confirmação do pedido enviado ao cliente. O e-mail de novo pedido para a loja (do módulo Mail alerts do PrestaShop) também mostra o ID da caixa. Se nenhuma caixa foi escolhida porque a API estava indisponível, apenas o e-mail para a loja menciona isso.
Chave de licença
O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Instabee é o primeiro bloco em Modules > Module Manager > VibeFox Instabee > 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 ficam a linha Product: presta-shipping-instabee 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 do 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 seguido de uma data. Depois que o endereço da loja for alterado, ou depois que você 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 único 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 Instabee não é mostrada aos clientes no checkout e nenhuma tarifa é calculada. A loja virtual do PrestaShop não sabe que você está logado no back office, então a transportadora também fica oculta para você: você pode configurar o módulo antes de comprar uma chave, mas não pode testá-lo no checkout. 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 precisam de renovação. O status é verificado novamente automaticamente 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 nenhum 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 Instabee não aparece no checkout: 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á ligado e o país é permitido. Verifique se o país tem preço, ou se existe uma linha * ou um Fallback cost. Verifique os limites de peso e o Minimum order amount. Um aviso acima das configurações informa quando nenhum preço está configurado. Produtos também podem ser limitados a certas transportadoras na página do produto. Ative o Debug log para ver o motivo no campo Log.
Os clientes não veem a lista de caixas: a lista só aparece 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 da API é mostrado acima das configurações. Os detalhes estão no campo Log na página do módulo. Ative o Debug log para mais detalhes.
HTTP 401 ou 403 no log: a Budbee rejeitou a chave ou o segredo da API. Verifique-os e confirme que Test environment corresponde às suas credenciais (credenciais de staging somente com o ambiente de teste ativado).
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.
O cliente não consegue continuar na etapa de entrega: uma caixa de pacotes precisa ser escolhida na lista, a menos que a API da Budbee esteja inacessível. Uma caixa que não está na lista do CEP pesquisado não é salva, e o cliente vê This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.
Listas de caixas antigas após uma alteração: clique em Save na página do módulo. Isso limpa as listas de caixas em cache.
A página informa que a transportadora Instabee não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente. O mesmo vale para a mensagem The settings were saved, but the carrier could not be updated. A redefinição mantém o status da transportadora: uma transportadora desativada continua desativada.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Instabee e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As listas de caixas em cache são sempre removidas. 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 as caixas escolhidas em carrinhos que nunca viraram pedidos são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, a transportadora salva recupera o status que tinha. Caixas de pacotes salvas em pedidos são sempre mantidas.
Instabee e Budbee são marcas registradas de seus respectivos proprietários. Este módulo não é afiliado nem endossado pela Instabee ou pela Budbee.