VibeFox Mondial Relay for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superiores (testado na 4.1.0.3) com o tema padrão.

PHP: 8.0 ou superior.

Conta da Mondial Relay: o código de marca (Enseigne) e a chave privada vêm com uma conta empresarial da Mondial Relay: veja 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 disponibiliza o código de marca BDTEST13 com a chave privada PrivateK.

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 o README.txt, o pacote do OpenCart 3 vfd_mondialrelay-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_mondialrelay.ocmod.zip. Instale somente 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, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_mondialrelay-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ê pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Mondial Relay e clique em Install (o botão verde +).

3. Clique em Edit (o botão de lápis) para abrir a página de configurações.

4. Insira a 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. Digite o seu código de marca (Enseigne) e, para o modo de lista, a chave privada. Preencha Country prices (por exemplo, uma linha para a França) ou um Fallback cost, ative Enable/Disable e clique em Save.

OpenCart 4

1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_mondialrelay.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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Mondial Relay, 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 para o 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ê ative Enable/Disable e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações mantidas voltam a ser usadas.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Mondial Relay > 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 as listas de pontos de retirada em cache. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.

Os avisos no topo da página mostram problemas que ocultam o método: código de marca ausente, chave privada ausente no modo de lista, nenhum preço para a França, a Bélgica ou a Espanha, e uma unidade de peso da loja que a extensão não reconhece (os pesos dos produtos são então lidos como kg). Se Name estiver vazio, tiver mais de 64 caracteres ou contiver algum dos caracteres < > ; = # { }, se Min weight (kg) for maior que Max weight (kg), ou se o código de marca não for válido, a página mostra um erro e nada é salvo. Um campo numérico com um valor que não é um número (ou é negativo) é informado após Save e mantém o valor anterior; as demais configurações são salvas.

Geral

Entrega em Point Relais da Mondial Relay para a França, a Bélgica, Luxemburgo, a Espanha, Portugal e os Países Baixos. O método é oferecido em sua zona geográfica (veja Availability) ou, com Ignore shipping zones, nos países listados.

Enable/Disable: mostra ou oculta a Mondial Relay na finalização de compra. Padrão: desativado.

Name: o nome do método de envio mostrado aos clientes no carrinho e na finalização de compra. Padrão: Mondial Relay Point Relais. Obrigatório, até 64 caracteres.

Tax status: None (padrão) significa que os preços da tabela são finais. A opção Taxable com o nome de uma classe de imposto significa que o OpenCart acrescenta sobre os preços o imposto de frete dessa classe.

Sort order: a posição da Mondial Relay entre os métodos de envio na finalização de compra. Um número inteiro.

Conta da Mondial Relay

Brand code (Enseigne): obrigatório, até 8 letras e algarismos, 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, então o método não aparece na finalização de compra.

Private Key: necessária somente para o seletor List of nearest points. Após salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um valor novo somente 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 chave privada estão definidos, a conexão com o Web Service da Mondial Relay é testada sempre que você salva as configurações, e uma mensagem indica se eles são válidos.

Seletor de ponto de retirada

O cliente deve escolher um Point Relais antes de prosseguir para a etapa de pagamento. O ponto é salvo no pedido.

Seletor: como o cliente escolhe um Point Relais.

Tarifas (na moeda padrão da sua loja, sem impostos)

A Mondial Relay não tem uma API pública de tarifas: o preço vem desta tabela.

Country prices: preço por país de destino e peso do pacote. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. Escolha * Default como país para todos os outros países. Cada linha tem um 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 0 usa a coluna Price. Se o Price também estiver vazio, a entrega para esse peso é gratuita, então preencha o Price quando usar apenas algumas colunas de peso. Decimais com ponto ou vírgula (4.90 ou 4,90). Linhas sem nenhum preço e linhas com um país desconhecido são removidas ao salvar, e valores que não são números são informados e ficam vazios.

Fallback cost: usado para países sem linha na tabela. Deixe vazio para ocultar o método para eles.

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 é gratuita. Deixe vazio para não ter frete grátis.

Disponibilidade

Min weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite (padrão).

Max weight (kg): oculta o método quando o carrinho pesa mais. A Mondial Relay aceita pacotes de até 30 kg nos Points Relais. Padrão: 30. 0 significa sem limite. Campo vazio significa 30 kg.

Minimum subtotal: mostra o método somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, sem impostos) é pelo menos este valor. Deixe vazio para sempre mostrar.

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. Não é verificada quando Ignore shipping zones está ativado.

Ignore shipping zones: quando ativado, a Geo zone não é verificada: o método é oferecido somente nos países abaixo, ou em todos os países suportados se a lista estiver vazia.

Countries (ignore zones): os países de destino para esse modo. Este campo é usado somente quando Ignore shipping zones está ativado. A lista contém apenas os países com Points Relais.

Avançado

Debug log: grava os cálculos de tarifas, as chamadas ao Web Service e as escolhas de ponto em storage/logs/vfd_mrel_debug.log.php (no OpenCart 4, system/storage/logs/vfd_mrel_debug.log.php). O arquivo não pode ser lido pela web. Erros são sempre registrados, mesmo com esta opção desativada. Chaves e dados de clientes nunca são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_mrel_debug.old.log.php e um novo log é iniciado.

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, ao desinstalar a extensão as configurações e o log são excluídos. Quando desativado (padrão), eles são mantidos para uma reinstalação. As listas de pontos em cache são sempre removidas. Os pontos de retirada salvos nos pedidos são mantidos.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON, sem a chave privada.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. As mesmas verificações de Save se aplicam. A chave privada salva é mantida.

Como funciona na finalização de compra

O método só é oferecido para países com Points Relais: França, Bélgica, Luxemburgo, Espanha, Portugal e Países Baixos. Ele fica oculto quando os clientes não conseguiriam escolher um ponto: sem código de marca, ou no modo de lista sem a chave privada. Se uma Geo zone estiver definida e o endereço estiver fora dela, o método não é oferecido. Com Ignore shipping zones ativado, a zona geográfica não é verificada e somente os países dessa lista são atendidos (todos os países suportados, se ela estiver vazia).

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço. Somente produtos com Requires Shipping definido como Yes contam: os outros produtos não somam peso e não entram no subtotal. Os pesos dos produtos são convertidos da classe de peso do OpenCart para kg. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. A extensão 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, o Price. Sem linha, usa-se o custo alternativo. Se não houver preço, o método fica oculto. Se o subtotal atingir Free shipping from, o preço passa a ser 0. O preço é calculado na moeda padrão da sua loja, arredondado para as suas casas decimais e exibido na moeda do cliente com o imposto da Tax status selecionada. Nenhuma requisição é enviada à Mondial Relay para calcular o preço.

No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe a Mondial Relay na janela Shipping method options. Os preços são os mesmos do OpenCart 3.

A extensão não consulta tarifas em tempo real: a Mondial Relay não tem API pública de tarifas. Ela não cria envios, não imprime etiquetas e não rastreia pacotes. 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 opção Mondial Relay na etapa do método de envio, uma caixa Mondial Relay pickup point aparece 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 sua 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 para ela. 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 de imediato para a sessão do cliente. Um ponto é obrigatório. Quando o cliente clica em Continue, a loja verifica o ponto novamente. Sem um ponto, o cliente vê Please choose a Mondial Relay pickup point. e não consegue prosseguir para o pagamento. Um ponto de outro país que não o do endereço de entrega é recusado com uma mensagem informando que o ponto não está no país de entrega. No modo lista, o ponto também é conferido com a lista do endereço. Depois que o pedido é feito, a escolha é apagada, então o próximo carrinho escolhe novamente.

No OpenCart 4, a caixa Mondial Relay pickup point aparece na janela Shipping method options, abaixo da opção Mondial Relay, e o mapa abre dentro dessa janela. A tecla Escape fecha somente o mapa. O botão Continue da janela não avança sem um ponto válido, com as mesmas mensagens.

Quando o pedido é feito, o ponto permanece vinculado a ele. O método de envio do pedido mostra o nome do método seguido do nome, do endereço e do número do ponto, por exemplo Mondial Relay Point Relais: TABAC DU LOUVRE, 12 RUE DE RIVOLI, 75001 PARIS (FR-066974), para que o cliente veja isso no e-mail do pedido e no histórico de pedidos da sua conta. O e-mail de novo pedido para a loja mostra o ponto com o seu número no bloco de comentários. Em Sales > Orders, a página do pedido mostra um painel Mondial Relay pickup point com o nome do ponto, o endereço e o número Point Relais, ou No Point Relais was saved for this order. No OpenCart 4 a caixa é mostrada acima de History. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo, e o ponto do pedido é atualizado junto. Se o cliente trocar esse pedido para outro método de envio, o ponto dele é removido.

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 Mondial Relay é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-mondialrelay 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 de modificação 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 com 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Mondial Relay não é mostrada aos clientes na finalização de 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 enxerga o login do admin, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece 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 precisam de renovação. O status é verificado novamente de forma automática quando você abre 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 é necessário 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 Mondial Relay não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ativado. Verifique Geo zone, ou Ignore shipping zones e a sua lista de países. Verifique os avisos no topo da página da extensão: o método fica oculto sem código de marca, no modo de lista sem a chave privada, para um país sem preço, fora dos limites de peso e de subtotal, e para países sem Points Relais. Verifique se os produtos têm Requires Shipping definido como Yes.

O teste do Web Service falhou após salvar: a mensagem mostra o erro da Mondial Relay, por exemplo um código de marca inválido ou uma chave de segurança inválida. Verifique o código de marca e a chave privada 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 da extensão 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, ou uma Content Security Policy da sua loja, não os está bloqueando. Se o mapa não puder ser carregado, o cliente vê "Não foi possível carregar o mapa da Mondial Relay. 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 "Warning: You do not have permission to modify VibeFox Mondial Relay!": 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_mondialrelay (OpenCart 3) ou extension/vfd_mondialrelay/shipping/vfd_mondialrelay (OpenCart 4) em System > Users > User Groups.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Mondial Relay. 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 status e Geo zone. As listas de pontos em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as demais configurações e o log de depuração também são excluídos. Se estiver desativado, eles são mantidos e voltam a ser usados quando você instalar a extensão novamente. Os pontos de retirada salvos nos pedidos são sempre mantidos, e 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, depois da desinstalação acesse Extensions > Installer e clique em Uninstall (o botão laranja −) ao lado de VibeFox Mondial Relay na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Mondial Relay é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Mondial Relay.