VibeFox Canada Post for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Canada Post Developer Program (somente para tarifas em tempo real): as tarifas em tempo real usam a Rating API da Canada Post. Inscreva-se no Canada Post Developer Program no site da 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 a Canada Post fornece 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 único 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 depois VibeFox Canada Post na lista de módulos e clique em Configure.
3. Insira a 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 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 o CAD, informe a taxa em CAD. Preencha Country prices se quiser preços fixos ou uma alternativa (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora Canada Post com o texto de prazo de trânsito Canada Post parcel delivery. A transportadora é atribuída a todas as zonas e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de trânsito, 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 Canada Post > Configure. Cada seção tem o próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas da Canada Post em cache. Para salvar, é preciso ter a permissão de configuração do módulo.
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 de 0, Min cart weight (kg) maior que Max cart weight (kg), ou um Method title com mais de 64 caracteres. Se a unidade de peso ou de dimensão da sua loja for uma que o módulo não conhece, a página avisa que os pesos são lidos em kg (as dimensões, em cm). Defina kg, g, lb ou oz (cm, mm, m ou in) em International > Localization, seção Local units.
Depois de salvar, a página mostra um aviso quando as configurações não podem funcionar como previsto: apenas um dos campos de nome de usuário e 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 em uma loja com outra moeda, ou não há nem credenciais de API nem preços fixos. O aviso também informa o que acontece enquanto isso: são usados os preços fixos por país, ou a transportadora fica oculta no checkout quando a tabela Country prices está vazia.
Geral
Enable Canada Post: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido ao cliente na finalização de compra. Padrão: Canada Post, também quando o campo é deixado vazio. Até 64 caracteres, sem os caracteres que o PrestaShop não permite em nomes de transportadoras.
Tax: a regra de imposto que o PrestaShop adiciona ao custo do envio, ou No tax (não tributável).
API da Canada Post (tarifas em tempo real)
Com o nome de usuário e a senha da API preenchidos, o preço vem da Rating API da Canada Post. Se a API não retornar uma tarifa (API fora do ar, código postal incorreto, serviço indisponível), é usado o preço fixo de Country prices, ou a transportadora fica oculta se não houver um. 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 de erro 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 ativa.
API password: a parte da chave de API depois dos dois-pontos. Depois de salvar, o campo fica vazio e exibe A password is saved. Leave empty to keep it; clear the username and save to remove both. Digite um novo valor somente se quiser alterá-lo. A senha é salva exatamente como digitada e nunca é gravada no log.
Customer number: com um número de cliente, a 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 da Canada Post, para testes com a chave de API de desenvolvimento. Os preços são dados de teste. Desative em uma loja ativa.
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: Cheapest available, Regular Parcel (DOM.RP, padrão), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) ou Priority (DOM.PC).
Service to the USA: Cheapest available (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: Cheapest available (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, é usado o mais barato disponível.
Use Canada Post prices without GST/HST/PST: para endereços canadenses, o preço da Canada Post inclui esses impostos. Ative quando o próprio PrestaShop adicionar imposto ao envio (Tax 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 da Canada Post estão em CAD. Se a sua moeda padrão não for o 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 sua moeda padrão for o CAD, deixe o campo vazio. A taxa deve ser maior que 0. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Default product weight (kg): enviado à Canada Post para cada produto sem peso. Padrão: 0.5. Os pesos dos produtos (na unidade de peso da sua loja) e as dimensões são convertidos, e o carrinho é calculado como um único pacote.
Preços fixos (usados sem credenciais de API e como alternativa quando a API não retorna uma 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 sua loja, 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 zero usa o preço Base. Clique em Add country para adicionar uma linha e no ícone de X para remover uma. A linha * Default (all other countries) define os preços de todos os países que não têm linha própria. Um país sem linha (e sem *) não recebe preço fixo. Um preço base de 0 significa frete grátis para esse país. Uma linha sem nenhum preço não é salva.
Fixed price per: Order cobra o preço uma única vez. Item (price x quantity) o multiplica pelo número de itens no carrinho. Isso vale apenas para preços fixos. As tarifas em tempo real são sempre calculadas para o pacote inteiro.
Condições
Min cart weight (kg): oculta a transportadora abaixo deste peso de carrinho. 0 significa sem limite.
Max cart weight (kg): oculta a transportadora acima deste peso de carrinho. Padrão: 25, também quando o campo está vazio. 0 significa sem limite. Os pacotes da Canada Post podem pesar até 30 kg. Não pode ser menor que Min cart weight (kg).
Minimum order amount: exibe a transportadora somente quando o subtotal do carrinho (produtos após descontos, sem impostos) atinge este valor. Deixe vazio para exibi-la sempre.
Free shipping: ativa a entrega grátis a partir do valor abaixo.
Free shipping from: o subtotal do carrinho a partir do qual o frete é grátis. Nesse caso, nenhuma solicitação é feita à API. Usado somente quando Free shipping está ativado.
Disponibilidade sem zonas de envio
Normalmente, a transportadora é exibida nas zonas às quais está atribuída em Shipping > Carriers.
Ignore shipping zones: oferece a transportadora para os países abaixo, independentemente da zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas, e também às zonas que você criar depois. Quando você desativa a opção e salva, as zonas adicionadas pelo módulo são removidas novamente, e a transportadora mantém as próprias zonas.
Countries: os países de destino para este modo. Mantenha Ctrl (Cmd) pressionado para selecionar vários. Deixe vazio para permitir todos os países ativos. Este campo é usado somente quando Ignore shipping zones está ativado.
Avançado
Debug log: registra os cálculos de tarifas em var/logs/vfd_canada_post.log.php. O arquivo não pode ser aberto pela web e é rotacionado ao atingir 5 MB. 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.
Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações, os serviços salvos dos pedidos, as tarifas em cache e o log. A transportadora é sempre removida do checkout na desinstalação. Os pedidos nunca são alterados.
Log: o painel abaixo das configurações mostra o nome do arquivo e as 50 entradas mais recentes. Clique em Clear log para apagá-lo.
Como funciona no checkout
Na etapa de envio, o PrestaShop pede ao módulo o preço da Canada Post. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no valor do pedido. 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 à Canada Post.
Com credenciais de API, o módulo envia à 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 EUA, o código ZIP; para os demais países, apenas o país. Uma tarifa em tempo real é solicitada somente quando um endereço canadense ou americano tem um código postal ou ZIP válido. A Canada Post retorna todos os serviços para o pacote. O módulo escolhe o serviço selecionado para o grupo de destino ou o mais barato, remove os impostos sobre vendas canadenses (GST/HST/PST) se Use Canada Post prices without GST/HST/PST estiver ativado, e converte o preço CAD com a sua taxa. O preço é calculado na moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente.
Cada resposta fica em cache por 1 hora, para que o mesmo carrinho e o mesmo endereço não gerem uma nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que uma queda da Canada Post não atrase cada atualização do checkout. 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 uma tarifa, é usado o preço fixo, ou a transportadora fica oculta quando não há preço fixo. O cliente nunca vê os detalhes de erro da API; eles vão para o log.
Se você editar a transportadora em Shipping > Carriers, 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, 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 dos correios ou um ponto de retirada. Ele exibe uma única tarifa da Canada Post, sem datas de entrega, opções de seguro ou de assinatura. O carrinho é sempre calculado como um único pacote, e as taxas de câmbio não são atualizadas automaticamente.
Pedidos
Quando um pedido é feito com a transportadora Canada Post, o módulo salva como o preço foi calculado. Na página do pedido no back office (Orders > 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.
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 Canada Post é o primeiro bloco em Modules > Module Manager > VibeFox Canada Post > 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 deles ficam a linha Product: presta-shipping-canada-post e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão de configuração 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 muda, ou depois que você libera 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, inclusive em uma configuração multistore. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a transportadora Canada Post não é exibida aos clientes na finalização de compra, e nenhuma tarifa é 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ê: é possível configurar o módulo antes de comprar uma chave, mas não 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 e, depois, uma vez por semana. Não é preciso 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 Canada Post não aparece no checkout: verifique se a licença está ativa e se Enable Canada Post 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á ativado e o país é permitido). Confira os limites de peso e o Minimum order amount. Deve haver uma tarifa: com credenciais de API, o endereço precisa de um código postal válido (Canadá) ou ZIP (EUA); caso contrário, deve existir um preço fixo para o país ou para *. Além disso, os produtos podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: ative o Debug log, recarregue o checkout e veja o painel Log na página do módulo. 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 da Canada Post. Enquanto isso, os clientes recebem o preço fixo, se houver.
A tarifa é diferente da exibida no site da 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. Para endereços canadenses, o preço da Canada Post inclui GST/HST/PST. Os preços são convertidos com a sua taxa CAD.
O imposto sobre o frete é cobrado duas vezes: ative Use Canada Post prices without GST/HST/PST, ou defina Tax como No tax.
Testar preços em uma loja ativa: desative Sandbox e use a chave de API de produção.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as tarifas da Canada Post em cache.
A página diz que a transportadora Canada Post está ausente: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Você não tem permissão para configurar este módulo: seu perfil de funcionário pode abrir a página do módulo, mas não salvá-la. Peça a um administrador que conceda ao seu perfil a permissão de configuração do módulo.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Canada Post e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. A transportadora é sempre removida do checkout (os pedidos mantêm a transportadora e o histórico). Se Remove data on uninstall estiver ativado, as configurações, os serviços salvos dos pedidos, as tarifas em cache e o log são apagados. Se estiver desativado, apenas as tarifas em cache são removidas e todas as configurações são mantidas. Instalar o módulo novamente (ou usar Reset) restaura a transportadora anterior com o status anterior: uma transportadora que você tinha desativado continua desativada.
A Canada Post é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Canada Post.