VibeFox Blue Express for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Conta Blue Express (somente para tarifas em tempo real): as tarifas em tempo real exigem uma conta de e-commerce da Blue Express e a sua chave de API (x-api-key). Solicite-a à Blue Express: developers.bluex.cl ou gpo.integraciones@bx.cl. O serviço que você usa (EX, PY ou MD) deve estar habilitado no seu contrato com a Blue Express. Se você usa apenas preços fixos, não precisa de chave de API.
Regiões chilenas: para uma tarifa em tempo real, o endereço de entrega precisa ter uma região chilena. Se a sua loja não tiver regiões para o Chile, o módulo pode adicioná-las para você (veja Configuração).
Pontos de retirada: o mapa da Blue Express é carregado a partir de widget-pudo.blue.cl no navegador do cliente.
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, mais tarde, encontre VibeFox Blue Express na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Insira a chave de API, o serviço, o código do distrito de origem (por exemplo SCL), a taxa de câmbio para CLP se a moeda da sua loja não for o CLP e os preços fixos (por exemplo CL=4500). Ative Pickup point carrier se quiser oferecer retirada nos pontos da Blue Express. Clique em Save. Veja Configuração.
Na instalação, o módulo cria duas transportadoras: Blue Express (entrega em domicílio, texto de prazo de entrega Home delivery, ativada) e Blue Express pickup point (texto de prazo de entrega Pickup at a Blue Express point, desativada até você ativá-la). Ambas estão atribuídas à zona do Chile e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho 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 Blue Express > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas da Blue Express e os dados de comunas em cache. No topo da página aparecem avisos sobre configurações que ocultariam as transportadoras ou a tarifa em tempo real: sem chave de API, moeda da loja diferente de CLP sem taxa de câmbio, tabela de preços fixos vazia, sem regiões para o Chile, uma unidade de peso ou de dimensão da loja que o módulo não reconhece (os pesos são então lidos como kg e as dimensões como cm), ou uma transportadora excluída. Valores inválidos são recusados com um erro e nada é salvo: um nome de transportadora vazio ou inválido, um nome com mais de 64 caracteres, um número negativo ou inválido, ou Min weight (kg) maior que Max weight (kg). As condições e os preços abaixo valem para as duas transportadoras.
Geral
Enable/Disable: ativa ou desativa a transportadora de entrega em domicílio. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora exibido no checkout para entrega em domicílio. Padrão: Blue Express. Obrigatório, no máximo 64 caracteres.
Tax status: None (no tax on shipping) ou Taxable com uma das suas regras de imposto. Os preços da Blue Express incluem IVA. Escolha None se o PrestaShop não deve adicionar imposto por cima. Vale para as duas transportadoras.
Retirada em pontos Blue Express (PUDO)
Pickup point carrier: oferece entrega em um ponto Blue Express escolhido pelo cliente, como segunda transportadora ao lado da entrega em domicílio. Desativada por padrão. É o mesmo interruptor do status da transportadora Blue Express pickup point em Shipping > Carriers.
Pickup point name: o nome da transportadora exibido no checkout para retirada em um ponto Blue Express. Padrão: Blue Express pickup point. Obrigatório, no máximo 64 caracteres.
API Blue Express (necessária para tarifas em tempo real)
API key: a sua chave de API da Blue Express (cabeçalho x-api-key). Sem ela, só os preços fixos são usados. Após salvar, o campo fica vazio e exibe A key is saved - leave empty to keep it. Digite um valor novo apenas se quiser alterá-la. Marque Remove the saved API key e salve para excluí-la.
Service: o serviço da Blue Express usado para a tarifa: Express (EX) (padrão), Prioritario (PY) ou SameDay (MD). Ele precisa estar habilitado no seu contrato com a Blue Express.
Origin district code: o código de distrito da Blue Express do local de onde você envia, por exemplo SCL para Santiago (padrão). Pergunte à Blue Express se não tiver certeza.
CLP per 1 unit of store currency: quando a moeda padrão da sua loja não é o CLP, o rótulo a mostra, por exemplo CLP per 1 EUR. Os preços da Blue Express são em pesos chilenos (CLP). Informe quantos CLP vale uma unidade da moeda padrão da sua loja, por exemplo 1050. Sem esse valor, as tarifas em tempo real não são usadas. É ignorado quando a moeda da loja é o CLP.
Preço
Rate source: como o preço é calculado. A tarifa em tempo real exige um endereço chileno com região e comuna (cidade). Os erros são gravados no log e nunca são mostrados ao cliente.
Fixed prices: uma linha por país no formato COUNTRY_CODE=PRICE, na moeda padrão da sua loja, sem impostos, por exemplo CL=4500 em uma loja em CLP ou CL=4.50 em uma loja em EUR. Vírgula ou ponto são aceitos como separador decimal. Linhas inválidas são ignoradas e listadas em um aviso ao salvar. Um país sem linha não recebe preço fixo, então as transportadoras ficam ocultas para ele quando o preço fixo é necessário. Os preços fixos podem ser usados para qualquer país.
Fixed price per: Order cobra o preço uma vez. Item (price x quantity) o multiplica pelo número de itens no carrinho. Isso se aplica apenas ao preço fixo. A tarifa da API é sempre para o envio inteiro.
Condições
Min weight (kg): oculta as transportadoras quando o carrinho pesa menos. 0 significa sem limite.
Max weight (kg): oculta as transportadoras quando o carrinho pesa mais. Padrão: 100. 0 significa sem limite; campo vazio significa 100 kg. Min weight (kg) não pode ser maior que Max weight (kg).
Minimum order subtotal: mostra as transportadoras somente a partir deste subtotal do carrinho (moeda da loja, após descontos, sem impostos). Deixe vazio para sempre mostrá-las.
Frete grátis
Free shipping: ativa o frete grátis a partir de um subtotal do carrinho.
Free from subtotal: o subtotal do carrinho (moeda da loja, após descontos, sem impostos) a partir do qual o frete é grátis. Usado apenas quando Free shipping está ativado.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece as duas transportadoras em todas as zonas. Os países ficam então limitados pela lista abaixo. Zonas criadas depois também são incluídas. Quando você desativa novamente, as transportadoras voltam às zonas que tinham antes.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais você envia. Usado apenas com Ignore shipping zones.
Avançado
Debug log: registra solicitações e decisões em logs/vfd_blex_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados. A chave de API e os endereços dos clientes nunca são registrados. Desative o log quando terminar.
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 exclui as configurações e as transportadoras. Os pontos de retirada salvos nos pedidos são mantidos.
Regiões chilenas (exibido somente quando a sua loja não tem regiões chilenas utilizáveis)
A Blue Express precisa da região de um endereço chileno (RM, VS etc.) para a tarifa em tempo real. O PrestaShop não inclui regiões chilenas por padrão. Clique em Add Chilean regions para adicionar as 16 regiões chilenas como estados do Chile, com os códigos que a Blue Express usa, e para exibir o campo de região no formulário de endereços chilenos. As regiões que você já tem, por código ou por nome, não são adicionadas duas vezes. Nada é alterado até que você clique no botão. Você também pode adicioná-las manualmente em International > Locations > States com os códigos RM, VS etc.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço de cada transportadora Blue Express. Apenas produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica Countries (com Ignore shipping zones), o peso do carrinho e o Minimum order subtotal. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Blue Express.
Para uma tarifa em tempo real, o endereço deve estar no Chile, com região e cidade (comuna). O módulo primeiro pede à Blue Express que reconheça a comuna e depois solicita o preço para o serviço, o distrito de origem, o destino e os volumes. Cada produto é enviado com peso e dimensões convertidos para kg e cm. Produtos sem peso ou tamanho são enviados como 0,01 kg, 10 x 10 x 10 cm. O valor declarado é enviado em CLP. O preço em CLP é convertido para a moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente.
As tarifas ficam em cache por 1 hora e os dados das comunas por 12 horas. Uma chamada à API que falhou fica registrada por 5 minutos, e o tempo limite é de 10 segundos, para que uma API lenta ou indisponível não atrase cada atualização da finalização de compra. Erros da API nunca são mostrados ao cliente: a transportadora fica oculta ou, no modo de preço fixo de contingência, o preço fixo é usado. O motivo é gravado no log.
Se você editar uma 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 não cria envios nem etiquetas na Blue Express, não atribui números de rastreamento e não mostra atualizações de rastreamento. Crie o envio na sua conta da Blue Express. Não existem tabelas de tarifas regionais por comuna: use a tarifa da API da Blue Express ou um preço fixo por país. As tarifas em tempo real funcionam apenas para o Chile.
Pontos de retirada
Quando o cliente seleciona Blue Express pickup point na etapa de entrega, aparece abaixo uma caixa com o botão Choose pickup point. O botão abre o mapa oficial da Blue Express, onde o cliente escolhe um ponto. O ponto escolhido é exibido com nome e endereço, e o botão muda para Change pickup point. O ponto é salvo no carrinho e a tarifa é recalculada com o preço de retirada Blue Express (PUDO). Se o preço mudar, a página é recarregada para mostrá-lo. Até que um ponto seja escolhido, a transportadora mostra o preço da entrega em domicílio.
O cliente não consegue continuar sem um ponto: Please choose a Blue Express pickup point. A loja verifica isso quando o cliente clica em Continue na etapa de entrega. Um código de ponto malformado é recusado com The selected Blue Express pickup point is not valid. Please choose it again on the map., e a escolha anterior é mantida.
Ao fazer o pedido, o ponto é salvo nele com o código de agência da Blue Express, o nome e o endereço. Na página de pedido do back office, ele aparece no bloco Blue Express pickup point. Clique em Edit para escolher outro ponto com Choose on the Blue Express map ou para digitar manualmente o Agency code, o Name e o Address, depois clique em Save pickup point. A alteração é registrada como mensagem privada do pedido. Alterar o ponto exige apenas permissão de edição de pedidos, não acesso às páginas de Módulos. O cliente vê o ponto na página de confirmação do pedido, na página de detalhes do pedido e no e-mail de confirmação do pedido, ao lado do nome da transportadora. O novo e-mail de pedido enviado à loja (do módulo Mail alerts) também mostra o código de agência. Pedidos existentes mantêm os dados do ponto de retirada.
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 Blue Express é o primeiro bloco de Modules > Module Manager > VibeFox Blue Express > Configure, acima das configurações. Informe 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 aparecem a linha Product: presta-shipping-blue-express 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 seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar um slot 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, inclusive em uma configuração multiloja. Remover a chave da loja não libera o slot do domínio. Libere o slot na sua conta vibefox.net.
Sem uma chave ativa, as transportadoras Blue Express não são exibidas 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 as transportadoras também ficam ocultas para você: você pode configurar o módulo antes de comprar uma chave, mas não pode 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 informada, 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 Blue Express não aparece no checkout: verifique se a licença está ativa e se Enable/Disable (ou Pickup point carrier) está ativado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones e confira Countries. Leia os avisos no topo da página do módulo. Verifique os limites de peso, o Minimum order subtotal e se Fixed prices tem uma linha para o país, caso use preços fixos ou a contingência. Produtos também podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: com Blue Express API only, as transportadoras ficam ocultas quando não há tarifa. Ative Debug log, recarregue o checkout e veja o campo Log na página do módulo. Motivos comuns: sem chave de API, moeda da loja diferente de CLP sem taxa de câmbio, região ou comuna ausente no endereço, comuna não reconhecida pela Blue Express ou erro da API (por exemplo HTTP 401 ou 403 quando a chave de API é rejeitada). Com Blue Express API, fixed price if the API gives no rate, os clientes continuam recebendo o preço fixo enquanto você corrige o problema.
Endereços chilenos sem região: a página mostra um aviso sobre regiões ausentes. Clique em Add Chilean regions na página do módulo. Clientes cujos endereços foram salvos sem região precisam editar o endereço e escolher a região.
Imposto sendo somado ao preço da Blue Express: os preços da Blue Express incluem IVA. Defina Tax status como None (no tax on shipping).
O mapa não abre: o mapa é carregado a partir de widget-pudo.blue.cl no navegador do cliente, então esse endereço precisa estar acessível e não bloqueado no seu site.
Tarifas parecem desatualizadas após uma alteração: clique em Save na página do módulo. Isso limpa as tarifas e os dados de comunas em cache.
A página diz que falta uma transportadora Blue Express: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente. A redefinição mantém as suas configurações e o status das transportadoras.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Blue Express e escolha Uninstall. A chave de licença, o status da licença e as tarifas em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as duas transportadoras são excluídas (os pedidos mantêm o histórico), e as configurações, o log e os pontos de retirada não vinculados a um pedido são removidos. Se estiver desativado, as transportadoras apenas ficam desativadas e todas as configurações são mantidas. Instalar o módulo novamente restaura as transportadoras com o status que tinham antes. Pontos de retirada salvos em pedidos nunca são removidos.
A Blue Express é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Blue Express.