VibeFox NZ Post for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a instalar em versões anteriores do PHP.

Acesso à API do NZ Post (somente para tarifas em tempo real): as tarifas em tempo real usam a API ShippingOptions do NZ Post. Solicite o acesso à API no Developer Resource Centre, no site do NZ Post. O 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 dele. Para as tarifas dentro da Nova Zelândia, você também precisa de uma conta comercial do 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

1. No back office, vá em 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 o VibeFox NZ 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, preencha a seção NZ Post API (live rates). Opcionalmente, informe preços fixos, que são usados sem as tarifas em tempo real e como alternativa (veja Configuração). Clique em Save.

Na instalação, o módulo cria a transportadora NZ Post com o texto de prazo de entrega NZ 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 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 NZ Post > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as tarifas do NZ Post em cache e os tokens de acesso.

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 preenchido, nenhuma taxa de conversão NZD, ou dados incompletos para as tarifas nacionais. Um aviso também aparece se a unidade de peso ou de dimensão da loja não for reconhecida pelo módulo (nesse caso, os pesos são considerados em kg e as dimensões em cm). Configure as unidades em International > Localization (Local units). Os campos numéricos devem conter 0 ou um número positivo; caso contrário, a página exibe um erro e nada é salvo.

General

Enable NZ Post: ativa ou desativa a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.

Method title: o nome da transportadora exibido no carrinho e na finalização de compra. Padrão: NZ Post. Obrigatório, no máximo 64 caracteres.

Tax: a regra tributária da transportadora, ou No tax (o custo de envio não é tributado). Se a loja acrescenta GST sobre o frete, defina API prices mais abaixo como Excluding GST, para que o GST não seja cobrado duas vezes.

NZ Post API (live rates) (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 client ID OAuth2 da sua aplicação da API do NZ Post. Limpá-lo também apaga o Client Secret salvo.

Client Secret: o client secret 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 somente se quiser alterá-lo.

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

Auth code: o código de autorização da conta para as tarifas nacionais. Não é necessário se você informar um site code. Assim como o Client Secret, não é exibido novamente depois de salvo.

Site code: a alternativa ao auth code: o seu código de site de coleta do NZ Post.

Ship-from suburb: o bairro (suburb) do endereço de onde os pacotes são enviados, por exemplo Petone. Necessário para as tarifas nacionais.

Ship-from city: a cidade ou localidade de onde os pacotes são enviados, 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 os pacotes são enviados, por exemplo 5012. Necessário para as tarifas nacionais.

Services: códigos de serviço opcionais do NZ Post, separados por vírgula, por exemplo CPOLP, ICOU. Somente esses serviços recebem preço. Deixe vazio para usar o serviço mais barato retornado pelo NZ Post para o pacote.

API prices: Including GST (padrão) ou Excluding GST. Os preços nacionais do NZ Post incluem 15% de GST; a postagem internacional tem alíquota zero. Escolha Excluding GST quando a transportadora tiver uma regra tributária (Tax acima), para que o GST não seja cobrado duas vezes.

Taxa NZD → (moeda da loja): os preços do 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 valem um NZD, por exemplo 0.55. Sem essa taxa, 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.

Parcel for live rates

O carrinho é enviado ao NZ Post como um único pacote. Pesos e dimensões dos produtos são convertidos das unidades da sua loja para kg e cm. O pacote usa o maior comprimento e a maior largura entre os produtos, e a sua altura aumenta 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.

Fixed prices (usados quando as tarifas em tempo real não estão configuradas ou o NZ Post não retorna uma tarifa)

Os preços sã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 ícone de lixeira 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". Linhas sem nenhum preço e preços negativos são removidos ao salvar. É mantida apenas uma linha por país.

Fallback cost: usado quando nem a API nem a tabela de países fornecem um preço. Deixe vazio para ocultar a transportadora nesse caso.

Fixed price per: Order cobra o preço uma vez. Item (price × quantity) o multiplica pela quantidade de itens no carrinho. Isso se aplica somente aos preços fixos e ao custo de contingência. As tarifas em tempo real são sempre calculadas para o pacote inteiro.

Conditions

Min cart weight (kg): oculta a transportadora quando o carrinho pesa menos. 0 significa sem limite.

Max cart weight (kg): oculta a transportadora quando o carrinho pesa mais. Padrão: 25 (os pacotes courier do 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 fora das zonas próprias da transportadora. Se Min cart weight for maior que Max cart weight, a página exibe um erro e nada é salvo, porque a transportadora nunca seria exibida.

Minimum order amount: exibe a transportadora somente quando o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) atinge este valor. Deixe vazio para exibi-la sempre.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega pelo NZ Post é grátis. Nesse caso, nenhuma solicitação é enviada ao NZ Post. Deixe vazio para nunca oferecer frete grátis.

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

Availability without shipping zones

Normalmente a transportadora é exibida nas zonas às quais está atribuída em Shipping > Carriers.

Ignore shipping zones: oferece o NZ Post para os países indicados abaixo, independentemente da zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas (inclusive às zonas criadas depois). Desativar a opção remove novamente as zonas adicionadas.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países ativos da loja. Este campo é usado somente quando Ignore shipping zones está ativado.

Advanced

Debug log: grava os cálculos de tarifas em logs/vfd_nzpt_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros da API são sempre registrados, mesmo com o log de depuração desativado. Credenciais, tokens e endereços de clientes não são registrados. Desative o log quando terminar.

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

Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações, a transportadora, as tarifas em cache, os detalhes salvos dos pedidos e os logs. Quando desativado, tudo é mantido para uma nova instalação.

Como funciona na finalização de compra

Na etapa de entrega, o PrestaShop pede ao módulo o preço do NZ Post. Apenas produtos físicos contam: produtos virtuais não adicionam 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 ao NZ Post. Caso contrário, ele procura um preço: primeiro a tarifa do NZ Post em tempo real, depois a tabela de países e, por fim, o custo de contingência. Se não houver preço, a transportadora é ocultada.

Com as tarifas em tempo real configuradas, o módulo obtém um token de acesso com o seu Client ID e o seu Client Secret e pede um preço ao NZ Post. Para um endereço na Nova Zelândia, ele 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 do tamanho do pacote. O PrestaShop não tem campo de bairro: o módulo usa o Address line 2 quando ele contém o nome de um bairro (sem dígitos); 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, ele envia o país de destino, o peso e o tamanho do pacote e o valor do pedido em NZD.

É usado o serviço permitido mais barato com preço, incluindo sobretaxas e adicionais obrigatórios. O preço é convertido de NZD para a moeda padrão da loja e depois exibido na moeda do carrinho do cliente. 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 pelo NZ Post a cada atualização. O tempo limite da API é de 10 segundos. Um token de acesso expirado é renovado automaticamente.

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

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 as tarifas. Ele não gera etiquetas de envio, não agenda coletas, não gera manifestos, não rastreia pacotes, não valida endereços e não permite que os clientes escolham um ponto de retirada, uma caixa postal (PO Box) ou um armário de encomendas (parcel locker). O carrinho é precificado como um único pacote, e o cliente vê uma única tarifa do NZ Post, não uma lista de serviços.

Pedidos

Quando um pedido com a transportadora NZ Post é feito, o módulo salva os dados nos quais o preço de entrega se baseou. A página do pedido no back office mostra um bloco NZ Post com NZ Post service (o serviço do NZ Post com preço de uma tarifa em tempo real) e Price source: Live rate (NZ Post ShippingOptions API), Fixed price ou Free shipping. O bloco mostra os valores do momento do pedido, mesmo que as tarifas ou as configurações mudem depois.

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 NZ Post é o primeiro bloco em Modules > Module Manager > VibeFox NZ Post > Configure, acima das configurações. Digite 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 digitar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-shipping-nz-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 NZ Post não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. O front office do 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. 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 é necessário 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

O NZ Post não aparece na finalização de compra: verifique se a licença está ativa e se Enable NZ Post está ativado. 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. Se o NZ Post não retornar uma tarifa, a transportadora só é exibida com um preço por país ou um Fallback cost. Produtos também podem estar limitados a certas transportadoras na página do produto.

As tarifas em tempo real não aparecem: veja os avisos no topo da página do módulo. 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 rejeitado, dados da conta ou do endereço de origem ausentes, cidade ou código postal do cliente ainda não informados, nenhuma taxa NZD ou nenhum serviço com preço. Enquanto você corrige o problema, os preços fixos são usados.

A solicitação de 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 estão ausentes, 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. Desenvolvedores podem alterar o bairro enviado para o endereço de entrega com o hook actionVfdNzptDeliverySuburb.

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

O GST está sendo cobrado duas vezes no frete: os preços nacionais do NZ Post incluem 15% de GST. Se a transportadora tiver uma regra tributária em Tax, defina API prices como Excluding GST.

As tarifas parecem desatualizadas depois de uma mudança: clique em Save na página do módulo. Isso limpa as tarifas do NZ Post e os tokens em cache.

A página diz que a transportadora NZ Post não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox NZ Post e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas e os tokens em cache são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações, os detalhes salvos dos pedidos e o log são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Reinstalar o módulo, ou um Reset, devolve à transportadora salva o status que ela tinha antes (ativada ou desativada).

NZ Post é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo NZ Post.