VibeFox Blue Express for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Cuenta de Blue Express (solo para tarifas en tiempo real): las tarifas en tiempo real necesitan una cuenta de comercio electrónico de Blue Express y su clave de API (x-api-key). Solicítala 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.

Regiones chilenas: para una tarifa en tiempo real, la dirección de entrega debe tener una región chilena. Si a tu tienda le faltan regiones chilenas, la extensión puede añadirlas por ti (consulta la sección Configuración).

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

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_blue_express-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_blue_express.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_blue_express-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Blue Express 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. Pega 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 la clave de API, el servicio, el código de distrito de origen (por ejemplo SCL), el tipo de cambio a CLP si la moneda de tu tienda no es CLP, y los precios fijos (por ejemplo CL=4500). Activa Enable/Disable para la entrega a domicilio y Pickup point option si quieres ofrecer recogida en puntos de Blue Express. Haz clic en Save. Consulta la sección Configuración.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_blue_express.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 Blue Express, haz clic en Install (el botón verde +) y luego 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 los mismos en ambas versiones.

Al instalar, la extensión crea una tabla para los puntos de recogida de los pedidos. El método está desactivado hasta que actives la entrega a domicilio o la opción de punto de recogida y guardes. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes de Blue Express que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Blue Express > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas de Blue Express y los datos de comunas que están en caché. Solo los usuarios administradores con el permiso de modificación para esta extensión pueden guardar los ajustes. Las condiciones, los precios y la clase de impuesto de abajo se aplican a ambas opciones.

Los valores no válidos se rechazan con un error y no se guarda nada: un nombre vacío o con los caracteres < > ; = # { }, un nombre de más de 64 caracteres, un número negativo o no válido, un Min weight (kg) mayor que Max weight (kg), un Sort order que no es un número entero, o una clase de impuesto o zona geográfica desconocida.

En la parte superior de la página aparecen advertencias sobre ajustes que ocultarían las opciones o la tarifa en tiempo real: falta la clave de API, una moneda de la tienda distinta de CLP sin tipo de cambio, una tabla de precios fijos vacía, ninguna zona para Chile, y una tienda sin clase de peso en kilogramos ni clase de longitud en centímetros cuya unidad predeterminada la extensión no reconoce (los pesos se leen entonces como kg y las dimensiones como cm).

General

Enable/Disable: activa o desactiva la entrega a domicilio de Blue Express.

Name: nombre del método de envío que se muestra en la finalización de compra para la entrega a domicilio. Predeterminado: Blue Express. Obligatorio, máximo 64 caracteres.

Tax class: la clase de impuesto del coste de envío, o None (no tax on shipping) (predeterminado). Los precios de Blue Express incluyen IVA. Elige None si OpenCart no debe añadir impuestos encima. Se aplica a ambas opciones.

Sort order: posición de Blue Express entre los métodos de envío en la finalización de compra. Un número entero.

Recogida en puntos de Blue Express (PUDO)

Pickup point option: ofrece la entrega en un punto de Blue Express elegido por el cliente, como segunda opción junto a la entrega a domicilio. Desactivada por defecto.

Pickup point name: nombre del método de envío que se muestra en la finalización de compra para la recogida en un punto de Blue Express. Predeterminado: Blue Express pickup point. Obligatorio, máximo 64 caracteres.

API de Blue Express (necesaria para tarifas en tiempo real)

API key: tu clave de API de Blue Express (cabecera x-api-key). Sin ella solo se usan los precios fijos. Tras guardar, el campo queda vacío y muestra A key is saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.

Remove the saved API key: actívalo y guarda para eliminar la clave guardada.

Service: el servicio de Blue Express usado 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). Pregunta a Blue Express si no estás seguro.

CLP per 1 (your currency): la etiqueta muestra la moneda predeterminada de tu tienda, por ejemplo CLP per 1 EUR. Los precios de Blue Express están en pesos chilenos (CLP). Introduce cuántos CLP vale una unidad de la moneda predeterminada de tu tienda, por ejemplo 1050. Sin este valor no se usan tarifas en tiempo real. Se ignora cuando la moneda de la tienda es CLP.

Precio

Rate source: cómo se calcula el precio. La tarifa en tiempo real necesita una dirección chilena con región y comuna (ciudad). Los errores se escriben en el registro, nunca se muestran al cliente.

Fixed prices: una línea por país en el formato CÓDIGO_DE_PAÍS=PRECIO, en la moneda predeterminada de tu tienda, sin impuestos, 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 ignoran y se listan en una advertencia al guardar. Un país sin línea no tiene precio fijo, así que las opciones se ocultan para él cuando se necesita el precio fijo. Los precios fijos pueden usarse para cualquier país.

Fixed price per: Order (predeterminado) 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 es para el envío completo.

Condiciones

Min weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite (predeterminado).

Max weight (kg): oculta el método cuando el carrito pesa más. Predeterminado: 100. 0 significa sin límite; un campo vacío significa 100 kg.

Minimum order subtotal: muestra el método solo a partir de este subtotal del carrito (moneda de la tienda, productos que requieren envío, después del cupón, sin impuestos). Déjalo vacío para mostrarlo siempre.

Envío gratuito

Free shipping: activa el envío gratuito a partir de un subtotal del carrito.

Free from subtotal: el subtotal del carrito (moneda de la tienda, productos que requieren envío, después del cupón, sin impuestos) a partir del cual el envío es gratuito. Entonces no se envía ninguna solicitud a Blue Express. Solo se usa cuando Free shipping está activado.

Disponibilidad

Geo zone: ofrece Blue Express solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se comprueba con Ignore shipping zones.

Ignore shipping zones: ofrece ambas opciones en todas las zonas geográficas. Los países se limitan entonces con la lista de abajo.

Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Solo se usa con Ignore shipping zones.

Regiones chilenas (solo se muestra cuando faltan regiones chilenas en tu tienda)

Blue Express necesita la región de una dirección chilena (RM, VS, etc.) para la tarifa en tiempo real. La región se toma de la zona de la dirección, por su código o por su nombre. La sección muestra cuántas zonas tiene Chile en tu tienda y qué regiones faltan (una tienda estándar de OpenCart 3.0.5 tiene 15 de las 16, sin Ñuble). Haz clic en Add Chilean regions para añadir las regiones que faltan como zonas de Chile, con los códigos que usa Blue Express. Las regiones que ya tienes, por código o por nombre, no se añaden dos veces. No se cambia nada hasta que hagas clic en el botón. También puedes añadirlas tú mismo en System > Localisation > Zones.

Avanzado

Debug log: registra las solicitudes y decisiones en storage/logs/vfd_blex_debug.log.php. El archivo no se puede leer desde la web. Los errores de la API siempre se registran. La clave de API y las direcciones de los clientes nunca se registran. Desactiva el registro cuando termines. El registro se rota al llegar a 5 MB.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar la extensión se borran los ajustes, las tarifas en caché y el registro. Si está desactivado (predeterminado), se conservan para una reinstalación. Los puntos de recogida guardados en pedidos siempre se conservan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de API no se exporta.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. La clave de API guardada se conserva.

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 cada opción activada. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, Blue Express no se ofrece. Con Ignore shipping zones decide la lista de Countries. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no entran en el subtotal. La extensión comprueba el peso del carrito y el Minimum order subtotal. El subtotal es el precio de los productos que requieren envío, después del descuento del cupón y antes de impuestos. Las tarjetas de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Blue Express.

Para una tarifa en tiempo real, la dirección debe estar en Chile, con región y ciudad (comuna). La extensión primero pide a Blue Express que reconozca la comuna y después solicita el precio del 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 desde sus clases de peso y longitud. 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 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.

Las tarifas se guardan en caché durante 1 hora y los datos de comunas hasta 12 horas, pero nunca más de lo que dura la caché de OpenCart (1 hora por defecto). Un fallo de la API se recuerda durante 5 minutos, y el tiempo de espera es de 10 segundos, para que una API lenta o no disponible no ralentice cada actualización de la finalización de compra. Los errores de la API nunca se muestran al cliente: la opción se oculta, o se usa el precio fijo en el modo de respaldo. El motivo se escribe en el registro.

La extensión 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.

En OpenCart 4 el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige Blue Express o Blue Express pickup point en la ventana Shipping method options. Las opciones funcionan igual que en OpenCart 3; el cuadro de punto de recogida se describe en Puntos de recogida.

Puntos de recogida

Cuando la opción de punto de recogida está activada, aparece un cuadro con el botón Choose pickup point bajo Blue Express pickup point en el paso Delivery Method de la finalización de compra de OpenCart. 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. El punto se guarda para la sesión de compra, y la tarifa se recalcula con el precio de recogida (PUDO) de Blue Express. Si el precio cambia, la opción muestra el nuevo precio. Si la opción ya no se ofrece para ese punto, el paso de entrega se recarga. Mientras no se elija un punto, la opción muestra el precio del envío a domicilio.

El cliente no puede continuar sin un punto: Continue en el paso de entrega se rechaza con Please choose a Blue Express pickup point. Esto se comprueba en el navegador y de nuevo en la tienda. Un código de punto mal formado se rechaza con The selected Blue Express pickup point is not valid. Please choose it again on the map., y la elección anterior se mantiene. Si el guardado falla, el cliente ve The pickup point could not be saved. Please try again.

En OpenCart 4 el cliente hace clic en Choose en el bloque de métodos de envío de la finalización de compra. La ventana Shipping method options muestra el mismo cuadro con Choose pickup point bajo Blue Express pickup point mientras esa opción está seleccionada. Cuando el precio cambia con el punto elegido, la opción de la ventana muestra el nuevo precio, y si la opción de recogida ya estaba guardada para la compra, el campo del método de envío y el bloque de confirmación del pedido también se actualizan. Si la opción ya no se ofrece para ese punto, la ventana se cierra y se vuelve a cargar la lista de métodos de envío. Continue en la ventana sin punto se detiene con Please choose a Blue Express pickup point. en el cuadro, y la tienda lo vuelve a comprobar. OpenCart 4 mantiene un solo pedido para la compra y lo actualiza en cada confirmación; el punto de recogida del pedido se actualiza con él, y se elimina cuando el pedido cambia a otro método de envío.

Cuando se realiza el pedido, el punto se guarda en el pedido con su código de agencia de Blue Express, nombre, dirección y región. También se añade al método de envío del pedido después del nombre de la opción de recogida, por ejemplo Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, para que el cliente lo vea en los correos de pedido y en las páginas de pedidos de su cuenta.

En la página de pedido del administrador (Sales > Orders, View), el punto aparece en el panel Blue Express pickup point con su código y región. Si el pedido no tiene punto, el panel muestra Not chosen. Haz clic en Edit para elegir otro punto con Choose on the Blue Express map o para introducir a mano el Agency code, el Name y la Address, y luego haz clic en Save pickup point. El texto del método de envío del pedido también se actualiza, y el cambio se añade al historial del pedido sin notificar al cliente (Blue Express pickup point changed: código antiguo -> código nuevo). Cambiar el punto solo requiere el permiso de modificación de pedidos, no el acceso a los ajustes de la extensión. Los pedidos existentes conservan los datos de su punto de recogida.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Blue Express es el primer bloque de Extensions > Extensions > Shipping > VibeFox Blue Express > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, 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 están la línea Product: opencart-shipping-blue-express y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el 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 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 después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un 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. 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 y no se calcula ninguna tarifa. Un administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), así que puedes configurar y probar la extensión antes de comprar una clave. Después de abrir la página Edit una vez, 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 requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del administrador: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No se necesita ningún cron job. Desinstalar la extensión siempre elimina la clave de licencia y su estado.

Solución de problemas

Blue Express no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable/Disable (o Pickup point option) está activado. Lee las advertencias de la parte superior de la página de la extensión. Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso, el Minimum order subtotal y que Fixed prices tenga una línea para el país si usas precios fijos o la alternativa. Comprueba que los productos tienen Requires Shipping en Yes.

Las tarifas en tiempo real no aparecen: con Blue Express API only las opciones se ocultan cuando no hay tarifa. Activa Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Motivos habituales: no hay clave de API, la moneda de la tienda no es CLP sin tipo de cambio, falta la región o la comuna en la dirección, una comuna no reconocida por Blue Express, o 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 solucionas el problema.

Las direcciones chilenas no tienen región: la página muestra una advertencia sobre regiones que faltan. Haz clic en Add Chilean regions en la página de la extensión. Los clientes cuyas direcciones se guardaron sin región deben editar la dirección y elegir la región.

El impuesto se añade sobre el precio de Blue Express: los precios de Blue Express incluyen IVA. Pon Tax class en None (no tax on shipping).

El mapa no se abre: el mapa se carga desde widget-pudo.blue.cl en el navegador del cliente, así que esta dirección debe ser accesible y no estar bloqueada en tu sitio.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas y los datos de comunas en caché.

La página dice "Warning: You do not have permission to modify VibeFox Blue Express!": tu grupo de usuarios administradores puede que solo tenga permiso para ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_blue_express (OpenCart 3) o extension/vfd_blue_express/shipping/vfd_blue_express (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: las direcciones de la API y del mapa de Blue Express se pueden sustituir con los ajustes vfd_blex_api_url y vfd_blex_widget_url (para pruebas); no tienen campos 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 Blue Express. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre restablece el estado del método, Sort order, Tax class y Geo zone. Las tarifas en caché se eliminan siempre. Si Remove data on uninstall está activado, también se borran los ajustes de Blue Express y el registro. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensión. Los puntos de recogida guardados en pedidos nunca se eliminan, y el texto del método de envío de los pedidos existentes conserva el punto de recogida.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Blue Express en la lista de extensiones instaladas, y luego en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Blue Express es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Blue Express.