VibeFox Blue Express for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Cuenta de Blue Express (solo para tarifas en tiempo real): las tarifas en tiempo real requieren una cuenta de comercio electrónico de Blue Express y su clave de API (x-api-key). Solicítalas a Blue Express: developers.bluex.cl o gpo.integraciones@bx.cl. El servicio que uses (EX, PY o MD) debe estar habilitado en tu contrato con Blue Express. Si solo usas precios fijos, no necesitas una clave de API.
Puntos de recogida: el mapa de Blue Express se carga desde widget-pudo.blue.cl en el navegador del cliente.
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_blue_express a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox Blue Express, 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 la clave de API, el servicio, el código de distrito de origen (por ejemplo SCL), el tipo de cambio CLP si la moneda de tu tienda no es CLP y los precios fijos (por ejemplo CL=4500). Consulta la sección Configuración.
6. Ve a WooCommerce > Settings > Shipping > Shipping zones y añade VibeFox Blue Express a tu zona de Chile. En los ajustes del método elige el título y el tipo de entrega (a domicilio o recogida en un punto de Blue Express). Añádelo dos veces para ofrecer ambas opciones.
Configuración
Los ajustes principales están en WooCommerce > Settings > Shipping > VibeFox Blue Express. Se aplican a todas las zonas de envío. Las advertencias sobre ajustes que ocultarían el método o la tarifa en tiempo real (sin clave de API, sin tipo de cambio CLP, tabla de precios fijos vacía) se muestran en la parte superior de la página. Al guardar los ajustes se borra la caché.
Ventana de zona (al añadir el método a una zona de envío)
Title: nombre del método de envío que ve el cliente en esta zona. Déjalo vacío para usar el Name global.
Delivery type: As in the global settings (predeterminado), Home delivery o Pickup at a Blue Express point (PUDO). Añade el método dos veces a una zona para ofrecer entrega a domicilio y recogida.
General
Enable/Disable: activa o desactiva el método en todas partes, en todas las zonas de envío.
Name: nombre del método de envío que se muestra en la finalización de compra. Una zona puede definir su propio título. Predeterminado: Blue Express.
Tax status: los precios de Blue Express incluyen IVA. Elige None si WooCommerce no debe añadir impuestos encima, o Taxable si debe hacerlo.
API de Blue Express (necesaria para las tarifas en tiempo real)
API key: tu clave de API de Blue Express (encabezado x-api-key). Sin ella solo se usan los precios fijos.
Service: el servicio de Blue Express que se usa para la tarifa: Express (EX) (predeterminado), Prioritario (PY) o SameDay (MD). Debe estar habilitado en tu contrato con Blue Express.
Origin district code: el código de distrito de Blue Express del lugar desde el que envías, por ejemplo SCL para Santiago (predeterminado). Si no estás seguro, pregúntale a Blue Express.
CLP per 1 (your currency): los precios de Blue Express están en pesos chilenos (CLP). Si tu tienda usa otra moneda, introduce cuántos CLP vale una unidad de ella, por ejemplo 1050. Sin este valor no se usan las tarifas en tiempo real. Se ignora si la moneda de tu tienda es CLP.
Precio
Rate source: cómo se calcula el precio.
Fixed prices: una línea por país en el formato COUNTRY_CODE=PRICE, en la moneda de tu tienda, por ejemplo CL=4500 en una tienda en CLP o CL=4.50 en una tienda en EUR. Se acepta la coma o el punto como separador decimal. Las líneas no válidas se notifican al guardar. Los precios fijos pueden usarse para cualquier país.
Fixed price per: Order cobra el precio una vez. Item (price x quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo al precio fijo. La tarifa de la API siempre corresponde a todo el envío.
Condiciones
Min weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite.
Max weight (kg): oculta el método cuando el carrito pesa más. Predeterminado: 100. 0 significa sin límite.
Minimum order subtotal: muestra el método solo a partir de este subtotal del carrito (en la moneda de la tienda). Déjalo vacío para mostrarlo siempre.
Excluded shipping classes: si algún artículo del carrito pertenece a una clase de envío de WooCommerce seleccionada, el método se oculta.
Envío gratis
Free shipping: activa el envío gratis a partir de un subtotal del carrito.
Free from subtotal: subtotal del carrito (en la moneda de la tienda) a partir del cual el envío es gratis.
Recogida en puntos de Blue Express (PUDO)
Pickup point by default: si está activado, los métodos de Blue Express entregan en un punto de Blue Express elegido por el cliente. Es el valor predeterminado para los métodos de zona con Delivery type = As in the global settings. El cliente debe elegir un punto para realizar el pedido.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece el método aunque no esté añadido a la zona de envío correspondiente. En ese caso usa los ajustes globales (sin título de zona ni tipo de entrega).
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías. Solo se usa con Ignore shipping zones.
Avanzado
Debug log: registra las solicitudes y decisiones en WooCommerce > Status > Logs, origen "vfd-blue-express". Los errores de la API siempre se registran. La clave de API y las direcciones de los clientes nunca se registran.
Remove data on uninstall: si está activado, al eliminar el plugin se borran sus ajustes y métodos de zona. Desactivarlo nunca borra los ajustes. Los puntos de recogida guardados en los pedidos se conservan.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, el plugin comprueba el peso del carrito, el Minimum order subtotal y las Excluded shipping classes. Si se aplica el envío gratis, la tarifa es 0 y no se envía ninguna solicitud a Blue Express.
Para obtener una tarifa en tiempo real, la dirección debe estar en Chile, con región y ciudad (comuna). El plugin pide primero a Blue Express que reconozca la comuna y luego solicita el precio para el servicio, el distrito de origen, el destino y los paquetes. Cada producto se envía con su peso y sus dimensiones convertidos a kg y cm. Los productos sin peso o tamaño se envían como 0,01 kg, 10 x 10 x 10 cm. El valor declarado se envía en CLP. El precio en CLP se convierte a la moneda de tu tienda.
Las tarifas se guardan en caché durante 1 hora y los datos de comunas durante 12 horas. Una llamada fallida a la API se recuerda durante 5 minutos, y el tiempo de espera es de 10 segundos, de modo que una API lenta o no disponible no ralentiza cada actualización de la finalización de compra. Los errores de la API nunca se muestran al cliente: el método se oculta o, en el modo alternativo, se usa el precio fijo. El motivo se escribe en el registro.
El método funciona en la finalización de compra clásica y en los bloques Carrito y Finalizar compra. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin no crea envíos ni etiquetas en Blue Express, no asigna números de seguimiento ni muestra actualizaciones de seguimiento. Crea el envío en tu cuenta de Blue Express. No hay tablas de tarifas regionales por comuna: usa la tarifa de la API de Blue Express o un precio fijo por país. Las tarifas en tiempo real solo funcionan para Chile.
Puntos de recogida
Con el tipo de entrega Pickup at a Blue Express point (PUDO), el cliente ve Choose pickup point debajo de la opción de Blue Express, tanto en la finalización de compra clásica como en la de bloques. El botón abre el mapa oficial de Blue Express, donde el cliente elige un punto. El punto elegido se muestra con su nombre y dirección, y el botón cambia a Change pickup point. Después, la tarifa se recalcula con el precio de recogida (PUDO) de Blue Express.
El pedido no se puede realizar sin un punto: el cliente ve Please choose a Blue Express pickup point. Esto se comprueba en el servidor.
El punto elegido se guarda en el pedido con su código de agencia de Blue Express, nombre y dirección. En la pantalla de pedidos del administrador se muestra debajo de la dirección de envío como Blue Express pickup point. Haz clic en Edit para elegir otro punto en el mapa de Blue Express o para introducir a mano el código de agencia, el nombre y la dirección, y luego haz clic en Save pickup point. El cambio queda registrado en una nota del pedido. El cliente ve el punto en la página del pedido y en los correos electrónicos del pedido (HTML y texto sin formato). Los correos a la tienda también muestran el código de agencia. Los pedidos existentes conservan los datos de su punto de recogida.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox Blue Express. 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 quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Blue Express no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión 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 recordatorio 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 renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Blue Express 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 de la dirección del cliente (o que Ignore shipping zones está activado y el país está permitido). Lee las advertencias de la parte superior de la página de ajustes. Revisa los límites de peso, el Minimum order subtotal y las Excluded shipping classes, y que Fixed prices tenga una línea para el país si usas precios fijos o la alternativa.
Las tarifas en tiempo real no aparecen: con Blue Express API only, el método se oculta cuando no hay tarifa. Activa Debug log, recarga la finalización de compra y abre WooCommerce > Status > Logs (origen "vfd-blue-express"). Motivos habituales: no hay clave de API, la moneda de la tienda no es CLP y falta el tipo de cambio, falta la región o la comuna en la dirección, Blue Express no reconoce la comuna o hay un error de la API (por ejemplo, HTTP 401 o 403 cuando la clave de API es rechazada). Con Blue Express API, fixed price if the API gives no rate, los clientes siguen recibiendo el precio fijo mientras tú solucionas el problema.
Se añade impuesto sobre el precio de Blue Express: los precios de Blue Express incluyen IVA. Pon Tax status en None si WooCommerce no debe añadir impuestos encima.
El mapa no se abre: el mapa se carga desde widget-pudo.blue.cl en el navegador del cliente, por lo que esa dirección debe ser accesible y no estar bloqueada en tu sitio.
Las tarifas parecen desactualizadas tras un cambio: guarda la página de ajustes. Esto borra las tarifas y los datos de comunas en caché.
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 para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los ajustes y solo borra la caché. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia, el estado de la licencia de este plugin y la caché siempre se eliminan. Los ajustes y los métodos de zona solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los puntos de recogida guardados en los pedidos nunca se eliminan.
Blue Express es una marca comercial de su respectivo titular. Este plugin no está afiliado a Blue Express ni cuenta con su respaldo.