VibeFox Ninja Van for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado con la 3.0.5.0) o 4.0.2 y posteriores (probado con la 4.1.0.3).
PHP: 8.0 o posterior.
Tarifa de Ninja Van: los precios de tu cuenta de remitente de Ninja Van o los que te facilite el equipo comercial de Ninja Van, introducidos en la tabla de precios. No se necesitan claves de API. Los precios opcionales en tiempo real dentro de Indonesia usan la Tariff API de Ninja Van, que es pública y no requiere autenticación.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
La descarga es un único archivo zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_ninja_van-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_ninja_van.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.
OpenCart 3
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_ninja_van-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions, elige el tipo de extensión Shipping. Busca VibeFox Ninja Van y haz clic en Install (el botón verde +).
3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes.
4. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Edit, y haz clic en Activate (consulta Clave de licencia).
5. Introduce tus precios de Ninja Van en la tabla de precios. Para Indonesia, opcionalmente activa Live rates (consulta Configuración). Activa Enable Ninja Van y haz clic en Save.
OpenCart 4
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_ninja_van.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.
2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.
3. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Ninja Van, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).
4. Introduce la clave de licencia y los ajustes como en los pasos 4 y 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable Ninja Van y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Ninja Van que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. No se guarda nada y aparece un error cuando Method title está vacío, tiene más de 64 caracteres o contiene < > ; = # { }, cuando un campo numérico contiene texto o un número negativo, cuando IDR conversion rate es 0, cuando Minimum weight (kg) es mayor que Maximum weight (kg) o cuando Sort order no es un número entero. Si la tienda no tiene una clase de peso en kilogramos y la unidad de la clase de peso predeterminada no la reconoce la extensión, un aviso indica que los pesos de los productos se toman como kilogramos: añade una clase de peso en kg en System > Localisation > Weight Classes. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
General
Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica en Conditions, o usar Ignore shipping zones.
Enable Ninja Van: muestra u oculta Ninja Van en la finalización de compra. Por defecto: desactivado.
Method title: el nombre del método de envío que el cliente ve en el carrito y en la finalización de compra. Por defecto: Ninja Van. Obligatorio, 64 caracteres como máximo.
Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Elige No tax si los precios de la tabla ya incluyen impuestos (GST, SST, VAT).
Sort order: la posición de Ninja Van entre los métodos de envío en la finalización de compra. Un número entero.
Precios (en la moneda predeterminada de tu tienda, sin impuestos)
Introduce los precios de tu tarifa de Ninja Van en la moneda predeterminada de tu tienda. Si tu tarifa está en SGD, MYR, IDR u otra moneda, conviértela antes. Esta tabla se usa para todos los destinos fuera de Indonesia y siempre que no haya un precio en tiempo real disponible.
Price table: una fila por país de destino. Haz clic en Add country para añadir una fila y en el botón × para quitarla. Elige * All other countries para todos los países sin fila propia. Cada fila tiene un precio Base y columnas de peso: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg y XL por encima de 5 kg. Una columna de peso vacía (o con 0) usa el precio base. Un precio base de 0 significa envío gratis a ese país. Se aceptan tanto "9.99" como "9,99". Las filas sin precios se eliminan al guardar y solo se conserva la primera fila de cada país.
Price for countries not in the table: se usa cuando la tabla no tiene fila para el país de destino (y tampoco una fila *), o la fila no tiene precio para este peso. Déjalo vacío para ocultar el método en ese caso. 0 significa envío gratis.
Price applies: la forma en que se calculan los precios. Esto también se aplica a los precios en tiempo real.
Tarifas en tiempo real (API) — Indonesia
La Tariff API de Ninja Van devuelve la tarifa de envío estándar, sin recargos ni descuentos, para paquetes enviados dentro de Indonesia. Ninja Van la ofrece solo para Indonesia. Cuando Live rates está activado, las líneas de estado bajo el título de la sección muestran la zona de origen, un tipo de cambio IDR que falta y la última respuesta de la Tariff API (entorno, hora y resultado). Se actualizan después de cada guardado.
Live rates: obtén precios en tiempo real de Ninja Van para entregas dentro de Indonesia. Por defecto: desactivado. Sin esta opción no se envía nada a Ninja Van durante la finalización de compra.
Environment: Production (api.ninjavan.co) (por defecto) o Sandbox — testing only (api-sandbox.ninjavan.co).
Service level: el servicio para el que se solicita el precio: Standard (por defecto), Express, Same day o Next day. Si Ninja Van no tiene precio para la ruta y el servicio, se usa la tabla de precios.
Ship-from zone code L1 y Ship-from zone code L2: los códigos de nivel L1 y L2 del distrito desde el que envías, por ejemplo ID_A00007_01 e ID_B00069_01, del mapa de códigos de zona de Ninja Van (CSV) cuya dirección se muestra bajo el campo. Introduce los dos: la dirección de la tienda en OpenCart no tiene ciudad ni calle separadas, así que la zona de origen no se puede detectar a partir de ella. Los códigos se convierten a mayúsculas. Un código con un formato incorrecto se borra con un aviso. Si solo se introduce un código, un aviso pide que introduzcas ambos y una línea de estado indica que no se solicitan precios en tiempo real. Una línea de estado también avisa cuando los dos códigos no forman pareja en el mapa de códigos de zona.
IDR conversion rate: la Tariff API devuelve la tarifa en rupias indonesias (IDR). Si la moneda predeterminada de tu tienda es IDR, déjalo vacío. Si no, introduce cuánto vale 1 IDR en la moneda de tu tienda, por ejemplo 0.000058. Debe ser mayor que 0. Sin este valor no se usan precios en tiempo real y se usa la tabla de precios.
Condiciones
Minimum weight (kg): oculta el método cuando el carrito pesa menos. Los pesos de los productos se convierten de su clase de peso de OpenCart a kilogramos. 0 significa sin límite (por defecto).
Maximum weight (kg): oculta el método cuando el carrito pesa más. Por defecto: 30. 0 o un campo vacío significan sin límite. No puede ser menor que Minimum weight (kg).
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón y antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal de los productos que necesitan envío (después del cupón y antes de impuestos) a partir del cual el envío de Ninja Van es gratis. Déjalo vacío si no quieres envío gratis.
Geo zone: ofrece Ninja Van solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. No se comprueba cuando Ignore shipping zones está activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece Ninja Van para los países de abajo, sea cual sea la Geo zone. Desactivado (por defecto), la zona geográfica decide y la lista de países no se usa.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de tarifas en storage/logs/vfd_njvn_debug.log.php (en OpenCart 4, system/storage/logs/vfd_njvn_debug.log.php). El archivo no se puede leer desde la web. No se registran direcciones de clientes ni códigos de zona. Las solicitudes fallidas a la Tariff API se registran aunque esta opción esté desactivada. Desactívala cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_njvn_debug.old.log.php y se inicia un registro nuevo.
Log: muestra el tamaño y las entradas más recientes del registro de depuración. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar la extensión se borran los ajustes de Ninja Van y el registro. Desactivado (por defecto), se conservan para una reinstalación. Las tarifas en caché siempre se borran.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La extensión no tiene claves secretas, así que se exporta todo.
Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal.
Cómo funciona en la finalización de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de Ninja Van. Si hay una Geo zone configurada (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, Ninja Van no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni se incluyen en el importe del pedido. Después la extensión comprueba las condiciones: la lista de países de Ignore shipping zones (si está activado), el peso del carrito y el importe mínimo del pedido. El importe del pedido es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna solicitud a Ninja Van.
El precio sale de la fila del país (o de la fila *): primero la columna de peso, si no hay, el precio base y, si tampoco, Price for countries not in the table. Si no hay precio, el método se oculta para ese carrito. El precio se calcula en la moneda predeterminada de tu tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
Con Live rates activado, un envío dentro de Indonesia lo calcula primero Ninja Van. La extensión convierte la dirección de entrega en códigos de zona de Ninja Van: la región (provincia) de la dirección, el campo City (ciudad o regencia) y, en ciudades con varias zonas, el distrito (Kecamatan) escrito en Address 1 o Address 2. Envía tus códigos de origen, los códigos de entrega, el peso y el nivel de servicio, y convierte la tarifa de IDR a la moneda de tu tienda. Con Per item, se envía una solicitud por cada peso distinto de artículo, hasta 5 por carrito. Si hay más pesos distintos, se usa la tabla de precios.
La Tariff API permite 20 solicitudes por minuto, así que las respuestas se guardan en caché en una tabla de la extensión: los precios durante 6 horas, "sin precio para esta ruta" durante 1 hora y los fallos durante 5 minutos. Guardar los ajustes no borra esta caché. La extensión nunca envía más de 18 solicitudes por minuto y, después de una respuesta HTTP 429, se pausa durante una hora. El tiempo de espera de la API es de 12 segundos. Si Ninja Van no responde, responde con un error, no tiene precio para la ruta o la dirección no se puede asociar, se usa el precio de la tabla. Los errores van al registro, nunca al cliente.
En OpenCart 4 el cliente hace clic en Choose en el bloque del método de envío de la página de finalización de compra y elige Ninja Van en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
La extensión solo calcula precios. No crea pedidos en Ninja Van, no imprime guías aéreas (AWB), no reserva recogidas, no hace seguimiento de paquetes ni gestiona COD. Para eso usa el Dashboard de Ninja Van. No hay selector de puntos de recogida (Ninja Points): el método es entrega a domicilio. No añade nada a los pedidos: el pedido muestra el título del método y el coste de envío como cualquier otro método de envío de OpenCart. Los precios en tiempo real no están disponibles fuera de Indonesia.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox Ninja Van es el primer bloque de Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit, encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-ninja-van y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (se incluyen inglés y ruso).
Si no se acepta la clave, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Tras cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío de Ninja Van no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el administrador en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método se oculta a todos. Tras abrir una vez la página Edit, aparece un recordatorio en el Dashboard del administrador. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del administrador o la página Edit: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. No hace falta ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Ninja Van no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Ninja Van esté activado. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso y Minimum order amount, y que el país, la fila * o Price for countries not in the table tengan un precio. Comprueba que los productos tengan Requires Shipping en Yes.
El precio en tiempo real no se usa para algunas direcciones: el destino debe asociarse a una zona de Ninja Van: Indonesia, región (provincia), ciudad o regencia en City y, en ciudades con varias zonas, el distrito (Kecamatan) en una línea de dirección. Si no, se usa el precio de la tabla. Activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión.
No se solicitan precios en tiempo real: las líneas de estado bajo Live rates (API) — Indonesia muestran el motivo: faltan los códigos de zona de origen, solo se ha introducido uno de los dos códigos, los códigos introducidos no forman pareja en el mapa de códigos de zona, o falta IDR conversion rate.
Se ha alcanzado el límite de solicitudes (HTTP 429): las solicitudes en tiempo real se pausan una hora y, mientras tanto, se usa la tabla de precios. Guardar los ajustes no termina la pausa.
Moneda de los precios: la tabla y las condiciones están en la moneda predeterminada de tu tienda. Los precios en tiempo real están en rupias (IDR), convertidas con IDR conversion rate salvo que la moneda de tu tienda sea IDR.
La página dice "Warning: You do not have permission to modify VibeFox Ninja Van!": tu grupo de usuarios administradores solo puede ver los ajustes. Concede al grupo el permiso de modificación para extension/shipping/vfd_ninja_van (OpenCart 3) o extension/vfd_ninja_van/shipping/vfd_ninja_van (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: una tienda con su propio campo de distrito (Kecamatan) puede proporcionar los códigos de zona con el evento de OpenCart vfd_ninja_van/tariff_zone (disparador catalog/vfd_ninja_van/tariff_zone), también para la zona de origen. La dirección de la Tariff API se puede cambiar con el ajuste vfd_njvn_api_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Ninja Van. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Ninja Van, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de Ninja Van, el último estado de la Tariff API y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al reinstalar la extensión. Los pedidos existentes conservan su método de envío y su coste.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Ninja Van en la lista de extensiones instaladas y, después, en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.
Ninja Van es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por Ninja Van.