VibeFox Mondial Relay for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x. A finalização de compra funciona com os temas Classic e Hummingbird.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Conta da Mondial Relay: o código de marca (Enseigne) e a Private Key são fornecidos com uma conta empresarial da Mondial Relay: consulte a seção para profissionais em mondialrelay.fr, a sua área do cliente "Connect" ou o seu contato comercial. O seletor de mapa precisa apenas do código de marca. A lista dos pontos mais próximos precisa dos dois. Para testes, a Mondial Relay fornece o código de marca BDTEST13 com a Private Key PrivateK.
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 Mondial Relay depois na lista de módulos e clique em Configure.
3. Informe 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. Informe seu código de marca (Enseigne) e, para o modo de lista, a Private Key. Preencha Country prices e clique em Save.
Na instalação, o módulo cria a transportadora Mondial Relay Point Relais com o texto de prazo de entrega Delivery to a Mondial Relay Point Relais of your choice. A transportadora é atribuída a todos os grupos de clientes e às zonas da França, Bélgica, Luxemburgo, Espanha, Portugal e Países Baixos. 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 Mondial Relay > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as listas de pontos de retirada em cache.
Os avisos no topo da página mostram problemas que ocultam a transportadora: código de marca ausente, Private Key ausente no modo de lista, nenhum preço para a França, Bélgica ou Espanha, ou transportadora excluída. Valores que não podem ser salvos são informados após Save: um campo numérico com um valor que não é número (ou é negativo) mantém o valor anterior. Um nome com mais de 64 caracteres, ou um Min weight (kg) maior que Max weight (kg), é recusado e nada é salvo. Se a unidade de peso da loja não for uma que o módulo conhece, um aviso informa que os pesos dos produtos são considerados em kg.
Geral
Enable/Disable: liga ou desliga a Mondial Relay. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado aos clientes na finalização de compra. Padrão: Mondial Relay Point Relais. Obrigatório, até 64 caracteres.
Tax status: None significa que os preços da tabela são finais. A opção Taxable com o nome de uma regra de imposto significa que o PrestaShop acrescenta o imposto de envio dessa regra sobre os preços.
Conta da Mondial Relay
Brand code (Enseigne): obrigatório, até 8 letras e números, por exemplo BDTEST13 para testes. Usado pelo mapa de pontos de retirada e pelo Web Service. Sem ele, os clientes não podem escolher um Point Relais, e a transportadora não é exibida na finalização de compra.
Private Key: necessária apenas para o seletor List of nearest points. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um novo valor apenas para alterá-la. Para excluir a chave salva, marque Remove the saved Private Key e clique em Save. Quando o código de marca e a Private Key estão preenchidos, a conexão com o Web Service da Mondial Relay é testada a cada vez que você salva as configurações, e uma mensagem mostra se são válidos.
Seletor do ponto de retirada
Selector: como o cliente escolhe um Point Relais.
Tarifas (na moeda padrão da sua loja, sem impostos)
Country prices: preço por país de destino e peso do pacote. Clique em + Add country para adicionar uma linha e no ícone de lixeira para remover uma. Escolha * Default como país para todos os demais países. Cada linha tem uma coluna Price e colunas de peso: XS até 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg e XL acima de 5 kg. Uma coluna de peso vazia ou com 0 usa a coluna Price. Se a Price também estiver vazia, a entrega para aquele peso é grátis, então preencha Price quando usar apenas algumas colunas de peso. Decimais com ponto ou vírgula (4.90 ou 4,90). Linhas sem nenhum preço são descartadas ao salvar, e valores que não são números são informados e deixados em branco.
Fallback cost: usado para países sem linha na tabela. Deixe vazio para ocultar a transportadora nesses países.
Calculation type: como o preço é calculado.
Free shipping from: o subtotal do carrinho (após descontos, sem impostos) a partir do qual a entrega é grátis. Deixe vazio para não ter frete grátis.
Disponibilidade
Min weight (kg): oculta a transportadora quando o carrinho pesa menos. 0 significa sem limite.
Max weight (kg): oculta a transportadora quando o carrinho pesa mais. A Mondial Relay aceita pacotes de até 30 kg nos Points Relais. Padrão: 30. 0 significa sem limite. Um campo vazio significa 30 kg. Não pode ser menor que Min weight (kg).
Minimum subtotal: mostra a transportadora apenas quando o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) é pelo menos este valor. Deixe vazio para mostrá-la sempre.
Ignore shipping zones: oferece a transportadora para os países abaixo, ou para todos os países suportados quando a lista está vazia, mesmo onde as zonas da transportadora não os incluem. Enquanto estiver ativada, a transportadora fica vinculada a todas as zonas ativas, inclusive as que você criar depois. Ao desativá-la, a transportadora volta às zonas que tinha antes.
Countries (ignore zones): os países de destino para esse modo. Este campo só é usado quando Ignore shipping zones está ativada. A lista tem apenas os países com Points Relais.
Avançado
Debug log: grava os cálculos de tarifas e as chamadas ao Web Service em logs/vfd_mrel_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com esta opção desativada. Chaves e dados de clientes nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativada, desinstalar o módulo exclui as configurações e a transportadora. Quando desativada, desinstalar apenas desliga a transportadora. Os pontos de retirada salvos nos pedidos são mantidos.
Como funciona na finalização de compra
A transportadora é oferecida somente para países com Points Relais: França, Bélgica, Luxemburgo, Espanha, Portugal e Países Baixos. Ela fica oculta quando o cliente não poderia escolher um ponto: sem código de marca ou, no modo de lista, sem a Private Key.
Na etapa de envio, o PrestaShop pede ao módulo o preço. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica o peso do carrinho e o subtotal mínimo. O preço vem da linha do país (ou da linha *): a coluna de peso e, se não houver valor, Price. Sem linha, usa-se o custo alternativo. Se não houver preço, a transportadora fica oculta. Se o subtotal atingir Free shipping from, o preço passa a ser 0. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
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 consulta tarifas em tempo real: a Mondial Relay não tem uma API pública de tarifas. Ele não cria envios, não imprime etiquetas nem rastreia encomendas. Crie os envios no seu espaço "Connect" da Mondial Relay usando o número do Point Relais exibido no pedido. A entrega em domicílio (Domicile) não é oferecida.
Pontos de retirada
Quando o cliente seleciona a transportadora Mondial Relay na etapa de entrega, aparece um quadro Mondial Relay pickup point abaixo dela.
Modo mapa: o botão Choose a Point Relais abre em uma janela o mapa oficial da Mondial Relay para o país de entrega, o CEP e o peso do pacote. Depois que o cliente escolhe um ponto, ele é exibido como Selected: e o botão muda para Change Point Relais. O widget do mapa é carregado de widget.mondialrelay.com, e a biblioteca de mapas de unpkg.com, somente quando o cliente abre o mapa. Mencione isso na sua política de privacidade.
Modo lista: uma lista suspensa - Choose a Point Relais - mostra os 10 pontos mais próximos do CEP de entrega, com a distância. O ponto escolhido é exibido com o horário de funcionamento. A lista é carregada pelo seu servidor, então nenhum script de terceiros é executado no navegador. As listas ficam em cache por 12 horas, uma resposta vazia por 1 hora, e uma requisição com falha é lembrada por 5 minutos. O tempo limite do Web Service é de 10 segundos. Sem CEP, o cliente vê Enter your postcode to see the nearest pickup points. Se nenhum ponto for encontrado ou a lista não estiver disponível, o cliente vê uma mensagem como "A lista de pontos de retirada não está disponível no momento. Use o mapa." e o mapa é oferecido.
O ponto escolhido é salvo no carrinho imediatamente. Um ponto é obrigatório. Sem ele, o cliente vê Please choose a Mondial Relay pickup point. e não consegue seguir para o pagamento. Um ponto em outro país que o do endereço de entrega é recusado. No modo de lista, o ponto também é conferido com a lista do endereço.
Quando o pedido é feito, o ponto permanece com o pedido. A página do pedido no back office mostra o bloco Mondial Relay pickup point com o nome do ponto, o endereço e o Point Relais number (por exemplo FR-066974). O cliente vê o ponto na página de confirmação do pedido e nos detalhes do pedido em sua conta. No e-mail de confirmação do pedido e no e-mail de novo pedido do módulo Alertas por e-mail, o ponto é acrescentado após o nome da transportadora.
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 Mondial Relay é o primeiro bloco de Modules > Module Manager > VibeFox Mondial Relay > Configure, 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-mondialrelay 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 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 Mondial Relay não é exibida aos clientes na finalização de compra, e nenhuma tarifa é calculada. A loja PrestaShop não sabe que você está conectado ao 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 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 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 Mondial Relay 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 ative Ignore shipping zones. Confira os avisos no topo da página do módulo: a transportadora fica oculta sem código de marca, no modo de lista sem Private Key, para um país sem preço, fora dos limites de peso e subtotal, e para países sem Points Relais. Os produtos também podem ser limitados a certas transportadoras na página do produto.
Teste do Web Service falhou após salvar: a mensagem mostra o erro da Mondial Relay, por exemplo um código de marca ou uma chave de segurança inválidos. Verifique o código de marca e a Private Key com a Mondial Relay.
A lista de pontos está vazia ou indisponível: o cliente precisa primeiro informar um CEP de entrega. Se o Web Service falhar, o mapa é oferecido no lugar. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo para descobrir o motivo.
O mapa não abre: o mapa é carregado de widget.mondialrelay.com e unpkg.com. Verifique se um bloqueador de privacidade ou de scripts não os está bloqueando. Se o mapa não puder ser carregado, o cliente vê "O mapa da Mondial Relay não pôde ser carregado. Tente novamente mais tarde ou escolha outro método de envio."
A página do pedido diz No Point Relais was saved for this order: o pedido foi feito sem um ponto do país de entrega. O motivo é gravado no log. Peça ao cliente o Point Relais antes de criar o envio.
A página diz que a transportadora Mondial Relay não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Mondial Relay e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As listas de pontos de retirada em cache são sempre removidas. Se Remove data on uninstall estiver ativada, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e os pontos de carrinhos sem pedido são removidos. Se estiver desativada, a transportadora apenas é desligada e todas as configurações são mantidas. Instalar o módulo novamente restaura o status que a transportadora tinha antes. Os pontos de retirada salvos nos pedidos são sempre mantidos.
A Mondial Relay é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Mondial Relay.