VibeFox NZ Post for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Acesso à API da NZ Post (somente para tarifas em tempo real): as tarifas em tempo real usam a ShippingOptions API da NZ Post. Solicite o acesso à API no Developer Resource Centre, no site da NZ Post. A NZ Post fornece um Client ID e um Client Secret, primeiro para o ambiente de testes (UAT) e depois para a produção, após a checklist de go-live. Para tarifas dentro da Nova Zelândia, você também precisa de uma conta comercial da NZ Post: o número da conta e o seu auth code (ou site code). Se você usar apenas preços fixos, não precisa de acesso à 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_nz_post-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_nz_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 painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_nz_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 instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox NZ 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. Informe sua chave de licença VibeFox no campo License key do bloco de licença, no topo da página Edit, e clique em Activate (veja Chave de licença).

5. Para as tarifas em tempo real, preencha a seção NZ Post API (live rates). Opcionalmente, informe preços fixos, que são usados sem tarifas em tempo real e como alternativa (veja Configuração). Ative Enable NZ Post e clique em Save.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_nz_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. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox NZ Post, 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 NZ Post e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações da NZ Post que você manteve serão usadas novamente.

Configuração

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

Nada é salvo e um erro é exibido quando Method title está vazio, tem mais de 64 caracteres ou contém < > ; = # { }, quando um campo numérico contém texto ou um número negativo, quando a taxa de NZD é 0, quando Min cart weight (kg) é maior que Max cart weight (kg), ou quando Sort order não é um número inteiro. Avisos aparecem acima das configurações quando as tarifas em tempo real não podem funcionar com os valores salvos: apenas um entre Client ID e Client Secret, nenhuma taxa de conversão para NZD ou dados incompletos para as tarifas nacionais. Um aviso também aparece se a loja não tiver uma classe de peso com a unidade kg nem uma classe de comprimento com a unidade cm: pesos e dimensões são então convertidos pelo nome da unidade de sua classe (kg, g, lb, oz; cm, mm, m, in), e as demais unidades são lidas como kg e cm.

Geral

As configurações se aplicam a todas as zonas geográficas. Você pode limitar o método a uma zona geográfica, ou a países, em Availability.

Enable NZ Post: ativa ou desativa o método na finalização de compra. Padrão: desativado.

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

Tax class: a classe de imposto do custo de envio, ou No tax (padrão; o custo de envio não é tributado). Se a loja adiciona GST ao envio, defina API prices abaixo como Excluding GST para que o GST não seja cobrado duas vezes.

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

API da NZ Post (tarifas em tempo real) (deixe o Client ID vazio para usar apenas preços fixos)

Environment: Production (api.nzpost.co.nz) (padrão) ou Testing / UAT (api.uat.nzpost.co.nz). Use o ambiente para o qual o seu Client ID foi emitido.

Client ID: o ID de cliente OAuth2 da sua aplicação da API da NZ Post. Limpá-lo também apaga o Client Secret salvo.

Client Secret: o segredo de cliente OAuth2. Ele é trocado por um token de acesso, que fica em cache até expirar. Depois de salvar, o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.

Account number: o número da sua conta comercial (de cobrança) na NZ Post. É obrigatório para as tarifas dentro da Nova Zelândia. Para as tarifas internacionais é opcional; com ele, a NZ Post retorna as suas tarifas contratuais. Limpá-lo também apaga o auth code salvo.

Auth code: o auth code da conta para as tarifas nacionais. Não é necessário se você informar um site code. Assim como o Client Secret, ele não é mostrado novamente depois de salvo.

Site code: a alternativa ao auth code: o seu site code de coleta da NZ Post.

Ship-from suburb: o bairro do endereço de onde as encomendas são enviadas, por exemplo Petone. Necessário para as tarifas nacionais.

Ship-from city: a cidade ou município de onde as encomendas são enviadas, por exemplo Lower Hutt. Necessária para as tarifas nacionais.

Ship-from postcode: o código postal neozelandês de 4 dígitos de onde as encomendas são enviadas, por exemplo 5012. Necessário para as tarifas nacionais.

Services: códigos de serviço opcionais da NZ Post, separados por vírgula, por exemplo CPOLP, ICOU. Somente esses serviços são precificados. Deixe vazio para usar o serviço mais barato que a NZ Post retorna para a encomenda.

API prices: Including GST (padrão) ou Excluding GST. As tarifas nacionais da NZ Post incluem os 15% de GST; o porte internacional tem alíquota zero. Escolha Excluding GST quando o método tiver uma classe de imposto (General), para que o GST não seja cobrado duas vezes.

Taxa NZD → (moeda da loja): os preços da NZ Post estão em NZD. Se a moeda padrão da sua loja não for o NZD, informe quantas unidades da sua moeda vale um NZD, por exemplo 0.55. Sem esse valor, as tarifas em tempo real não são usadas. A mesma taxa converte o valor do pedido enviado nas solicitações internacionais. A taxa deve ser maior que 0. Se a moeda da sua loja for o NZD, deixe o campo vazio.

Encomenda para as tarifas em tempo real

O carrinho é enviado à NZ Post como uma única encomenda. Pesos e dimensões dos produtos são convertidos das suas classes de peso e de comprimento para kg e cm (mm nas solicitações internacionais). A encomenda usa o maior comprimento e a maior largura dos produtos, e sua altura cresce até caber o volume de todos os itens. Os valores abaixo são usados para produtos sem peso ou dimensões.

Default product weight (kg): usado para cada produto sem peso. Padrão: 0.5.

Default parcel length (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 30.

Default parcel width (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 20.

Default parcel height (cm): usado quando nenhum produto do carrinho tem dimensões. Padrão: 10.

Preços fixos (usados quando as tarifas em tempo real não estão configuradas ou a NZ Post não retorna uma tarifa)

Os preços estão na moeda padrão da loja, sem impostos.

Country prices: uma linha por país de destino. Clique em Add country para adicionar uma linha e no botão × para removê-la. Escolha * Default para uma linha que cubra todos os outros países. Cada linha tem um preço Any weight e colunas de peso opcionais: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg e > 5 kg (peso do carrinho). Uma coluna de peso preenchida substitui Any weight; uma coluna vazia ou com 0 usa Any weight. Um preço Any weight de 0 significa frete grátis para esse país. São aceitos tanto "9.99" quanto "9,99". As linhas sem nenhum preço e os preços negativos são removidos ao salvar. Só uma linha por país é mantida.

Fallback cost: usado quando nem a API nem a tabela de países fornecem um preço. Deixe em branco para ocultar o método nesse caso.

Fixed price per: Order (padrão) cobra o preço uma única vez. Item (price × quantity) o multiplica pelo número de itens no carrinho. Isso se aplica apenas aos preços fixos e ao custo de contingência. As tarifas em tempo real são sempre calculadas para a encomenda inteira.

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: 25 (as encomendas courier da NZ Post vão até 25 kg); um campo vazio também significa 25. 0 significa sem limite. Com Ignore shipping zones ativado, um campo vazio significa sem limite para endereços fora da Geo zone.

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 em branco para exibi-lo sempre.

Free shipping from: o subtotal (após o cupom, antes dos impostos) a partir do qual a entrega pela NZ Post é grátis. Nenhuma solicitação é enviada à NZ Post nesse caso. Deixe em branco para nunca oferecer frete grátis.

Para essas condições, o peso do carrinho considera os produtos sem peso como 0.

Disponibilidade

Normalmente o método é oferecido na zona geográfica selecionada abaixo, ou em todas as regiões se nenhuma for selecionada.

Geo zone: ofereça a NZ Post 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.

Ignore shipping zones: ofereça também a NZ Post fora da zona geográfica, para os países abaixo. Quando ativado, somente esses países recebem o método, inclusive dentro da zona geográfica. Padrão: desativado.

Countries: os países de destino para esse modo. Deixe em branco para usar todos os países ativados na 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_nzpt_debug.log.php (no OpenCart 4, system/storage/logs/vfd_nzpt_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com o log de depuração desativado. Credenciais, tokens, o número da conta e os endereços dos clientes não são registrados. Desative o log quando terminar. Quando o arquivo atinge 5 MB, ele é movido para vfd_nzpt_debug.old.log.php e um novo log é iniciado.

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

Remove data on uninstall: quando ativado, ao desinstalar a extensão as configurações e o log são apagados. Quando desativado (padrão), são mantidos para uma reinstalação. As tarifas em cache são sempre apagadas. Os dados da NZ Post dos pedidos são sempre mantidos.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O Client Secret e o auth code não são exportados.

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. O Client Secret e o auth code salvos são mantidos enquanto o Client ID e o número da conta estiverem preenchidos.

Como funciona na finalização de compra

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da NZ Post. Se uma Geo zone estiver definida e o endereço estiver fora dela, a NZ Post só é oferecida quando Ignore shipping zones estiver ativado e o país for permitido. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no valor do pedido. Em seguida, a extensão verifica as condições: os países permitidos (com Ignore shipping zones), o peso do carrinho e o 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. Vale-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 à NZ Post. Caso contrário, ela procura um preço: primeiro a tarifa da NZ Post em tempo real, depois a tabela de países e depois o custo de contingência. Se não houver nenhum preço, o método é ocultado.

Com as tarifas em tempo real configuradas, a extensão obtém um token de acesso com o seu Client ID e o seu Client Secret e pede um preço à NZ Post. Para um endereço na Nova Zelândia, ela envia os dados da sua conta, o endereço de origem, o bairro, a cidade e o código postal do cliente, além do peso e das dimensões da encomenda. O OpenCart não tem campo de bairro: a extensão usa Address 2 quando ele contém o nome de um bairro (sem números); caso contrário, usa a cidade. Uma tarifa nacional só é solicitada depois que o cliente informa uma cidade e um código postal de 4 dígitos. Para outros países, ela envia o país de destino, o peso e as dimensões da encomenda e o valor do pedido em NZD.

É usado o serviço permitido mais barato que tenha preço, incluindo adicionais e taxas obrigatórias. O preço é convertido de NZD para a moeda padrão da loja, arredondado para as casas decimais dela e mostrado ao cliente em sua moeda com o imposto da Tax class selecionada. Cada resposta fica em cache por 1 hora. Uma solicitação com falha fica em cache por 10 minutos, para que a finalização de compra não espere a NZ Post a cada atualização. O tempo limite da API é de 10 segundos. O token de acesso é mantido até expirar, e um token recusado é renovado automaticamente.

Se a NZ Post não retornar uma tarifa (API não configurada, erro, endereço incompleto, serviço indisponível, sem taxa para NZD), o cliente não vê nenhum erro. É usado o preço da tabela de países e, depois, o custo de contingência. Se não houver preço fixo, o método é ocultado. O motivo é gravado no log.

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 uma opção da NZ Post na janela Shipping method options. As tarifas são as mesmas do OpenCart 3.

A extensão apenas calcula tarifas. Ela não cria etiquetas de envio, não gera manifestos, não agenda coletas, não rastreia encomendas, não valida endereços e não permite que o cliente escolha um ponto de retirada, uma caixa postal (PO Box) ou um armário de encomendas. O carrinho é precificado como uma única encomenda, e o cliente vê uma tarifa da NZ Post, não uma lista de serviços.

Pedidos

Quando um pedido com a NZ Post é feito, a extensão salva em que o preço do envio se baseou. Abra o pedido em Sales > Orders: a página do pedido mostra um painel NZ Post com NZ Post service (o serviço da NZ Post precificado em uma tarifa em tempo real, com o código dele) e Price source: Live rate (NZ Post ShippingOptions API), Fixed price ou Free shipping. O painel mostra os valores do momento do pedido, mesmo que tarifas ou configurações mudem depois, e também enquanto o método estiver desativado. O cliente não vê o nome do serviço.

No OpenCart 4, o painel NZ Post é exibido acima de History. 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 salvo e a origem do preço são atualizados junto. Se o cliente trocar esse pedido para outro método de envio, os dados da NZ Post do pedido são removidos.

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 NZ Post é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox NZ 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 aparecem a linha Product: opencart-shipping-nz-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 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 do domínio dela. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a NZ 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 é 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 NZ Post não aparece na finalização de compra: verifique se a licença está ativa e se Enable NZ Post está ativado. Confira Geo zone (ou Ignore shipping zones e Countries), os limites de peso e Minimum order amount. Se a NZ Post não retornar uma tarifa, o método só é mostrado com um preço de país ou um Fallback cost. Confirme que os produtos têm Requires Shipping definido como Yes.

As tarifas em tempo real não aparecem: veja os avisos no topo da página da extensão. Depois ative o Debug log, recarregue a finalização de compra e consulte o campo Log. Os erros da API sempre aparecem ali. O log mostra o motivo: Client ID ou Client Secret ausente, token recusado, dados da conta ou de origem faltando, ainda sem cidade ou código postal do cliente, sem taxa de NZD ou sem nenhum serviço com preço. Os preços fixos são usados enquanto você corrige o problema.

A solicitação do token falha: verifique o Client ID, o Client Secret e o Environment. Credenciais de UAT não funcionam em produção, e vice-versa.

As tarifas nacionais não aparecem, mas as internacionais funcionam: as tarifas dentro da Nova Zelândia exigem o Account number, o Auth code ou o Site code, e o endereço de origem completo com código postal de 4 dígitos. O cliente precisa informar uma cidade e um código postal de 4 dígitos.

Minha loja não usa NZD: informe a taxa de NZD (o campo NZD → (sua moeda) rate). Os preços fixos estão sempre na moeda padrão da loja.

O GST está sendo cobrado duas vezes no envio: as tarifas nacionais da NZ Post incluem os 15% de GST. Se o método tiver uma Tax class, defina API prices como Excluding GST.

As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página da extensão. Isso limpa as tarifas e os tokens da NZ Post em cache.

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

Para desenvolvedores: o bairro enviado para um endereço de entrega na Nova Zelândia pode ser alterado com o evento do OpenCart vfd_nz_post/delivery_suburb (gatilho catalog/vfd_nz_post/delivery_suburb). O endereço da API da NZ Post pode ser substituído pela configuração vfd_nzpt_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox NZ Post. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre restaura Enable NZ Post, Sort order, Tax class e Geo zone. As tarifas e os tokens em cache são sempre removidos, e o painel NZ Post deixa de aparecer na página do pedido. Se Remove data on uninstall estiver ativado, as configurações da NZ Post e o log de depuração também são apagados. Se estiver desativado, as demais configurações são mantidas e usadas novamente ao reinstalar a extensão. Os dados salvos da NZ Post nos pedidos nunca são apagados e reaparecem após uma reinstalaçã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, depois da desinstalação acesse Extensions > Installer e clique em Uninstall (o botão laranja −) ao lado de VibeFox NZ Post na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

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