VibeFox Canada Post for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado com a 3.0.5.0) ou 4.0.2 e posteriores (testado com a 4.1.0.3).

PHP: 8.0 ou superior.

Canada Post Developer Program (somente para tarifas em tempo real): as tarifas em tempo real usam a Canada Post Rating API. Cadastre-se no Canada Post Developer Program no site do Canada Post e copie a sua chave de API e o seu número de cliente. A chave de API tem o formato username:password, e o Canada Post emite chaves separadas para os ambientes de desenvolvimento (sandbox) e de produção. Você também precisa 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 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 README.txt, o pacote do OpenCart 3 vfd_canada_post-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_canada_post.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 administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_canada_post-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. Encontre VibeFox Canada Post 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 License key).

5. Para as tarifas em tempo real, informe o nome de usuário e a senha da API, o seu número de cliente e o código postal de envio. Se a moeda padrão da sua loja não for CAD, informe a taxa em CAD. Preencha Country prices se quiser preços fixos ou um valor de reserva (veja Configuração). Ative Enable Canada Post e clique em Save.

OpenCart 4

1. No administrador, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_canada_post.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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 Shipping. Encontre VibeFox Canada Post, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Insira a chave de licença e as configurações como nos passos 4 e 5 do 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 Canada Post e salve. Se você reinstalar a extensão depois de desinstalá-la, as configurações mantidas serão usadas novamente.

Configuração

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

Quando um valor está errado, a página mostra um erro e nada é salvo: um campo numérico ou um preço em Country prices que não seja um número igual ou maior que 0 (por exemplo -1 ou 12abc), uma taxa CAD igual a 0, Min cart weight (kg) maior que Max cart weight (kg), um Method title com mais de 64 caracteres ou com os caracteres < > ; = # { }, um Sort order que não seja um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida. Se a loja não tiver uma classe de peso com a unidade "kg" nem uma classe de comprimento com a unidade "cm", a página avisa que pesos e dimensões são convertidos pelo nome da unidade de cada classe (kg, g, lb, oz; cm, mm, m, in) e que as demais unidades são lidas como kg ou cm.

Após salvar, a página mostra um aviso quando as configurações não podem funcionar como previsto: apenas um entre o nome de usuário e a senha da API está preenchido, o código postal de envio não é um código postal canadense (formato A1A 1A1), falta a taxa CAD para uma loja em outra moeda, ou não há credenciais de API nem preços fixos. O aviso também informa o que acontece enquanto isso: os preços fixos por país são usados, ou o método fica oculto na finalização de compra quando a tabela Country prices está vazia.

Geral

As configurações valem para todas as zonas geográficas. O preço sempre vem desta extensão: uma tarifa em tempo real do Canada Post ou os preços fixos por país.

Enable Canada Post: mostra ou oculta o Canada Post na finalização de compra. Padrão: desativado.

Method title: o nome do método de envio mostrado ao cliente na finalização de compra. Padrão: Canada Post, também quando o campo fica vazio. No máximo 64 caracteres.

Tax class: a classe de imposto que o OpenCart adiciona ao custo do frete, ou No tax (não tributável).

Sort order: a posição do Canada Post entre os métodos de envio na finalização de compra.

API do Canada Post (tarifas em tempo real)

Com o nome de usuário e a senha da API preenchidos, o preço vem da Canada Post Rating API. Se a API não retornar nenhuma tarifa (API indisponível, código postal errado, serviço não disponível), usa-se o preço fixo de Country prices, ou o método fica oculto quando não há nenhum. A seção traz um link para o Canada Post Developer Program, onde você encontra as chaves de API e o seu número de cliente. Os detalhes dos erros vão para o log, nunca para o cliente.

API username: a parte da chave de API antes dos dois-pontos. Use a chave de desenvolvimento com Sandbox e a chave de produção em uma loja real.

API password: a parte da chave de API depois dos dois-pontos. Após salvar, o campo fica vazio e mostra A password is saved. Leave empty to keep it; clear the API username and save to remove both. Digite um valor novo somente para alterá-la. A senha é salva exatamente como digitada e nunca é gravada no log.

Customer number: com um número de cliente, o Canada Post retorna as tarifas comerciais (com desconto) da sua conta. Deixe vazio para as tarifas de balcão (varejo). Os espaços são removidos.

Contract number: opcional, para clientes com contrato. É usado somente junto com o número de cliente.

Sandbox: usa o ambiente de desenvolvimento do Canada Post, para testes com a chave de API de desenvolvimento. Os preços são dados de teste. Desative em uma loja real. Padrão: desativado.

Ship-from postal code: o código postal canadense de onde os pacotes são enviados, por exemplo K1A 0B1. As tarifas em tempo real precisam dele.

Service in Canada: o serviço para endereços canadenses: o mais barato disponível, Regular Parcel (DOM.RP, padrão), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) ou Priority (DOM.PC).

Service to the USA: o mais barato disponível (padrão), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) ou Priority Worldwide parcel USA (USA.PW.PARCEL).

International service: o mais barato disponível (padrão), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) ou Priority Worldwide parcel International (INT.PW.PARCEL).

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

Use Canada Post prices without GST/HST/PST: para endereços canadenses, o preço do Canada Post inclui esses impostos. Ative quando o OpenCart adicionar ele mesmo o imposto sobre o frete (Tax class acima), para que o imposto não seja cobrado duas vezes.

CAD to … rate: o nome do campo mostra a moeda padrão da sua loja, por exemplo CAD to USD rate. Os preços do Canada Post estão em CAD. Se a moeda padrão não for 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 CAD, deixe vazio. A taxa deve ser maior que 0.

Default product weight (kg): enviado ao Canada Post para cada produto sem peso. Padrão: 0.5. Pesos e dimensões dos produtos são convertidos a partir das classes de peso e de comprimento deles, e o carrinho é calculado como um único pacote (até 30 kg).

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

Country prices: uma tabela de países com um preço Base e preços conforme o peso do carrinho, na moeda padrão da loja e sem impostos: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou igual a zero usa o preço Base. Clique em Add country para adicionar uma linha. A linha * All other countries define os preços de todos os países sem linha própria. Um país sem linha (e sem *) não tem preço fixo. Um preço base de 0 significa frete grátis para esse país.

Fixed price per: Order (padrão) cobra o preço uma vez. Item (price × quantity) 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 pacote inteiro.

Condições

Min cart weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão).

Max cart weight (kg): oculta o método acima deste peso do carrinho. Padrão: 25, também quando o campo está vazio. 0 significa sem limite. Pacotes do Canada Post podem pesar até 30 kg.

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

Free shipping: ative o frete grátis a partir do valor abaixo.

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) a partir do qual o frete é grátis. Nesse caso nenhuma solicitação é enviada à API. Usado somente quando Free shipping está ativo.

Geo zone: oferece o Canada Post somente para endereços nesta zona geográfica. All zones (padrão) significa em todas. Não é usado quando Ignore shipping zones está ativo. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Disponibilidade sem zonas de envio

Normalmente o método é oferecido na zona geográfica selecionada em Conditions.

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

Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países ativos da loja. Usado somente quando Ignore shipping zones está ativo.

Avançado

Debug log: grava os cálculos de tarifas em storage/logs/vfd_canada_post.log.php. O arquivo não pode ser lido pela web. Quando chega a 5 MB, é movido para vfd_canada_post.old.log.php e um novo log é iniciado. Erros da API são sempre registrados, mesmo com esta opção desativada. Chaves de API, números de cliente e códigos postais dos clientes não são registrados.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativo, desinstalar a extensão apaga as configurações, os serviços salvos dos pedidos, as tarifas em cache e o log. Quando desativado (padrão), eles são mantidos para uma nova instalação. Os pedidos nunca são alterados.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha da API não é exportada.

Import: cole um 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 senha da API salva é mantida enquanto o nome de usuário da API continuar preenchido.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço do Canada Post. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o Canada Post não é oferecido. Só contam os produtos com Requires Shipping definido como Yes: os demais não somam peso e não 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 recompensa 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 ao Canada Post.

Com credenciais de API, a extensão envia ao Canada Post o código postal de envio, o destino, o peso do pacote e, quando todos os produtos têm dimensões, o tamanho estimado do pacote. Para o Canadá o destino é o código postal, para os Estados Unidos o código ZIP, e para os demais países apenas o país. Uma tarifa em tempo real só é solicitada quando um endereço canadense ou americano tem código postal ou ZIP válido. O Canada Post retorna todos os serviços para o pacote. A extensão escolhe o serviço selecionado para o grupo de destino ou o mais barato, remove os impostos sobre vendas canadenses se Use Canada Post prices without GST/HST/PST estiver ativo, e converte o preço de CAD com a sua taxa. O preço é calculado na moeda padrão, 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, para que o mesmo carrinho e o mesmo endereço não disparem uma nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que uma instabilidade do Canada Post não atrase cada atualização da finalização de compra. O tempo limite da API é de 10 segundos. Pacotes acima de 30 kg não são enviados à API.

Se a API não retornar nenhuma tarifa, usa-se o preço fixo, ou o método fica oculto quando não há preço fixo. O cliente nunca vê os detalhes dos erros da API; eles vão para o log.

A extensão apenas calcula tarifas. Ela não cria envios, não imprime etiquetas, não cria manifestos ou devoluções e não rastreia pacotes. Os clientes não podem escolher uma agência ou um ponto de retirada. Mostra uma única tarifa do Canada Post, sem datas de entrega, opções de seguro ou assinatura. O carrinho é sempre calculado como um único pacote, e as taxas de câmbio não são atualizadas automaticamente.

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 o Canada Post na janela Shipping method options, por exemplo Canada Post - $12.50. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido é feito com o Canada Post, a extensão salva como o preço dele foi calculado. Na página do pedido no administrador (Sales > Orders, abra um pedido), um bloco Canada Post mostra:

Canada Post service: o nome e o código do serviço de uma tarifa em tempo real, por exemplo Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API), Fixed price ou Free shipping.

No OpenCart 4, o bloco aparece acima de History. A finalização de compra mantém um único pedido: quando o cliente confirma o pedido novamente, o serviço e a origem do preço salvos são substituídos, e são removidos se o cliente escolher outro método de envio.

O serviço não é adicionado aos e-mails de pedido nem à página de pedidos do cliente; eles mostram o nome do método e o custo do frete como qualquer outro método de envio do OpenCart.

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 Canada Post é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Canada Post > 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-canada-post 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 esta extensão podem alterar a chave. Os textos do bloco seguem o idioma do administrador (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 de alterar o endereço da loja, ou depois de 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 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 dela. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o Canada Post não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao administrador 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 vê o login do administrador, então, sem uma chave ativa, o método fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. 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 exigem a renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do administrador ou a página Edit: uma vez por dia nos primeiros 14 dias após a inserção da chave, e 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

O Canada Post não aparece na finalização de compra: verifique se a licença está ativa e se Enable Canada Post está ativado. Verifique a Geo zone, ou se Ignore shipping zones está ativado e o país é permitido. Confira os limites de peso e o Minimum order amount, e se os produtos têm Requires Shipping definido como Yes. Precisa existir uma tarifa: com credenciais de API, o endereço precisa de um código postal válido (Canadá) ou de um código ZIP (Estados Unidos); caso contrário, deve existir um preço fixo para o país ou para *.

As tarifas em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Ele mostra o motivo: nome de usuário ou senha da API ausente, código postal de envio ou de destino inválido, taxa CAD ausente, pacote acima de 30 kg ou a mensagem de erro do Canada Post. Enquanto isso, os clientes recebem o preço fixo, se houver.

A tarifa é diferente da exibida no site do Canada Post: com um número de cliente você obtém as tarifas comerciais (com desconto) da sua conta; sem ele, as tarifas de balcão (varejo). Para endereços canadenses, o preço do Canada Post inclui GST/HST/PST. Os preços são convertidos com a sua taxa CAD.

O imposto é cobrado duas vezes no frete: ative Use Canada Post prices without GST/HST/PST, ou defina Tax class como No tax.

Testar preços em uma loja real: desative Sandbox e use a chave de API de produção.

As tarifas parecem desatualizadas após uma alteração: clique em Save na página da extensão. Isso limpa as tarifas do Canada Post em cache.

A página diz "Warning: You do not have permission to modify VibeFox Canada Post!": o seu grupo de usuários administradores pode ter apenas permissão de visualização das configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_canada_post (OpenCart 3) ou extension/vfd_canada_post/shipping/vfd_canada_post (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da API do Canada Post pode ser substituído pela configuração vfd_cp_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 Canada Post. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Canada Post, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativo, as configurações, os serviços salvos dos pedidos e o log também são apagados. Se estiver desativado, as demais configurações são mantidas e usadas novamente ao reinstalar a extensão. 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, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Canada Post na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

Canada Post é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo Canada Post.