VibeFox Ninja Van 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.

Tabela de tarifas da Ninja Van: os preços da sua conta de remetente da Ninja Van ou os fornecidos pela equipe comercial da Ninja Van, informados na tabela de preços. Não são necessárias chaves de API. As tarifas opcionais em tempo real dentro da Indonésia usam a Tariff API da Ninja Van, que é pública e não exige autenticação.

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_ninja_van-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_ninja_van.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_ninja_van-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 Ninja Van 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 em License key, no bloco de licença no topo da página Edit, e clique em Activate (veja Chave de licença).

5. Informe seus preços da Ninja Van na tabela de preços. Para a Indonésia, se desejar, ative Live rates (veja Configuração). Ative Enable Ninja Van e clique em Save.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_ninja_van.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 Ninja Van, 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 Ninja Van e salve. Se você instalar a extensão novamente depois de uma desinstalação, as configurações da Ninja Van 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 Ninja Van > Edit. As seções são listadas à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. 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 IDR conversion rate é 0, quando Minimum weight (kg) é maior que Maximum weight (kg), ou quando Sort order não é um número inteiro. Se a loja não tiver uma classe de peso com a unidade kg e a unidade da classe de peso padrão não for reconhecida pela extensão, um aviso informa que os pesos dos produtos são considerados em quilogramas: adicione uma classe de peso kg em System > Localisation > Weight Classes. Apenas usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.

Geral

As configurações se aplicam a todas as zonas geográficas. Você pode limitar o método a uma zona geográfica em Conditions, ou usar Ignore shipping zones.

Enable Ninja Van: mostra ou oculta a Ninja Van 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: Ninja Van. Obrigatório, no máximo 64 caracteres.

Tax class: a classe de imposto do custo de envio, ou No tax (padrão). Escolha No tax se os preços da tabela já incluem impostos (GST, SST, VAT).

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

Preços (na moeda padrão da sua loja, sem impostos)

Informe 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 antes. Esta tabela é usada para todos os destinos fora da Indonésia e sempre que uma tarifa 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 botão × para removê-la. Escolha * All other countries para todos os países que não têm linha própria. Cada linha tem um preço Base 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. Um preço base de 0 significa frete grátis para esse país. São aceitos tanto "9.99" quanto "9,99". As linhas sem preços são removidas 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 (e não há linha *), ou quando a linha não tem preço para esse peso. Deixe em branco para ocultar o método nesse caso. 0 significa frete grátis.

Price applies: a forma como os preços são calculados. Isso também vale para as tarifas em tempo real.

Tarifas em tempo real (API) — Indonésia

A Tariff API da Ninja Van retorna a taxa de entrega padrão, sem sobretaxas e descontos, para pacotes enviados dentro da Indonésia. A Ninja Van oferece apenas para a Indonésia. Quando Live rates está ativado, as linhas de status abaixo do título da seção mostram a zona de origem, uma taxa de conversão ausente e a última resposta da Tariff API (ambiente, hora e resultado). Elas são atualizadas após cada salvamento.

Live rates: obtenha tarifas 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, do mapeamento de códigos de zona da Ninja Van (CSV), cujo endereço aparece abaixo do campo. Informe os dois: o endereço da loja no OpenCart não tem cidade nem rua separadas, então a zona de origem não pode ser detectada a partir dele. Os códigos são convertidos para letras maiúsculas. Um código em formato errado é apagado com um aviso. Se apenas um código for informado, um aviso pede que você informe os dois, e uma linha de status indica que as tarifas em tempo real não estão sendo solicitadas. Uma linha de status também avisa quando os dois códigos não formam um par no mapeamento de códigos de zona.

IDR conversion rate: a Tariff API retorna a tarifa em rupias indonésias (IDR). Se a moeda padrão da sua loja for IDR, deixe em branco. Caso contrário, informe quanto 1 IDR vale na moeda da sua loja, por exemplo 0.000058. Deve ser maior que 0. Sem ela, as tarifas em tempo real não são usadas e a tabela de preços é utilizada.

Condições

Minimum weight (kg): oculta o método quando o carrinho pesa menos. Os pesos dos produtos são convertidos da classe de peso do OpenCart para quilogramas. 0 significa sem limite (padrão).

Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 ou um campo vazio significam sem limite. Não pode ser menor que Minimum weight (kg).

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 dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual o envio pela Ninja Van é grátis. Deixe em branco se não houver frete grátis.

Geo zone: ofereça a Ninja Van somente para endereços dentro desta zona geográfica. All zones (padrão) significa sem limite. Não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Disponibilidade sem zonas de envio

Ignore shipping zones: ofereça a Ninja Van para os países abaixo, independentemente da Geo zone. Quando desativado (padrão), a zona geográfica decide e a lista de países não é usada.

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

Avançado

Debug log: grava os cálculos de tarifas em storage/logs/vfd_njvn_debug.log.php (no OpenCart 4, system/storage/logs/vfd_njvn_debug.log.php). O arquivo não pode ser lido pela web. Nenhum endereço de cliente ou código de zona é registrado. As requisições com falha à Tariff API são registradas mesmo quando esta opção está desativada. Desative-a ao terminar. Quando o arquivo atinge 5 MB, ele é movido para vfd_njvn_debug.old.log.php e um novo log é iniciado.

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 ativado, ao desinstalar a extensão as configurações da Ninja Van 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.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A extensão não tem chaves secretas, então tudo é exportado.

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.

Como funciona na finalização de compra

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da Ninja Van. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a Ninja Van não é oferecida. 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: a lista de países de Ignore shipping zones (se ativado), 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 requisição é enviada à Ninja Van.

O preço vem da linha do país (ou da linha *): primeiro a coluna de peso, depois o preço base e, por último, Price for countries not in the table. Se não houver preço, o método é ocultado para aquele carrinho. O preço é calculado na moeda padrão da loja, arredondado para as casas decimais dela e exibido ao cliente em sua moeda com o imposto da Tax class selecionada.

Com Live rates ativado, uma entrega dentro da Indonésia é precificada primeiro pela Ninja Van. A extensão converte o endereço de entrega em códigos de zona da Ninja Van: a região (província) do endereço, o campo City (cidade ou regência) e, para cidades com várias zonas, o distrito (Kecamatan) informado em Address 1 ou Address 2. Ela envia os seus códigos de origem, os códigos de entrega, o peso e o nível de serviço, e converte a tarifa de IDR para a moeda da sua loja. Com Per item, é enviada uma requisição por peso distinto de item, até 5 por carrinho. Com mais pesos diferentes, a tabela de preços é usada.

A Tariff API permite 20 requisições por minuto, então as respostas são guardadas em cache em uma tabela da extensão: preços por 6 horas, "sem preço para esta rota" por 1 hora e falhas por 5 minutos. Salvar as configurações não limpa esse cache. A extensão 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, retornar 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.

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 a Ninja Van na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

A extensão apenas calcula preços. Ela não cria pedidos na Ninja Van, não imprime etiquetas aéreas (AWB), não agenda coletas, não rastreia encomendas e não trata COD. Use o Dashboard da Ninja Van para isso. Não há seletor de pontos de retirada (Ninja Points): o método é entrega porta a porta. Ela não acrescenta nada aos pedidos: o pedido mostra o título do método e o custo do frete como qualquer outro método de envio do OpenCart. As tarifas em tempo real não estão disponíveis fora da Indonésia.

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 Ninja Van é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit, acima das configurações. Informe 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-ninja-van e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com permissão de modificação 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 de domínio dela. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a Ninja Van 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 Ninja Van não aparece na finalização de compra: verifique se a licença está ativa e se Enable Ninja Van está ativado. Confira Geo zone (ou Ignore shipping zones e Countries), os limites de peso e Minimum order amount, e se o país, a linha * ou Price for countries not in the table tem um preço. Confirme que os produtos têm Requires Shipping definido como Yes.

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, região (província), cidade ou regência em City e, para cidades com várias zonas, o distrito (Kecamatan) em uma linha de endereço. Caso contrário, a tabela de preços é usada. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão.

As tarifas em tempo real não são solicitadas de forma alguma: as linhas de status abaixo de Tarifas em tempo real (API) — Indonésia mostram o motivo: faltam os códigos de zona de origem, só um dos dois códigos foi informado, os códigos informados não formam um par no mapeamento 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, enquanto isso, a tabela de preços é usada. Salvar as configurações não encerra a pausa.

Em qual moeda estão os preços: a tabela e as condições estão na moeda padrão da sua loja. As tarifas em tempo real estão em rúpias (IDR), convertidas com IDR conversion rate, exceto se a moeda da loja for IDR.

A página mostra "Warning: You do not have permission to modify VibeFox Ninja Van!": o grupo de usuários administradores só pode visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_ninja_van (OpenCart 3) ou extension/vfd_ninja_van/shipping/vfd_ninja_van (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: uma loja com seu próprio campo de distrito (Kecamatan) pode fornecer os códigos de zona com o evento do OpenCart vfd_ninja_van/tariff_zone (gatilho catalog/vfd_ninja_van/tariff_zone), inclusive para a zona de origem. O endereço da Tariff API pode ser substituído pela configuração vfd_njvn_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 Ninja Van. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre restaura Enable Ninja Van, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações da Ninja Van, o último status da Tariff API 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 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 Ninja Van na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

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