VibeFox Ninja Van for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Tarifario de Ninja Van: los precios de tu cuenta de remitente de Ninja Van o los que facilite el equipo comercial de Ninja Van, introducidos en la tabla de precios. No se necesitan claves de API. Los precios en tiempo real opcionales dentro de Indonesia usan la API de tarifas 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
1. En el back office, ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la carga, haz clic en Configure o busca más adelante VibeFox Ninja Van en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia situado en la parte superior de la página Configure, y haz clic en Activate (consulta Clave de licencia).
4. Introduce tus precios de Ninja Van en la tabla de precios. Para Indonesia, opcionalmente activa Live rates (consulta Configuración). Haz clic en Save.
Al instalarse, el módulo crea el transportista Ninja Van con el texto del tiempo de entrega Courier delivery. El transportista queda activado, asignado a todas las zonas y a todos los grupos de clientes, y sin regla fiscal. Puedes cambiar las zonas, los grupos de clientes, el tiempo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No definas precios allí: el precio siempre procede del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Ninja Van > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. No se guarda nada y se muestra un error 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 Method title tiene más de 64 caracteres. Si la unidad de peso de tu tienda no es una de las que conoce el módulo, tras guardar aparece una advertencia que indica que los pesos de los productos se toman en kilogramos.
General
Enable Ninja Van: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista que ve el cliente en el carrito y en la finalización de compra. Predeterminado: Ninja Van. Obligatorio, máximo 64 caracteres.
Tax: la regla fiscal del transportista, o No tax (predeterminado). Elige No tax si los precios de la tabla ya incluyen impuestos (GST, SST, VAT).
Precios (en la moneda predeterminada de tu tienda, sin impuestos)
Introduce los precios de tu tarifario de Ninja Van en la moneda predeterminada de tu tienda. Si tu tarifario está en SGD, MYR, IDR u otra moneda, conviértelo primero. 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 icono de papelera para eliminar una. Elige * All other countries para todos los países que no tengan fila propia. Cada fila tiene un Base price 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 gratuito 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 (ni fila *), o la fila no tiene precio para ese peso. Déjalo vacío para ocultar el transportista en ese caso. 0 significa envío gratuito.
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 API de tarifas de Ninja Van devuelve la tarifa de entrega estándar, sin recargos ni descuentos, para los 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, la falta de tasa de conversión y la última respuesta de la API de tarifas (entorno, hora y resultado).
Live rates: obtén precios en tiempo real de Ninja Van para entregas dentro de Indonesia. Predeterminado: desactivado. Sin esta opción no se envía nada a Ninja Van durante la finalización de compra.
Environment: Production (api.ninjavan.co) (predeterminado) o Sandbox — testing only (api-sandbox.ninjavan.co).
Service level: el servicio para el que se solicita el precio: Standard (predeterminado), 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, tomados de la tabla de códigos de zona de Ninja Van (CSV) cuya dirección se muestra debajo del campo. Introduce ambos o déjalos vacíos para detectarlos a partir de la dirección de la tienda en Shop Parameters > Contact > Stores: Indonesia, provincia (state), ciudad y, si la ciudad tiene varias zonas, el distrito (Kecamatan) en la línea de dirección. Un código con formato incorrecto se borra con una advertencia. Si solo se introduce uno de los códigos, una advertencia pide que introduzcas ambos y una línea de estado indica que no se solicitan precios en tiempo real.
IDR conversion rate: la API de tarifas devuelve la tarifa en rupias indonesias (IDR). Si la moneda predeterminada de tu tienda es IDR, déjalo vacío. En caso contrario, indica cuánto vale 1 IDR en la moneda de tu tienda, por ejemplo 0.000058. Debe ser mayor que 0. Sin esta tasa no se usan los precios en tiempo real, sino la tabla de precios.
Condiciones
Minimum weight (kg): oculta el transportista cuando el carrito pesa menos. Los pesos de los productos se convierten de la unidad de peso de tu tienda a kilogramos. 0 significa sin límite.
Maximum weight (kg): oculta el transportista cuando el carrito pesa más. Predeterminado: 30. 0 significa sin límite. No puede ser menor que Minimum weight (kg).
Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (productos que requieren envío, después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal del carrito (productos que requieren envío, después de descuentos, antes de impuestos) a partir del cual el envío de Ninja Van es gratuito. Déjalo vacío si no hay envío gratuito.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece Ninja Van para los países indicados abajo aunque el transportista no esté vinculado a su zona. Cuando está activado, el transportista se vincula a todas las zonas activas, incluidas las que crees más adelante. Al desactivarlo, el transportista recupera las zonas que tenía antes.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra los cálculos de tarifas en logs/vfd_njvn_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. No se registran direcciones de clientes. Las solicitudes fallidas a la API de tarifas se registran incluso cuando esta opción está desactivada. Desactívala cuando termines.
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 el módulo se eliminan sus ajustes, el transportista, los precios en caché y el registro. Si está desactivado, se conserva todo para una reinstalación.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de Ninja Van. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el importe del pedido. El módulo comprueba primero 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. Si se aplica envío gratuito, el precio es 0 y no se envía ninguna solicitud a Ninja Van.
El precio procede de la fila del país (o de la fila *): la columna de peso, si no la hay el precio base y, si tampoco, Price for countries not in the table. Si no hay precio, el transportista se oculta para ese carrito. El precio se calcula en la moneda predeterminada de la tienda y después se muestra en la moneda del carrito del cliente.
Con Live rates activado, las entregas dentro de Indonesia se tarifican primero con Ninja Van. El módulo convierte las direcciones de origen y de destino en códigos de zona de Ninja Van: provincia (state), ciudad o regencia y, en las ciudades con varias zonas, el distrito (Kecamatan) escrito en una línea de dirección. Envía los códigos, 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 de artículo distinto, hasta 5 por carrito. Si hay más pesos distintos, se usa la tabla de precios.
La API de tarifas permite 20 solicitudes por minuto, por lo que las respuestas se guardan en caché durante 6 horas, los errores durante 5 minutos y «sin precio para esta ruta» durante 1 hora. El módulo nunca envía más de 18 solicitudes por minuto y, tras 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 localizar, se usa el precio de la tabla. Los errores van al registro, nunca al cliente.
Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.
El módulo 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 el pago contra reembolso (COD). Para eso usa el Ninja Van Dashboard. No hay selector de puntos de recogida (Ninja Points): el transportista es de entrega a domicilio. Los precios en tiempo real no están disponibles fuera de Indonesia.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Ninja Van es el primer bloque de Modules > Module Manager > VibeFox Ninja Van > Configure, por 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-ninja-van y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).
Si la clave no se acepta, 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. Después de cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, el transportista Ninja Van no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. El front office de PrestaShop no sabe que has iniciado sesión en el back office, por lo que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave y después una vez por semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo 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. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o activa Ignore shipping zones y revisa Countries). Revisa 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. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.
El precio en tiempo real no se usa para algunas direcciones: el destino debe asociarse a una zona de Ninja Van: Indonesia, provincia (state), ciudad o regencia y, en las 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 revisa el campo Log en la página del módulo.
Los precios en tiempo real no se solicitan en absoluto: las líneas de estado bajo Tarifas en tiempo real (API) — Indonesia indican el motivo: la dirección de la tienda no está en Indonesia o no se pudo detectar la zona de origen (introduce ambos códigos de zona), solo se ha introducido uno de los dos códigos, los códigos introducidos no forman una pareja en la tabla de códigos de zona, o falta IDR conversion rate.
Límite de solicitudes alcanzado (HTTP 429): las solicitudes en tiempo real se pausan durante una hora y, mientras tanto, se usa la tabla de precios.
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), convertidos con IDR conversion rate salvo que la moneda de tu tienda sea IDR.
La página indica que no se encontró el transportista Ninja Van: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Desarrolladores: una tienda con su propio campo de distrito (Kecamatan) puede proporcionar los códigos de zona mediante el hook actionVfdNjvnTariffZone.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Ninja Van y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Los precios en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes, el último estado de la API de tarifas y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, el transportista guardado recupera el estado que tenía antes de la desinstalación.
Ninja Van es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por Ninja Van.