VibeFox Ninja Van for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 5.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Tarifario 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 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 dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_ninja_van a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox Ninja Van, o haz clic en Settings debajo del nombre del plugin en la página Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Introduce tus precios de Ninja Van en la tabla de precios. Para Indonesia, opcionalmente activa Live rates (consulta Configuración).
6. Añade VibeFox Ninja Van a una zona de envío (por ejemplo, "Singapur") en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones y elige los países.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox Ninja Van. Se aplican a todas las zonas de envío. Cuando añades el método a una zona, la ventana de la zona solo tiene un campo:
Title (zone): el nombre que ven los clientes para esta zona. Déjalo vacío para usar el Method title general.
General
Enable/Disable: activa o desactiva el método en todas las zonas a la vez.
Method title: el nombre del método de envío que se muestra en el carrito y en la finalización de compra. Una zona puede sustituirlo. Por defecto: Ninja Van.
Precios (en la moneda de tu tienda)
Introduce los precios de tu tarifario de Ninja Van en la moneda de tu tienda. Si tu tarifario está en SGD, MYR, IDR, PHP, THB o VND, 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 la cruz 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.
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 método en ese caso.
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 de esta sección muestran la zona de origen, una tasa de conversión que falta y la última respuesta de la API de tarifas.
Live rates: obtén precios en tiempo real de Ninja Van para las 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) (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, de la tabla de códigos de zona de Ninja Van (CSV) enlazada en la página de ajustes. Introduce ambos, o déjalos vacíos para detectarlos a partir de la dirección de la tienda en WooCommerce > Settings > General: Indonesia, provincia, 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 y se muestra un error.
IDR conversion rate: la API de tarifas devuelve la tarifa en rupias indonesias (IDR). Si la moneda 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. Sin este dato no se usan los precios en tiempo real, sino la tabla de precios.
Condiciones
Minimum weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite.
Maximum weight (kg): oculta el método cuando el carrito pesa más. Por defecto: 30. 0 significa sin límite.
Minimum order amount: muestra el método solo cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual el envío con Ninja Van es gratuito. Déjalo vacío si no hay envío gratuito.
Excluded shipping classes: oculta el método cuando el carrito contiene un producto de alguna de estas clases de envío de WooCommerce.
Tax status: Taxable añade el impuesto de WooCommerce al coste de envío; None no lo añade. Elige None si los precios de la tabla ya incluyen impuestos (GST, SST, IVA).
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece Ninja Van para los países indicados abajo, aunque el método no esté añadido a ninguna zona de envío.
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 WooCommerce > Status > Logs (fuente vfd_ninja_van). No se registran direcciones de clientes. Las solicitudes fallidas a la API de tarifas se registran aunque esta opción esté desactivada. Desactívala cuando termines.
Remove data on uninstall: si está activado, al eliminar el plugin se borran todos los ajustes de Ninja Van y los métodos de zona. Desactivar el plugin nunca borra nada.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, WooCommerce pide una tarifa al plugin. Primero, el plugin comprueba las condiciones: país de entrega, peso del carrito, importe mínimo del pedido y clases de envío excluidas. Si se aplica el envío gratuito, el cliente ve el método sin coste 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, el precio base, si no, Price for countries not in the table. Los pesos de los productos se convierten de la unidad de peso de tu tienda a kilogramos. Si no hay precio, el método se oculta.
Con Live rates activado, una entrega dentro de Indonesia se tarifica primero por Ninja Van. El plugin convierte las direcciones de origen y de entrega en códigos de zona de Ninja Van: provincia, ciudad o regencia y, en las ciudades con varias zonas, el distrito (Kecamatan) indicado 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.
La API de tarifas permite 20 solicitudes por minuto, así 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 plugin 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 asociar, se usa el precio de la tabla. Los errores van al registro, nunca al cliente.
El método funciona en la finalización de compra clásica y en los bloques Cart y Checkout. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin 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 método es entrega a domicilio. Los precios en tiempo real no están disponibles fuera de Indonesia.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox comprada en vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox Ninja Van. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa, y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Ninja Van no se muestra a los clientes en la finalización de compra. Los gestores de la tienda con sesión iniciada sí lo ven, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un aviso en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Ninja Van no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el método esté añadido a la zona del país del cliente (o que Ignore shipping zones esté activado y el país esté permitido). Revisa los límites de peso, Minimum order amount y Excluded shipping classes, y que el país, la fila * o Price for countries not in the table tengan un precio.
El precio en tiempo real no se usa para algunas direcciones: el destino debe asociarse a una zona de Ninja Van: Indonesia, provincia, 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 para ver el motivo y revisa las líneas de estado en Tarifas en tiempo real (API) — Indonesia.
No se solicitan precios en tiempo real en absoluto: las líneas de estado muestran 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), o falta la 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.
En qué moneda están los precios: la tabla está en la moneda 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.
Desarrolladores: un sitio con su propio campo de distrito (Kecamatan) en la finalización de compra puede proporcionar los códigos de zona con el filtro vfd_njvn_tariff_zone.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes, los métodos de zona, el último estado de la API de tarifas y los precios en tiempo real en caché solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus líneas de envío.
Ninja Van es una marca comercial de su respectivo titular. Este plugin no está afiliado a Ninja Van ni cuenta con su respaldo.