VibeFox Ninja Van 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.
Tabela de tarifas da Ninja Van: os preços da sua conta de remetente da Ninja Van ou fornecidos pela equipe comercial da Ninja Van, digitados na tabela de preços. Não são necessárias chaves de API. Os preços opcionais em tempo real dentro da Indonésia usam a API Ninja Van Tariff, que é pública e não exige autenticação.
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 Ninja Van na lista de módulos e clique em Configure.
3. Digite 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. Digite seus preços da Ninja Van na tabela de preços. Para a Indonésia, opcionalmente ative Live rates (veja Configuração). Clique em Save.
Na instalação, o módulo cria a transportadora Ninja Van com o texto de prazo de entrega Courier delivery. A transportadora fica ativa, atribuída a todas as zonas e a todos os grupos de clientes, e sem regra de imposto. 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 Ninja Van > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem seu próprio botão Save, que salva a página inteira. Nada é salvo e um erro é exibido quando um campo numérico contém texto ou um número negativo, IDR conversion rate é 0, Minimum weight (kg) é maior que Maximum weight (kg) ou Method title tem mais de 64 caracteres. Se a unidade de peso da sua loja não for uma que o módulo conhece, um aviso após salvar informa que os pesos dos produtos são considerados em quilogramas.
Geral
Enable Ninja Van: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido ao cliente no carrinho e na finalização de compra. Padrão: Ninja Van. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax (padrão). Escolha No tax se os preços da tabela já incluem impostos (GST, SST, VAT).
Preços (na moeda padrão da sua loja, sem impostos)
Digite os preços da sua tabela de tarifas da Ninja Van na moeda padrão da sua loja. Se a sua tabela estiver em SGD, MYR, IDR ou outra moeda, converta-a primeiro. Esta tabela é usada para todos os destinos fora da Indonésia e sempre que um preço em tempo real não estiver disponível.
Price table: uma linha por país de destino. Clique em Add country para adicionar uma linha e no ícone de lixeira para removê-la. Escolha * All other countries para todos os países sem linha própria. Cada linha tem um Base price e colunas de peso: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 5 kg. Uma coluna de peso vazia (ou com 0) usa o preço base. Preço base 0 significa frete grátis para esse país. Tanto «9.99» quanto «9,99» são aceitos. Linhas sem preços são descartadas ao salvar, e só a primeira linha de cada país é mantida.
Price for countries not in the table: usado quando a tabela não tem linha para o país de destino (nem linha *), ou a linha não tem preço para esse peso. Deixe vazio para ocultar a transportadora nesse caso. 0 significa frete grátis.
Price applies: a forma como os preços são calculados. Isso também vale para os preços em tempo real.
Tarifas em tempo real (API) — Indonésia
A API Ninja Van Tariff retorna a taxa padrão de entrega, sem sobretaxas nem descontos, para encomendas enviadas dentro da Indonésia. A Ninja Van oferece esse recurso somente para a Indonésia. Quando Live rates está ativo, as linhas de status abaixo do título da seção mostram a zona de origem, a falta de uma taxa de conversão e a última resposta da API Tariff (ambiente, horário e resultado).
Live rates: obtém preços em tempo real da Ninja Van para entregas dentro da Indonésia. Padrão: desligado. Sem essa opção, nada é enviado à Ninja Van durante a finalização de compra.
Environment: Production (api.ninjavan.co) (padrão) ou Sandbox — testing only (api-sandbox.ninjavan.co).
Service level: o serviço para o qual o preço é solicitado: Standard (padrão), Express, Same day ou Next day. Se a Ninja Van não tiver preço para a rota e o serviço, é usada a tabela de preços.
Ship-from zone code L1 e Ship-from zone code L2: os códigos de nível L1 e L2 do distrito de onde você envia, por exemplo ID_A00007_01 e ID_B00069_01, da tabela de códigos de zona da Ninja Van (CSV), cujo endereço aparece abaixo do campo. Digite os dois ou deixe ambos vazios para detectá-los a partir do endereço da loja em Shop Parameters > Contact > Stores: Indonésia, estado (state), cidade e, se a cidade tiver várias zonas, o distrito (Kecamatan) na linha do endereço. Um código em formato errado é apagado com um aviso. Se apenas um código for digitado, um aviso pede que você digite os dois, e uma linha de status mostra que os preços em tempo real não são solicitados.
IDR conversion rate: a API Tariff retorna a taxa em rúpias indonésias (IDR). Se a moeda padrão da sua loja for IDR, deixe vazio. Caso contrário, informe quanto vale 1 IDR na moeda da sua loja, por exemplo 0.000058. Deve ser maior que 0. Sem ele, os preços em tempo real não são usados e vale a tabela.
Condições
Minimum weight (kg): oculta a transportadora quando o carrinho pesa menos. Os pesos dos produtos são convertidos da unidade de peso da sua loja para quilogramas. 0 significa sem limite.
Maximum weight (kg): oculta a transportadora quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite. Não pode ser menor que Minimum weight (kg).
Minimum order amount: mostra a transportadora somente quando o subtotal do carrinho (produtos que precisam de entrega, após descontos, antes de impostos) atinge este valor. Deixe vazio para sempre mostrar.
Free shipping from: o subtotal do carrinho (produtos que precisam de entrega, após descontos, antes de impostos) a partir do qual a entrega pela Ninja Van é grátis. Deixe vazio para não ter entrega grátis.
Disponibilidade sem zonas de entrega
Ignore shipping zones: oferece a Ninja Van para os países abaixo mesmo que a transportadora não esteja vinculada à zona deles. Quando ativo, a transportadora fica vinculada a todas as zonas ativas, inclusive às que você criar depois. Quando você desliga, a transportadora volta às zonas que tinha antes.
Countries: os países de destino para esse modo. Deixe vazio para usar todos os países para os quais você envia. Este campo só é usado quando Ignore shipping zones está ativo.
Avançado
Debug log: registra os cálculos de tarifas em logs/vfd_njvn_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Nenhum endereço de cliente é registrado. Requisições à API Tariff com falha são registradas mesmo quando esta opção está desligada. Desligue quando terminar.
Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativo, ao desinstalar o módulo são apagados as configurações do módulo, a transportadora, os preços em cache e o log. Quando desligado, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de entrega, o PrestaShop pede ao módulo o preço da Ninja Van. 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: a lista de países de Ignore shipping zones (se ativo), o peso do carrinho e o valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Ninja Van.
O preço vem da linha do país (ou da linha *): a coluna de peso; se não houver, o preço base; se também não houver, Price for countries not in the table. Se não houver preço, a transportadora fica oculta para aquele carrinho. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
Com Live rates ativo, uma entrega dentro da Indonésia é cobrada primeiro pela Ninja Van. O módulo converte os endereços de origem e de destino em códigos de zona da Ninja Van: estado (state), cidade ou regência e, para cidades com várias zonas, o distrito (Kecamatan) escrito em uma linha do endereço. Ele envia os códigos, o peso e o nível de serviço, e converte a taxa de IDR para a moeda da sua loja. Com Per item, é enviada uma requisição por peso de item distinto, até 5 por carrinho. Com mais pesos diferentes, é usada a tabela de preços.
A API Tariff permite 20 requisições por minuto, então as respostas ficam em cache por 6 horas, as falhas por 5 minutos e «sem preço para esta rota» por 1 hora. O módulo nunca envia mais de 18 requisições por minuto e, após uma resposta HTTP 429, pausa por uma hora. O tempo limite da API é de 12 segundos. Se a Ninja Van não responder, responder com erro, não tiver preço para a rota ou o endereço não puder ser associado, é usado o preço da tabela. Os erros vão para o log, nunca para o cliente.
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 segue a nova versão automaticamente.
O módulo calcula apenas os preços. Ele não cria pedidos na Ninja Van, não imprime conhecimentos de transporte aéreo (AWB), não agenda coletas, não rastreia encomendas e não trabalha com pagamento na entrega (COD). Use o Ninja Van Dashboard para isso. Não há seletor de pontos de retirada (Ninja Points): a transportadora é de entrega porta a porta. Os preços em tempo real não estão disponíveis fora da Indonésia.
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 Ninja Van é o primeiro bloco em Modules > Module Manager > VibeFox Ninja Van > 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-ninja-van 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 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 Ninja Van não é exibida aos clientes na finalização de compra e nenhuma taxa é 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
A Ninja Van não aparece na finalização de compra: verifique se a licença está ativa e se Enable Ninja Van está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou ative Ignore shipping zones e confira Countries). Confira os limites de peso e Minimum order amount, e se o país, a linha * ou Price for countries not in the table têm um preço. Os produtos também podem estar limitados a certas transportadoras na página do produto.
O preço em tempo real não é usado para alguns endereços: o destino precisa corresponder a uma zona da Ninja Van: Indonésia, estado (state), cidade ou regência e, para cidades com várias zonas, o distrito (Kecamatan) em uma linha do endereço. Caso contrário, é usado o preço da tabela. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo.
Os preços em tempo real não são solicitados de jeito nenhum: as linhas de status abaixo de Tarifas em tempo real (API) — Indonésia mostram o motivo: o endereço da loja não está na Indonésia ou a zona de origem não pôde ser detectada (informe os dois códigos de zona), só um dos dois códigos foi informado, os códigos informados não formam um par na tabela de códigos de zona, ou falta o IDR conversion rate.
Limite de requisições atingido (HTTP 429): as requisições em tempo real ficam pausadas por uma hora, e a tabela de preços é usada nesse período.
Em qual moeda estão os preços: a tabela e as condições estão na moeda padrão da sua loja. Os preços em tempo real estão em rúpias (IDR), convertidos com o IDR conversion rate, a menos que a moeda da sua loja seja IDR.
A página informa que a transportadora Ninja Van não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desenvolvedores: uma loja com um campo próprio de distrito (Kecamatan) pode fornecer os códigos de zona pelo hook actionVfdNjvnTariffZone.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Ninja Van e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. Os preços em cache são sempre removidos. Se Remove data on uninstall estiver ativo, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações, o último status da API Tariff e o log são removidos. Se estiver desligado, a transportadora apenas é desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, a transportadora salva recebe de volta o status que tinha antes da desinstalação.
A Ninja Van é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Ninja Van.