VibeFox Australia Post for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Chave PAC API da Australia Post (somente para tarifas em tempo real): as tarifas em tempo real usam a API Postage Assessment Calculator (PAC) da Australia Post. A chave é gratuita: cadastre-se para obter uma chave PAC API no Australia Post Developer Centre (developers.auspost.com.au). A página de configurações tem um link para a página de cadastro. Você também precisa do CEP australiano de 4 dígitos de onde envia. Se você usa 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 ú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_australia_post-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_australia_post.ocmod.zip. Instale apenas 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_australia_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 deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Australia 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 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. Escolha a Rate source (fonte das tarifas). Para preços fixos, adicione linhas em Country prices. Para tarifas em tempo real, informe a chave PAC API, o 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). Ative Enable Australia Post e clique em Save.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_australia_post.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 Australia Post, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe 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 seus campos são iguais nas duas versões.

Após a instalação, o método fica desativado até que você ative Enable Australia Post e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações da Australia Post 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 Australia Post > Edit. As seções são listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas da Australia Post em cache. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.

Alguns erros impedem o salvamento, e nesse caso nada é salvo: um Method title com mais de 64 caracteres, um Sort order que não é um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida. Outros problemas são mostrados como avisos acima do painel, e o restante das configurações é salvo. Um campo numérico com valor que não é número ou é negativo mantém o valor anterior, e o aviso indica o campo. Os campos numéricos aceitam ponto ou vírgula como separador decimal.

Se uma fonte de tarifas em tempo real for 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é a correção: o método fica oculto na finalização de compra, ou os preços fixos por país são usados no modo alternativo. A página também avisa se a sua loja não tiver uma classe de peso com a unidade kg ou uma classe de comprimento com a unidade cm. Nesse caso, pesos e dimensões dos produtos são convertidos conforme a unidade da respectiva classe (kg, g, lb, oz; cm, mm, m, in), e as demais unidades são lidas como kg e cm.

Geral

As configurações valem para todas as zonas geográficas. Você pode limitar o método a uma zona geográfica em Conditions, ou a uma lista de países em Availability without shipping zones.

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

Method title: o nome do método de frete exibido ao cliente no carrinho e na finalização de compra. Padrão: Australia Post. No máximo 64 caracteres: um título mais longo é recusado e nada é salvo. Se o campo estiver vazio, um aviso é mostrado e a Australia Post é usada.

Rate source: como o preço é calculado.

Os detalhes dos erros vão para o log, nunca para o cliente.

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

API Australia Post (tarifas em tempo real) (não necessária para preços fixos)

PAC API key: sua chave PAC API gratuita da Australia Post. Ela é enviada à 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 apagar 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 por 1,1 os preços nacionais da API. Os preços nacionais da Australia Post incluem 10% de GST. Ative quando o próprio OpenCart acrescenta imposto ao frete (uma Tax class está selecionada), para que o GST não seja cobrado duas vezes. O envio internacional é isento de GST e nunca é alterado.

AUD → (your currency) rate: o rótulo mostra a moeda padrão da sua loja. Os preços da Australia Post estão em AUD. Se a sua moeda padrão não for AUD, informe quantas unidades da sua moeda vale 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 sua moeda padrão for AUD, o campo indica que não é necessária conversão: deixe-o vazio.

Pacote para tarifas em tempo real

O carrinho é enviado como um único pacote. Pesos e dimensões dos produtos são convertidos das classes de peso e de comprimento do OpenCart 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 à 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 alternativa das tarifas em tempo real)

Country prices: uma lista de países e preços na moeda padrão da sua loja, sem impostos. Clique em Add row para adicionar uma linha e no botão × para remover uma. Escolha * All other countries para um preço usado em todos os países sem linha própria. Um país sem preço (e sem linha *) não recebe tarifa fixa, então o método fica oculto para ele. Linhas sem preço são descartadas ao salvar. A tabela fica vazia até que você adicione preços.

Fixed price per: Order (padrão) cobra o preço uma vez. Item (price × 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 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: 22. 0 significa sem limite; um campo vazio significa 22 kg. Pacotes da Australia Post: 22 kg nacionais, 20 kg internacionais. Se Min cart weight (kg) for maior que o máximo, o método nunca seria mostrado: um aviso aparece e os dois pesos mantêm os valores anteriores.

Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de frete (após o cupom, sem impostos, na moeda padrão da sua loja) atinge este valor. Deixe o campo vazio para sempre mostrá-lo.

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

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

Tax class: a classe de imposto do custo do frete, ou No tax (padrão). Os preços nacionais da Australia Post incluem GST: com uma classe de imposto, ative Remove GST.

Geo zone: ofereça a Australia Post somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usado com Ignore shipping zones.

Disponibilidade sem zonas de frete

Normalmente o método é oferecido na zona geográfica escolhida em Conditions (All zones significa em todos os lugares).

Ignore shipping zones: oferece o método para os países abaixo, seja qual for a zona geográfica.

Countries: os países de destino para esse modo. Digite para pesquisar e selecione vários. Deixe o campo vazio para permitir todos os países ativos da loja. Usado somente com Ignore shipping zones.

Avançado

Debug log: registra os cálculos de tarifas em storage/logs/vfd_ap.log.php. O arquivo não pode ser lido 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 log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_ap.old.log.php e um novo log é iniciado.

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

Remove data on uninstall: quando ativo, ao desinstalar a extensão são apagados as configurações, as tarifas em cache e o log. Quando desativado (padrão), eles são mantidos para uma nova instalação.

Importar / exportar

Exportar: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave de API não é exportada.

Importar: 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 salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de frete, ele pede à extensão o preço da Australia Post. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a Australia Post não é oferecida. Com Ignore shipping zones, a lista Countries decide. Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no valor do pedido. Em seguida, a extensão verifica o peso do carrinho e o Minimum order amount. O valor do pedido é o preço dos produtos que precisam de frete, 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 à Australia Post.

No modo de preços fixos, o preço é obtido da tabela. Nos modos de tarifas em tempo real, a extensão envia à Australia Post o peso do pacote e, para entregas dentro da Austrália, os CEPs de origem e de entrega e o tamanho do pacote; para envios 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 se o pacote ultrapassar os limites da Australia Post (22 kg ou 105 cm nacional, 20 kg internacional). O preço em AUD é convertido com a sua taxa, e o GST é removido dos preços nacionais se Remove GST estiver ativo. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela, e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.

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 que falhou fica em cache por 10 minutos, para que a finalização de compra não espere pela Australia Post a cada atualização. O tempo limite da API é de 10 segundos. Erros da API nunca são mostrados ao cliente: o método fica oculto, ou o preço fixo é usado no modo alternativo. O motivo é gravado no log.

A extensão apenas calcula tarifas. Ela não cria etiquetas de envio, envios ou manifestos eParcel ou MyPost Business, não rastreia pacotes e não permite que os clientes escolham armários de retirada ou agências dos Correios. Ela não acrescenta nada aos pedidos: o pedido mostra o nome do método e o custo do frete como qualquer outro método de frete do OpenCart. O carrinho é sempre tarifado como um único pacote. Cartas, envelopes e tarifas contratuais (eParcel) não estão incluídos.

No OpenCart 4, o cliente clica em Choose no bloco de método de frete da página de finalização de compra e escolhe a Australia Post na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

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 Australia Post é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox Australia Post > 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 deles estão a linha Product: opencart-shipping-australia-post e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão de modificação da 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 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja nas configurações do OpenCart. 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 Australia Post não é mostrada aos clientes na finalização de compra e nenhuma tarifa é 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 é preciso 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 Australia Post não aparece na finalização de compra: verifique se a licença está ativa e se Enable Australia Post está ativado. Confira Geo zone (ou Ignore shipping zones e Countries), os limites de peso do carrinho e Minimum order amount. No modo de preços fixos, verifique se o país ou * All other countries tem preço. Verifique se os produtos têm Requires Shipping definido como Yes.

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: chave de API ou CEP de origem ausentes, ainda sem CEP de entrega de 4 dígitos, pacote acima dos limites, sem taxa AUD, ou a mensagem de erro da Australia Post. Com Live rates, fixed price if the API gives no rate, os clientes continuam recebendo 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 da loja valem um AUD) no campo AUD → (your currency) rate. Os preços fixos estão sempre na moeda padrão da loja.

O GST é cobrado duas vezes no frete: os preços nacionais da Australia Post incluem 10% de GST. Se uma Tax class estiver selecionada, ative Remove GST, ou defina a Tax class como No tax.

O preço está alto ou baixo demais: verifique os pesos e as dimensões dos produtos, as classes de peso e de comprimento deles, e os valores padrão em Parcel for live rates. Com Item (price × quantity), os preços fixos são multiplicados pelo número de itens.

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

A página diz "Warning: You do not have permission to modify VibeFox Australia Post!": 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_australia_post (OpenCart 3) ou extension/vfd_australia_post/shipping/vfd_australia_post (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da PAC API pode ser substituído pela configuração vfd_ap_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 Australia Post. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Australia 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 da Australia Post e o log também são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas ao instalar a extensão novamente. Os pedidos existentes mantêm o método de frete e o custo.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Australia Post na lista de extensões instaladas e depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

Australia Post é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada à Australia Post nem endossada por ela.