VibeFox Ninja Van for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 5.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

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 em tempo real opcionais 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 WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_ninja_van para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Ninja Van, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite suas tarifas da Ninja Van na tabela de preços. Para a Indonésia, você pode ativar opcionalmente Live rates (veja Configuração).

6. Adicione VibeFox Ninja Van a uma zona de entrega (por exemplo, "Singapura") em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox Ninja Van. Elas valem para todas as zonas de entrega. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:

Title (zone): o nome que os clientes veem nesta zona. Deixe em branco para usar o Method title global.

Geral

Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.

Method title: o nome do método de entrega exibido no carrinho e na finalização de compra. Uma zona pode substituí-lo. Padrão: Ninja Van.

Preços (na moeda da sua loja)

Digite as tarifas da sua tabela da Ninja Van na moeda da sua loja. Se sua tabela estiver em SGD, MYR, IDR, PHP, THB ou VND, 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 X para remover uma. Escolha * All other countries para todos os países que não têm 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 igual a 0) usa o preço base. Preço base 0 significa entrega grátis para esse país. Tanto "9.99" quanto "9,99" são aceitos. Linhas sem preços são removidas ao salvar.

Price for countries not in the table: usado quando a tabela não tem linha para o país de destino (e não há linha *), ou a linha não tem preço para esse peso. Deixe em branco para ocultar o método nesse caso.

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 a oferece apenas para a Indonésia. Quando Live rates está ativado, as linhas de status nesta seção mostram a zona de origem, uma taxa de conversão ausente e a última resposta da API Tariff.

Live rates: obtém preços em tempo real da Ninja Van para entregas dentro da Indonésia. Padrão: desativado. 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, a tabela de preços é usada.

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) vinculada na página de configurações. Digite os dois, ou deixe ambos em branco para detectá-los a partir do endereço da loja em WooCommerce > Settings > General: Indonésia, província, cidade e, se a cidade tiver várias zonas, o distrito (Kecamatan) na linha do endereço. Um código em formato incorreto é apagado com um erro.

IDR conversion rate: a API Tariff retorna a taxa em rúpias indonésias (IDR). Se a moeda da sua loja for IDR, deixe em branco. Caso contrário, informe quanto vale 1 IDR na moeda da sua loja, por exemplo 0.000058. Sem esse valor, os preços em tempo real não são usados e a tabela de preços é aplicada.

Condições

Minimum weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.

Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite.

Minimum order amount: mostra o método somente quando o subtotal do carrinho (após descontos, antes dos impostos) atinge este valor. Deixe em branco para mostrá-lo sempre.

Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual a entrega pela Ninja Van é grátis. Deixe em branco se não houver entrega grátis.

Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de entrega do WooCommerce.

Tax status: Taxable adiciona o imposto do WooCommerce ao valor do frete, None não adiciona. Escolha None se os preços da tabela já incluírem impostos (GST, SST, IVA).

Disponibilidade sem zonas de entrega

Ignore shipping zones: oferece a Ninja Van para os países listados abaixo, mesmo que o método não tenha sido adicionado a nenhuma zona de entrega.

Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você entrega. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: registra os cálculos de tarifas em WooCommerce > Status > Logs (origem vfd_ninja_van). Nenhum endereço de cliente é registrado. Requisições com falha à API Tariff são registradas mesmo com esta opção desativada. Desative-a quando terminar.

Remove data on uninstall: quando ativado, excluir o plugin remove todas as configurações da Ninja Van e os métodos das zonas. Desativar o plugin nunca apaga nada.

Como funciona na finalização de compra

Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: país de entrega, peso do carrinho, valor mínimo do pedido e classes de entrega excluídas. Se a entrega grátis se aplicar, o cliente vê o método sem custo e nenhuma requisição é enviada à Ninja Van.

O preço vem da linha do país (ou da linha *): a coluna de peso, senão o preço base, senão Price for countries not in the table. Os pesos dos produtos são convertidos da unidade de peso da loja para quilogramas. Se não houver preço, o método fica oculto.

Com Live rates ativado, uma entrega dentro da Indonésia é cobrada primeiro pela Ninja Van. O plugin converte os endereços de origem e de destino em códigos de zona da Ninja Van: província, 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.

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 plugin 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, a tabela de preços é usada. Os erros vão para o log, nunca para o cliente.

O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin apenas calcula 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). Para isso, use o Ninja Van Dashboard. Não há seletor de pontos de retirada (Ninja Points): o método é 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 plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Ninja Van. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a na sua conta em vibefox.net.

Sem uma chave ativa, a Ninja Van não é exibida aos clientes na finalização de compra. Gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um aviso aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A Ninja Van não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ativado e o país é permitido). Confira os limites de peso, Minimum order amount e Excluded shipping classes, e se o país, a linha * ou Price for countries not in the table tem um preço.

O preço em tempo real não é usado para alguns endereços: o destino precisa ser associado a uma zona da Ninja Van: Indonésia, província, cidade ou regência e, para cidades com várias zonas, o distrito (Kecamatan) em uma linha do endereço. Caso contrário, a tabela de preços é usada. Ative Debug log para ver o motivo e confira as linhas de status em Tarifas em tempo real (API) — Indonésia.

Os preços em tempo real nem são solicitados: as linhas de status 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), ou falta a IDR conversion rate.

Limite de requisições atingido (HTTP 429): as requisições em tempo real são pausadas por uma hora e, enquanto isso, a tabela de preços é usada.

Em qual moeda estão os preços: a tabela está na moeda da sua loja. Os preços em tempo real estão em rúpias (IDR), convertidos com IDR conversion rate, a menos que a moeda da sua loja seja IDR.

Desenvolvedores: um site com campo próprio de distrito (Kecamatan) na finalização de compra pode fornecer os códigos de zona com o filtro vfd_njvn_tariff_zone.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações, os métodos de zona, o último status da API Tariff e os preços em tempo real em cache só são removidos se Remove data on uninstall estava ativado. Caso contrário, eles são mantidos para uma reinstalação futura. Os pedidos existentes mantêm suas linhas de frete.

A Ninja Van é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Ninja Van.