VibeFox Purolator for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior, com a extensão cURL. A extensão SOAP do PHP não é necessária.

Purolator E-Ship Web Services (somente para tarifas em tempo real): registre-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 CEP canadense de onde envia. Se usar apenas preços fixos, não precisa de chaves de API.

Chave de licença VibeFox: adquirida 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_purolator-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_purolator.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 painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_purolator-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 do pacote para a pasta raiz da sua loja.

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

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

4. Informe 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. Para tarifas em tempo real, preencha a seção Purolator API (live rates): chave de API, senha, número da conta de faturamento, CEP canadense de origem e, se a moeda da loja não for CAD, a taxa de CAD. Para testar, ative Development environment com a chave de desenvolvimento. Preencha Country prices ou Fallback price se quiser preços fixos ou uma alternativa (veja Configuração). Ative Enable Purolator e clique em Save.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_purolator.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 Purolator, 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.

Após a instalação, o método fica desativado até que você ative Enable Purolator e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações Purolator que você manteve voltam a ser usadas.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Purolator > Edit. As seções aparecem à esquerda. Um botão Save na parte inferior salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas Purolator em cache. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.

Se as tarifas em tempo real não puderem funcionar com os valores salvos (chave, senha ou conta de faturamento ausente, nenhum CEP canadense de origem, nenhuma taxa de CAD), ou se não houver credenciais de API nem preços fixos, aparece um aviso na seção General. Ele também informa se, até lá, são usados os preços fixos ou se o método fica oculto. Um aviso também aparece se a unidade de peso da loja não for uma que a extensão conhece. Nesse caso, os pesos dos produtos são lidos como kg; adicione uma classe de peso com a unidade kg em System > Localisation > Weight Classes.

Um campo numérico que não contenha um número igual ou maior que 0 não é salvo. Uma mensagem após Save indica o campo e o valor. O campo fica vazio ou recebe o valor padrão nos campos de peso. Um valor incorreto em Country prices é salvo como 0, e a mensagem indica o país e a coluna. Nada é salvo e um erro é exibido se o título do método estiver vazio ou tiver mais de 64 caracteres, se Min cart weight (kg) for maior que Max cart weight (kg), se a ordem de classificação não for um número inteiro, ou se a classe de imposto ou a zona geográfica não forem válidas.

Geral

O cliente vê uma única tarifa Purolator. As configurações valem para todas as zonas geográficas. Você pode limitar o método a uma zona geográfica ou a países em Availability.

Enable Purolator: mostra ou oculta a Purolator na finalização de compra. Padrão: desativado.

Method title: o nome do método de envio exibido ao cliente na finalização de compra. Padrão: Purolator. Obrigatório, no máximo 64 caracteres.

Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Ela define se a loja acrescenta imposto por cima. Para endereços canadenses, o total da Purolator já inclui GST/HST/PST/QST. Veja mais abaixo Canadian sales taxes.

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

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 (Quick Estimate, pelo peso total do carrinho). Se a Purolator não retornar uma tarifa, usa-se o preço fixo, ou o método fica oculto quando não há um. A seção tem um link para o Purolator E-Ship Resource Centre, onde você se cadastra e obtém as chaves. Os detalhes dos erros vão para o log, nunca para o cliente.

API key: sua chave do 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 somente se quiser alterá-la.

API password: a senha que pertence à chave. Assim como a chave, ela não é mostrada novamente após salvar.

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

Development environment: usa o ambiente de desenvolvimento da Purolator (devwebservices) 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 CEP canadense de onde as encomendas são enviadas, por exemplo L4W 5M8. O OpenCart não tem um CEP da loja, então ele não é obtido do endereço da loja: informe-o aqui.

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: usa os preços da Purolator sem GST/HST/PST/QST. Para endereços canadenses, o total da Purolator inclui esses impostos. Ative quando a loja acrescentar imposto sobre o envio por conta própria (uma classe de imposto em General), para que o imposto não seja cobrado duas vezes. Padrão: desativado.

CAD → (store currency) rate: os preços da Purolator estão em CAD. Se a moeda padrão da loja não for CAD, informe quantas unidades da sua moeda equivalem a 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 CAD, deixe o campo vazio.

Default product weight (kg): usado para cada produto que não tem peso. Padrão: 0.5. Os pesos são convertidos a partir da classe de peso do produto 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 botão × para removê-la. 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 o método nesses países.

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

Condições

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

Max cart weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. Se deixar vazio, usam-se 30 kg. 0 significa sem limite.

Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe vazio para mostrar sempre.

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

Disponibilidade

Geo zone: oferece a Purolator somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é verificada quando Ignore shipping zones está ativado.

Ignore shipping zones: oferece o método para os países abaixo, independentemente da zona geográfica selecionada.

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

Avançado

Debug log: grava os cálculos de tarifas em storage/logs/vfd_prlr_debug.log.php (no OpenCart 4, system/storage/logs/vfd_prlr_debug.log.php). O arquivo não pode ser lido pela web. Erros de API são sempre registrados, mesmo com o log de depuração desativado. Chaves de API, a conta de faturamento e os CEPs dos clientes não são registrados. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_prlr_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 limpá-lo.

Remove data on uninstall: quando ativado, ao desinstalar a extensão são excluídas as configurações e o log da Purolator. Quando desativado, eles são mantidos para uma reinstalação. As tarifas em cache são sempre removidas. O serviço Purolator dos pedidos realizados é sempre mantido.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API e a senha não são exportadas.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. A chave de API e a senha salvas são mantidas.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da Purolator. Se uma Geo zone estiver definida e o endereço estiver fora dela, a Purolator não é oferecida (a menos que Ignore shipping zones esteja ativado). Só contam os produtos com Requires Shipping definido como Yes: os demais não somam peso nem entram no valor do pedido. A extensão verifica primeiro as condições: países permitidos (com Ignore shipping zones), peso do carrinho e valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada à Purolator. Caso contrário, a extensão procura um preço: primeiro a tarifa em tempo real da Purolator, depois a tabela por país e então o preço de alternativa. Se não houver preço, o método fica oculto.

Com credenciais de API, a extensão envia à Purolator uma solicitação Quick Estimate: a sua conta de faturamento, o CEP de origem, a cidade, a província ou o estado do cliente, o país e o CEP do cliente, e o peso total do carrinho em libras inteiras. Para o Canadá é necessário um CEP válido; para os EUA, um código ZIP válido; os demais países são enviados com o CEP como foi informado. As dimensões (peso dimensional) não são enviadas. A Purolator responde em francês quando o cliente vê a loja em francês, caso contrário em inglês. A Purolator retorna os preços de todos os serviços; a extensão usa o serviço escolhido ou o mais barato, remove os impostos sobre vendas canadenses se configurado, e converte o preço a partir de CAD. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela, e mostrado ao cliente na moeda dele com o imposto da Tax class selecionada.

Cada resposta fica em cache por 1 hora, então o mesmo carrinho não gera nova solicitação. 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 de compra. O tempo limite da API é de 10 segundos.

Se a Purolator não retornar uma tarifa (API fora do ar, credenciais ou CEP incorretos, serviço indisponível, nenhuma taxa de CAD), o cliente não vê erro. Usa-se o preço fixo, ou o método fica oculto quando não há preço fixo. O motivo é gravado no log.

A extensão calcula apenas tarifas. Não cria envios Purolator, não imprime etiquetas, não agenda coletas, não trata devoluções nem rastreia encomendas. Não usa a Full Estimate (dimensões, vários volumes, opções como assinatura ou mercadorias perigosas), não mostra datas de entrega, não apresenta vários serviços como opções separadas e não busca taxas de câmbio automaticamente. O cliente não vê o nome do serviço Purolator, apenas o título do seu método.

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 Purolator na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido é feito com uma tarifa Purolator em tempo real, o serviço é salvo com o pedido. Em Sales > Orders, a página do pedido mostra acima do histórico um painel Purolator com o Purolator service (nome e código) e a Live rate (excl. tax). O painel continua visível mesmo depois que o método é desativado. Pedidos precificados com os preços fixos ou com frete grátis não têm esse painel. O próprio pedido mostra o título do método e o custo do envio como qualquer outro método de envio do OpenCart.

O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo. O serviço Purolator salvo é atualizado junto, para a tarifa em tempo real mais recente. Se o pedido mudar para outro método de envio ou para um preço sem tarifa em tempo real, o serviço salvo é removido do pedido.

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 Purolator é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Purolator > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo estão a linha Product: opencart-shipping-purolator e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify 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 na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio Purolator não é mostrado aos clientes na finalização de compra e nenhuma tarifa é solicitada ou 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 Purolator não aparece na finalização de compra: verifique se a licença está ativa e se Enable Purolator está ativado. Verifique a Geo zone (ou se Ignore shipping zones está ativado e o país é permitido), os limites de peso e o Minimum order amount. Se a Purolator não retornar uma tarifa, o método só aparece com um preço por país, uma linha * ou um Fallback price. Confira se os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: veja o campo Log na página da extensão. Os erros da API sempre aparecem ali. Ative o Debug log e recarregue a finalização de compra para ver os detalhes. Com chaves de API, o endereço precisa de um CEP válido (Canadá) ou de um código ZIP válido (EUA). Verifique também os avisos na seção General.

HTTP 401 no log: a chave de API ou a senha não correspondem ao ambiente selecionado. Chaves de desenvolvimento só funcionam com Development environment ativado, e as de produção só com ele desativado.

A tarifa é diferente da que aparece no site da Purolator: a Quick Estimate usa as tarifas da sua conta de faturamento e o peso total arredondado para cima em libras inteiras, sem o peso dimensional. Para endereços canadenses, o total inclui os impostos sobre vendas; use Canadian sales taxes se você definiu uma Tax class. Os preços são convertidos com a sua CAD → (store currency) rate.

Um valor desapareceu após salvar: leia a mensagem exibida 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 da extensão. Isso limpa as tarifas Purolator em cache.

A página mostra "Warning: You do not have permission to modify VibeFox Purolator!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_purolator (OpenCart 3) ou extension/vfd_purolator/shipping/vfd_purolator (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API da Purolator pode ser substituído pela configuração vfd_prlr_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Purolator. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Purolator, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, também são excluídas as configurações e o log de depuração da Purolator. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os pedidos existentes mantêm o método de envio e o custo, e os serviços Purolator salvos nos pedidos são sempre mantidos.

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 Purolator na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Purolator é uma marca comercial de seu respectivo proprietário. Esta extensão não é afiliada à Purolator nem endossada por ela.