VibeFox Purolator for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP. A extensão SOAP do PHP não é necessária.

Purolator E-Ship Web Services (somente para tarifas em tempo real): cadastre-se no E-Ship Web Services no Purolator E-Ship Resource Centre, no site da Purolator. A Purolator fornece chaves e senhas separadas para os ambientes de desenvolvimento e de produção. Você também precisa do número da sua conta de faturamento Purolator e do código postal canadense de onde envia. Se usar apenas preços fixos, não precisa de chaves de API.

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 envio terminar, clique em Configure, ou encontre depois VibeFox Purolator na lista de módulos e clique em Configure.

3. Insira 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. Para tarifas em tempo real, preencha a seção Purolator API (live rates). Para testes, ative Development environment com a chave de desenvolvimento. Preencha Country prices ou Fallback price se quiser preços fixos ou um preço alternativo (veja Configuração). Clique em Save.

Na instalação, o módulo cria a transportadora Purolator com o texto de prazo de entrega Purolator courier. A transportadora é atribuída a todas as zonas 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 ficam na página do módulo: Modules > Module Manager > VibeFox Purolator > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas da Purolator em cache.

Se as tarifas em tempo real não puderem funcionar com os valores salvos (chave, senha ou conta de faturamento ausente, sem código postal canadense de origem, sem taxa CAD), ou se não houver nem credenciais de API nem preços fixos, um aviso aparece acima das configurações. Um aviso também aparece se a unidade de peso da loja não for uma que o módulo conhece (kg, g, lb, oz e similares). Nesse caso, os pesos dos produtos são considerados em kg. Defina a unidade de peso em International > Localization (Local units).

Um campo numérico que não contém um número igual ou maior que 0 não é salvo. Um aviso indica o campo e o valor. O campo fica vazio ou, nos campos de peso, recebe o valor padrão. Um valor incorreto em Country prices é salvo como 0, e o aviso indica o país e a coluna. Se Min cart weight for maior que Max cart weight, nada é salvo e um erro é exibido.

Geral

Enable Purolator: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Method title: o nome da transportadora exibido no carrinho e na finalização da compra. Padrão: Purolator. Obrigatório, no máximo 64 caracteres.

Tax: a regra de imposto da transportadora, ou No tax. Ela define se a loja adiciona imposto sobre o custo do frete. Para endereços canadenses, o total da Purolator já inclui GST/HST/PST/QST. Veja Canadian sales taxes abaixo.

API Purolator (tarifas em tempo real)

Com a chave de API, a senha e a conta de faturamento preenchidas, o preço vem do serviço web Purolator E-Ship Estimating. Se a Purolator não retornar uma tarifa, usa-se o preço fixo, ou a transportadora fica oculta quando não há nenhum. A seção tem um link para o Purolator E-Ship Resource Centre, onde você se cadastra e obtém as chaves.

API key: sua chave E-Ship Web Services para o ambiente selecionado. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.

API password: a senha que corresponde à chave. Assim como a chave, ela não é mais exibida após salvar.

Billing account number: o número da sua conta Purolator. As estimativas usam as tarifas dessa conta. O ambiente de desenvolvimento aceita a conta de teste da documentação da Purolator. Limpar este campo também remove a chave e a senha de API salvas.

Development environment: usa o ambiente de desenvolvimento da Purolator (devwebservices.purolator.com) com a chave de desenvolvimento. Os preços são dados de teste. Desative em uma loja em produção.

Ship-from postal code: o código postal canadense de onde os pacotes são enviados, por exemplo L4W 5M8.

Service in Canada: Cheapest available (padrão), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM ou Purolator Express Evening.

Service to the USA: Cheapest available (padrão), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM ou Purolator Express U.S. 12:00.

International service: Cheapest available (padrão), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM ou Purolator Express International 12:00.

Se o serviço escolhido não for oferecido para o endereço, usa-se o mais barato disponível.

Canadian sales taxes: use preços da Purolator sem GST/HST/PST/QST. Para endereços canadenses, o total da Purolator inclui esses impostos. Ative quando a transportadora tiver uma regra de imposto em Tax, para que o imposto não seja cobrado duas vezes.

CAD → (shop currency) rate: os preços da Purolator estão em CAD. Se a moeda padrão da sua loja não for o CAD, informe quantas unidades da sua moeda valem um CAD, por exemplo 0.68. Sem esse valor, as tarifas em tempo real não são usadas. Se a moeda padrão for o CAD, deixe o campo vazio.

Default product weight: em kg, usado para cada produto sem peso. Padrão: 0.5. Os pesos são convertidos a partir da unidade de peso da loja e enviados à Purolator como peso total em libras inteiras, arredondado para cima.

Preços fixos (usados sem credenciais de API e como alternativa quando a API não retorna tarifa)

Country prices: um preço por país e peso do carrinho, na moeda padrão da loja, sem impostos. Clique em Add country para adicionar uma linha e no ícone de lixeira para remover uma. Escolha * Default (all other countries) para uma linha que cubra todos os países sem linha própria. Cada linha tem um preço Base e colunas de tamanho: XS até 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg e XL acima de 5 kg. Um preço de tamanho vazio ou zero usa Base. Um Base de 0, ou um Base vazio, significa frete grátis para os pesos sem preço de tamanho próprio. Tanto 9.99 quanto 9,99 são aceitos. Linhas sem nenhum preço não são salvas, e só uma linha por país é mantida.

Fallback price: o preço para um país que não tem linha em Country prices nem linha *. Deixe vazio para ocultar a transportadora nesses países.

Fixed price per: Order cobra o preço uma única vez. Item (price × quantity) o multiplica pelo número de itens no carrinho. Isso se aplica apenas aos preços fixos. As tarifas em tempo real são sempre calculadas para o envio inteiro.

Condições

Min cart weight: em kg, oculta a transportadora quando o carrinho pesa menos. 0 significa sem limite.

Max cart weight: em kg, oculta a transportadora quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite.

Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe vazio para sempre mostrá-la.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega é grátis. Nesse caso, nenhuma solicitação é enviada à Purolator. Deixe vazio para nunca oferecer frete grátis.

Para estas condições, o peso do carrinho conta produtos sem peso como 0.

Disponibilidade sem zonas de envio

Normalmente, a transportadora é oferecida nas zonas às quais está atribuída em Shipping > Carriers.

Ignore shipping zones: oferece a Purolator para os países abaixo, qualquer que seja a zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas, e zonas criadas depois também são incluídas. Desligar a opção remove essas zonas novamente.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativos da loja. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de tarifas em logs/vfd_prlr_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 o log de depuração desligado. Chaves de API, a conta de faturamento e os códigos postais dos clientes não são registrados. Desligue o log quando terminar.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.

Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações, a transportadora, as tarifas em cache e os logs. Quando desativado, tudo é mantido para uma reinstalação.

Como funciona na finalização da compra

Na etapa de entrega, o PrestaShop pede ao módulo o preço da Purolator. Só contam produtos físicos: produtos virtuais não somam peso e não entram no valor do pedido. Antes de o cliente informar um endereço, o preço é estimado para o país que a loja usa para estimativas. O módulo verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Purolator. Depois ele procura um preço: primeiro a tarifa da Purolator em tempo real, depois a tabela por país e, por fim, o preço alternativo. Se não houver preço, a transportadora fica oculta.

Com credenciais de API, o módulo envia à Purolator uma solicitação Quick Estimate: a sua conta de faturamento, o código postal de origem, a cidade, a província ou o estado do cliente, o país e o código postal, e o peso total do carrinho em libras inteiras. Para o Canadá é necessário um código postal válido; para os EUA, um código ZIP válido; os demais países são enviados com o código postal como foi digitado. Dimensões (peso dimensional) não são enviadas. A Purolator responde em francês ou inglês, conforme o idioma do cliente. A Purolator retorna os preços de todos os serviços; o módulo usa o serviço escolhido ou o mais barato, remove os impostos de venda canadenses se configurado e converte o preço de CAD. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.

Cada resposta fica em cache por 1 hora. Uma solicitação com falha fica em cache por 10 minutos, para que uma queda da Purolator não deixe lenta cada atualização da finalização da compra. O tempo limite da API é de 10 segundos.

Se a Purolator não retornar uma tarifa (API fora do ar, credenciais ou código postal incorretos, serviço indisponível, sem taxa CAD), o cliente não vê erro. Usa-se o preço fixo, ou a transportadora fica oculta se não houver preço fixo. O motivo é gravado no log.

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 calcula apenas tarifas. Ele não cria envios Purolator, não imprime etiquetas, não agenda coletas, não trata devoluções e não rastreia pacotes. Não usa o Full Estimate (dimensões, várias peças, opções como assinatura ou mercadorias perigosas), não mostra datas de entrega, não exibe vários serviços como transportadoras separadas e não busca taxas de câmbio automaticamente.

Pedidos

Quando um pedido é feito com uma tarifa da Purolator em tempo real, o serviço é salvo com o pedido. Recálculos posteriores do carrinho não o alteram. Na página do pedido no back office (Orders > Orders, abra o pedido), um bloco Purolator mostra o Purolator service (nome e código) e o Live rate (excl. tax). Pedidos com preços fixos ou com frete grátis não têm esse bloco.

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 Purolator é o primeiro bloco na página Modules > Module Manager > VibeFox Purolator > 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-purolator 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 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 ú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 Purolator não é exibida aos clientes na finalização da compra, e nenhuma tarifa é solicitada ou calculada. A vitrine do 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 da 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 precisam de renovação. O status é verificado de novo 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. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A Purolator não aparece na finalização da compra: verifique se a licença está ativa e se Enable Purolator 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). Confira os limites de peso e Minimum order amount. Se a Purolator não retornar uma tarifa, a transportadora só aparece com um preço por país, uma linha * ou um Fallback price. Produtos também podem ser limitados a determinadas transportadoras na página do produto.

As tarifas em tempo real não aparecem: veja o campo Log na página do módulo. Erros da API sempre aparecem ali. Ative o Debug log e recarregue a finalização da compra para ver detalhes. Com chaves de API, o endereço precisa ter um código postal válido (Canadá) ou um código ZIP (EUA). Confira também os avisos acima das configurações.

HTTP 401 no log: a chave ou a senha da API não corresponde ao ambiente selecionado. Chaves de desenvolvimento funcionam apenas com Development environment ligado; chaves de produção, apenas com ele desligado.

A tarifa é diferente do site da Purolator: o Quick Estimate usa as tarifas da sua conta de faturamento e o peso total arredondado para cima em libras inteiras, sem peso dimensional. Para endereços canadenses, o total inclui impostos de venda; use Canadian sales taxes se a transportadora tiver uma regra de imposto. Os preços são convertidos com a sua CAD → (shop currency) rate.

Um valor desapareceu depois de salvar: leia o aviso exibido após Save. O valor não era um número igual ou maior que 0, por isso não foi salvo. Digite-o novamente como um número simples.

As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as tarifas da Purolator em cache.

A página diz que a transportadora Purolator não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para recriá-la.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Purolator e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas 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, os serviços Purolator salvos nos pedidos e o log são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas; pedidos já feitos mantêm o serviço Purolator. Reinstalar o módulo ou usar um Reset devolve à transportadora o status que ela tinha antes.

A Purolator é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Purolator.