VibeFox Australia Post 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 anteriores do PHP.
Chave PAC API do Australia Post (somente para tarifas em tempo real): as tarifas em tempo real usam a API Postage Assessment Calculator (PAC) do Australia Post. A chave é gratuita: cadastre-se para obter uma chave PAC API no Developer Centre do Australia Post (developers.auspost.com.au). A página do módulo tem um link para a página de cadastro. Você também precisa do CEP australiano de 4 dígitos de onde envia. Se usar apenas preços fixos por país, não precisa de chave de API.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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, mais tarde, encontre VibeFox Australia Post na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Escolha o Rate source. Para tarifas em tempo real, informe a chave PAC API, o seu CEP de origem e, se a moeda padrão da sua loja não for AUD, a taxa de conversão para AUD (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora Australia Post com o texto de prazo de entrega Australia 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 entrega, logotipo, limites de tamanho e a regra de imposto em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Australia Post > Configure. Elas valem para todas as zonas. No topo da página aparecem o nome e o ID da transportadora em Shipping > Carriers. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa o cache de tarifas do Australia Post.
Se uma fonte de tarifas em tempo real estiver escolhida, mas faltar a chave de API, o CEP de origem de 4 dígitos ou a taxa de conversão para AUD, um aviso é exibido após salvar. Ele também informa o que acontece até você corrigir: a transportadora fica oculta na finalização de compra ou, no modo de contingência, os preços fixos por país são usados.
Os campos numéricos aceitam ponto ou vírgula como separador decimal. Um valor que não seja numérico ou seja negativo não é salvo: um aviso indica o campo e o valor anterior é mantido. A página também avisa se a unidade de peso ou de dimensão da loja (International > Localization) não é uma que o módulo reconhece. Nesse caso, os pesos dos produtos são lidos em kg e as dimensões em cm.
Geral
Enable Australia Post: desativa a transportadora em todas as zonas de uma vez. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido ao cliente na finalização de compra. É também o nome da transportadora em Shipping > Carriers, e renomear a transportadora lá atualiza este campo. Padrão: Australia Post. No máximo 64 caracteres: um título mais longo é recusado e nada é salvo. Se o campo estiver vazio ou tiver caracteres que o PrestaShop não permite em um nome de transportadora, um aviso é exibido e o Australia Post é usado.
Tax status: como o imposto é aplicado ao custo do frete.
Rate source: como o preço é calculado.
Os detalhes dos erros vão para o registro, nunca para o cliente.
Australia Post API (live rates) (não necessária para preços fixos)
PAC API key: a sua chave gratuita da PAC API do Australia Post. Ela é enviada ao Australia Post no cabeçalho AUTH-KEY. Após salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.
Remove the saved API key: ative e salve para excluir a chave salva. As tarifas em tempo real deixam de funcionar.
Ship-from postcode: o CEP australiano de 4 dígitos de onde os pacotes são enviados, por exemplo 2000.
Domestic service: usado para entregas dentro da Austrália (até 22 kg, 105 cm por lado): Parcel Post (padrão) ou Express Post.
International service: usado para entregas fora da Austrália (até 20 kg): International Standard (padrão), International Express ou International Courier.
Remove GST: divide os preços nacionais da API por 1,1. Os preços nacionais do Australia Post incluem 10% de GST. Ative quando o PrestaShop adicionar o imposto ao frete por conta própria (Tax status = Taxable com uma regra de imposto na transportadora), para que a GST não seja cobrada duas vezes. A postagem internacional é isenta de GST e nunca é alterada.
AUD → (your currency) rate: o rótulo mostra a moeda padrão da sua loja. Os preços do Australia Post estão em AUD. Se a moeda padrão não for AUD, informe quantas unidades da sua moeda equivalem a um AUD, por exemplo 0.61. A taxa deve ser maior que 0. Sem ela, as tarifas em tempo real não são usadas. Se a moeda padrão for AUD, a página indica que não é necessária conversão: deixe o campo vazio. Tanto o ponto quanto a vírgula são aceitos como separador decimal.
Pacote para tarifas em tempo real
O carrinho é enviado como um único pacote. Os pesos e as dimensões dos produtos são convertidos das unidades da sua loja para kg e cm. Os valores abaixo são usados para produtos sem peso ou dimensões.
Default product weight (kg): usado para cada produto sem peso, na solicitação ao Australia Post e na verificação de Min cart weight (kg) / Max cart weight (kg). Padrão: 1.
Default parcel length (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 22.
Default parcel width (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 16.
Default parcel height (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 8.
Quando os produtos têm dimensões, o pacote assume o maior comprimento e a maior largura entre eles, e a altura aumenta até que o pacote comporte o volume de todos os itens.
Preços fixos (usados com preços fixos e como contingência das tarifas em tempo real)
Country prices: uma tabela de códigos de país de 2 letras (AU, NZ, US etc.) e preços na moeda padrão da sua loja, sem impostos. Clique em Add row para adicionar um país e no link × para remover um. Use * para todos os outros países. Um país sem preço (e sem linha *) não tem tarifa fixa, então a transportadora fica oculta para ele. Linhas com código de país inválido ou sem preço são descartadas ao salvar. A tabela fica vazia até você adicionar preços.
Fixed price per: Order cobra o preço uma única vez. Item (price × quantity) o multiplica pelo número de itens do 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 a transportadora se o peso do carrinho for inferior a este valor. 0 significa sem limite.
Max cart weight (kg): oculta a transportadora se o peso do carrinho for superior a este valor. Padrão: 22. 0 significa sem limite; um campo vazio significa 22 kg. Pacotes do Australia Post: 22 kg nacionais, 20 kg internacionais. Se Min cart weight (kg) for maior que o máximo, a transportadora nunca seria exibida: um aviso aparece e os dois pesos mantêm os valores anteriores.
Minimum order amount: exibe a transportadora somente quando o subtotal dos produtos (após descontos, sem impostos) atinge este valor, na moeda padrão da sua loja. Deixe o campo vazio para exibi-la sempre.
Free shipping: ativa o frete grátis a partir do valor indicado abaixo.
Free shipping from: o subtotal dos produtos (após descontos, sem impostos) a partir do qual o frete é grátis. Nesse caso nenhuma solicitação é feita à API. Usado somente quando Free shipping está ativo.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida nas zonas selecionadas para ela em Shipping > Carriers.
Ignore shipping zones: oferece a transportadora para os países indicados abaixo, independentemente da zona correspondente. Ao salvar, a transportadora fica vinculada a todas as zonas, e as zonas criadas depois são vinculadas automaticamente. Desativar a opção devolve à transportadora as zonas que ela tinha antes.
Countries: os países de destino para esse modo. Deixe o campo vazio para permitir todos os países ativos. Mantenha Ctrl (Cmd no Mac) pressionado e clique para selecionar vários. Usado somente com Ignore shipping zones.
Avançado
Debug log: registra os cálculos de tarifas em modules/vfd_australia_post/logs/vfd_ap.log.php. O arquivo não pode ser aberto pela web. Os erros da API são sempre registrados. A chave de API e os CEPs dos clientes não são registrados. Desative o registro quando terminar.
Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativo, desinstalar o módulo exclui as configurações, as tarifas em cache e o registro. A transportadora é sempre removida na desinstalação. Ao instalar novamente, ela é restaurada se os dados tiverem sido mantidos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço do Australia Post. Só produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro as condições: a lista Countries (com Ignore shipping zones), o peso do carrinho e o Minimum order amount. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada ao Australia Post.
No modo de preços fixos, o preço vem da tabela. Nos modos de tarifas em tempo real, o módulo envia ao Australia Post o peso do pacote e, para entregas dentro da Austrália, os CEPs de origem e de destino e o tamanho do pacote; para entregas internacionais, o país de destino. Uma tarifa nacional em tempo real só é solicitada quando o endereço de entrega tem um CEP de 4 dígitos. Nenhuma solicitação é enviada quando o pacote ultrapassa os limites do Australia Post (22 kg ou 105 cm nacional, 20 kg internacional). O preço em AUD é convertido com a sua taxa e, se Remove GST estiver ativo, a GST é retirada dos preços nacionais. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
Cada resposta bem-sucedida fica em cache por 1 hora, para que o mesmo carrinho não gere uma nova solicitação. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere pelo Australia Post a cada atualização. O tempo limite da API é de 10 segundos. Erros da API nunca são exibidos ao cliente: a transportadora fica oculta ou, no modo de contingência, o preço fixo é usado. O motivo é gravado no registro.
Se você editar a transportadora em Shipping > Carriers depois que ela 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 etiquetas de envio, envios ou manifestos eParcel ou MyPost Business, não rastreia pacotes nem permite que os clientes escolham armários de retirada ou agências dos correios. O carrinho é sempre calculado como um único pacote. Cartas, envelopes e tarifas de contrato (eParcel) não estão incluídos.
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 Australia Post é o primeiro bloco em Modules > Module Manager > VibeFox Australia 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 estão a linha Product: presta-shipping-australia-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 Configure para o 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 Australia Post não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A loja 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 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, depois uma vez por semana. Não é necessário 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
O Australia Post não aparece na finalização de compra: verifique se a licença está ativa e se Enable Australia Post está ativado (a transportadora está ativa em Shipping > Carriers). 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 está permitido em Countries). Confira os limites de peso do carrinho e o Minimum order amount. No modo de preços fixos, confira se o país ou * tem um preço. Produtos também podem ser limitados a determinadas transportadoras na página do produto.
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 do módulo. Ele mostra o motivo: falta a chave de API ou o CEP de origem, ainda não há um CEP de entrega de 4 dígitos, o pacote está acima dos limites, falta a taxa de conversão para AUD ou aparece a mensagem de erro do Australia Post. Com Live rates, fixed price if the API gives no rate, os clientes continuam vendo o preço fixo enquanto você corrige o problema.
Minha loja não está em AUD: informe a taxa de conversão (quantas unidades da moeda padrão equivalem a um AUD) no campo AUD → (your currency) rate. Os preços fixos estão sempre na moeda padrão.
A GST é cobrada duas vezes no frete: os preços nacionais do Australia Post incluem 10% de GST. Se Tax status for Taxable e a transportadora tiver uma regra de imposto, ative Remove GST ou defina Tax status como None.
O imposto não é adicionado ao frete: com Tax status = Taxable, o imposto vem da regra de imposto da transportadora. Selecione-a em Shipping > Carriers. A página do módulo mostra um aviso enquanto a transportadora não tiver regra de imposto.
O preço está alto ou baixo demais: verifique os pesos e as dimensões dos produtos e os valores padrão em Pacote para tarifas em tempo real. Com Item (price × quantity), os preços fixos são multiplicados pelo número de itens.
As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página do módulo. Isso limpa o cache de tarifas do Australia Post.
A página informa que a transportadora Australia Post foi excluída: a transportadora foi excluída em Shipping > Carriers. Clique em Save na página do módulo para recriá-la, ou redefina o módulo em Modules > Module Manager.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Australia Post e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. A transportadora é sempre removida (os pedidos mantêm o histórico), e o cache de tarifas é limpo. Se Remove data on uninstall estiver ativo, as configurações, a tabela de cache de tarifas e o registro também são excluídos. Se estiver desativado, as configurações são mantidas, e reinstalar o módulo restaura a transportadora com suas zonas, grupos e logotipo.
O Australia Post é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo Australia Post.