VibeFox Loggi 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 Loggi (solo para precios en tiempo real): el precio en tiempo real usa la API GraphQL de Loggi con una clave de API que Loggi emite para cuentas de empresa. Pídela a tu gestor de cuenta de Loggi o al soporte de integraciones de Loggi (integracoes@loggi.com); consulta también la documentación de la API de Loggi en docs.api.loggi.com. Necesitas tres valores: el correo electrónico de tu cuenta de Loggi, la clave de API y el ID numérico de tu tienda. Si tu cuenta de Loggi solo tiene credenciales para la API de la plataforma REST más reciente de Loggi (ID de cliente y secreto), el precio en tiempo real no está disponible y se usan los precios fijos. Si solo usas precios fijos, no necesitas una cuenta de Loggi.
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_loggi-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_loggi.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 administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_loggi-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, 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 Loggi 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 (véase Clave de licencia).
5. Introduce el correo electrónico de la API de Loggi, la clave de API, el ID de tienda y la dirección de recogida y, si la moneda predeterminada de tu tienda no es BRL, el tipo de cambio a BRL. Añade precios fijos como red de seguridad (véase Configuración), activa Enable Loggi y haz clic en Save.
OpenCart 4
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_loggi.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 Loggi, 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 pequeña tabla para los precios de Loggi en caché. El método está desactivado hasta que actives Enable Loggi y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Loggi que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Loggi > Edit. Las secciones aparecen a la izquierda. Se aplican a todas las zonas geográficas. Un botón Save en la parte inferior guarda toda la página sin recargarla. Cada guardado también borra los precios de Loggi en caché. Si un valor no es válido, por ejemplo un número negativo, un correo electrónico no válido o un ID de tienda que no es un número, la página muestra un error y no se guarda nada. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
Las advertencias sobre los ajustes (que se muestran de nuevo tras cada guardado) señalan una configuración incompleta: sin credenciales de API (solo se usan precios fijos), sin credenciales de API y sin precios fijos (el método nunca se muestra), sin dirección de recogida o sin tipo de cambio a BRL. Otra advertencia aparece cuando la tienda no tiene una clase de peso con la unidad kg o una clase de longitud con la unidad cm, y la unidad de la clase predeterminada no se reconoce. En ese caso, los pesos de los productos se cuentan como kg y las dimensiones como cm. Añade las clases en System > Localisation > Weight Classes y Length Classes.
General
Enable Loggi: muestra u oculta Loggi en la compra. Por defecto: desactivado.
Method title: el nombre del método de envío que el cliente ve en el carrito y en la compra. Por defecto: Loggi. Obligatorio, 64 caracteres como máximo, sin los caracteres < > ; = # { }.
Sort order: la posición de Loggi entre los métodos de envío en la compra. Un número entero.
API de Loggi (precio en tiempo real) (deja las credenciales vacías para usar solo precios fijos)
API e-mail: el correo electrónico de tu cuenta de Loggi. La clave de API le pertenece. Debe ser una dirección de correo válida. Borrarlo también borra la clave de API guardada.
API key: tu clave de API de Loggi. Solo se envía a Loggi y nunca se registra. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it; clear the API e-mail to remove it. Escribe un valor nuevo solo para cambiarlo. Si cambias API e-mail, introduce también la clave de API del nuevo correo; de lo contrario, la página muestra un error y no se guarda nada.
Shop ID: el ID numérico (pk) de tu tienda en el panel de Loggi, por ejemplo 12345. Cualquier otro valor se rechaza con un error.
Staging: usa el entorno de pruebas (staging) de Loggi con credenciales de prueba. El entorno de pruebas y el de producción tienen cuentas y claves distintas. Por defecto: desactivado.
Pickup address: dónde recoge Loggi los paquetes, en una sola línea: calle y número, barrio, ciudad, estado y CEP, por ejemplo Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Obligatoria para los precios en tiempo real: la dirección de la tienda en OpenCart es texto libre y nunca se usa en su lugar. Sin dirección de recogida, Loggi no puede estimar y solo se usan precios fijos.
BRL exchange rate: los precios de Loggi están en reales brasileños. Si la moneda predeterminada de tu tienda es BRL, este campo no es necesario y la página lo indica. En caso contrario, introduce cuánto vale 1 BRL en la moneda de tu tienda, por ejemplo 0.16. Sin él no se usan los precios en tiempo real. Solo se acepta un número positivo. Se aceptan tanto el punto como la coma como separador decimal.
Precios fijos (en la moneda predeterminada de tu tienda, sin impuestos)
Los precios fijos se usan cuando la API de Loggi no está configurada, para destinos fuera de Brasil o sin un CEP completo, y siempre que Loggi no devuelva precio (API caída, clave rechazada, dirección fuera de cobertura).
Price table: una fila por país de destino. Haz clic en Add country para añadir una fila y en el botón de eliminar para borrar una. Elige * All other countries para todos los países sin 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 0) usa el precio base. Un precio base de 0 significa envío gratuito. Se aceptan tanto "9.99" como "9,99". Las filas vacías y una segunda fila para el mismo país se eliminan al guardar.
Price for countries not in the table: se usa cuando no hay precio en tiempo real de Loggi y la tabla no tiene fila para el país de destino (y no hay fila *). Déjalo vacío para ocultar el método en ese caso.
Fixed price applies: la forma en que se calculan los precios fijos. Un precio en tiempo real de Loggi ya cubre todo el carrito y nunca se multiplica.
Condiciones
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (por defecto).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Por defecto: 30. 0 significa sin límite. Minimum weight no puede ser mayor que Maximum weight.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, 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, antes de impuestos) a partir del cual el envío de Loggi es gratuito. Déjalo vacío si no hay envío gratuito.
Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Elige No tax si tus precios y el precio de Loggi ya incluyen impuestos.
Geo zone: ofrece Loggi solo para direcciones en esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. La zona geográfica no se comprueba cuando Ignore shipping zones está activado.
Para los límites de peso y las columnas de peso, un producto sin peso cuenta como 0 kg.
Países
OpenCart no tiene zonas de transportista: la Geo zone limita el método a las direcciones de una zona geográfica. En su lugar, puedes activar Ignore shipping zones y elegir una lista de países.
Ignore shipping zones: ofrece Loggi para los países indicados abajo, sea cual sea la Geo zone. La zona geográfica no se comprueba en este modo. Por defecto: desactivado.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países activados en la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de tarifas y las solicitudes a Loggi en storage/logs/vfd_lggi_debug.log.php (en OpenCart 4, system/storage/logs/vfd_lggi_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. La clave de API y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_lggi_debug.old.log.php y se inicia un registro nuevo.
Log: muestra el tamaño y las últimas entradas 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 Loggi y el registro. Si está desactivado (por defecto), los ajustes se conservan para una reinstalación. Los precios en caché siempre se eliminan.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de API no se exporta.
Import: pega un 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.
Funcionamiento en la compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de Loggi. Si hay una Geo zone definida, Ignore shipping zones está desactivado y la dirección está fuera de la zona geográfica, Loggi no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso y no se incluyen en el importe del pedido. La extensión comprueba entonces las condiciones: países permitidos (con Ignore shipping zones), peso del carrito e 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. Las tarjetas regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si corresponde envío gratuito, el precio es 0 y no se envía ninguna solicitud a Loggi.
En una dirección de Brasil con un CEP completo de 8 dígitos, la extensión construye paquetes de Loggi: cada artículo se gira para que su lado más corto sea la altura, y los artículos se apilan en un paquete mientras no supere 55 × 55 × 55 cm y 20 kg. Los productos sin peso o dimensiones cuentan como 1 cm por lado, y cada paquete pesa al menos 100 g. Loggi acepta 2 paquetes por estimación, así que los carritos más grandes se envían en varias solicitudes y los totales se suman. La extensión envía a Loggi tu ID de tienda, la dirección de recogida, la dirección de entrega (calle, ciudad, estado y CEP) y los paquetes, y convierte el total de Loggi de BRL a la moneda predeterminada de tu tienda. El precio se redondea a los decimales de esa moneda y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
Cada precio de Loggi se guarda en caché durante 1 hora por carrito, dirección, cuenta y entorno, para que el mismo carrito no genere una nueva solicitud. Una estimación fallida se guarda en caché durante 10 minutos. Si no se puede contactar con Loggi, las solicitudes se pausan durante 2 minutos, para que la compra no espere a Loggi en cada actualización. El tiempo de espera de la API es de 10 segundos.
Los precios fijos se usan en su lugar cuando la API no está configurada, la dirección está fuera de Brasil o aún no tiene un CEP completo, falta el tipo de cambio a BRL, no hay dirección de recogida, un producto es más grande que un paquete de Loggi, el carrito necesita más de 10 paquetes, o Loggi devuelve un error, un paquete rechazado, una dirección fuera de cobertura o un total de cero. Si tampoco hay precio fijo, el método se oculta. El cliente nunca ve un error de la API. El motivo se escribe en el registro de depuración.
En OpenCart 4 el cliente hace clic en Choose en el bloque de método de envío de la página de compra y elige Loggi en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
La extensión solo calcula precios. No crea pedidos ni envíos de Loggi, no imprime etiquetas, no rastrea paquetes, no muestra el plazo de entrega en la compra ni ofrece puntos de recogida o taquillas. No añade nada a los pedidos: el pedido muestra el nombre del método y el coste de envío como cualquier otro método de envío de OpenCart. Crea los envíos en el panel de Loggi. Loggi entrega solo dentro de Brasil. Usa los precios fijos para el resto de países.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Loggi es el primer bloque en Extensions > Extensions > Shipping > VibeFox Loggi > Edit, por encima de los ajustes. Introduce 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-loggi y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify de 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 y 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, el método de envío de Loggi no se muestra a los clientes en la 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 para todos. Tras 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 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 a la semana. No se necesita ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Loggi no aparece en la compra: comprueba que la licencia está activa y que Enable Loggi está activado. Revisa Geo zone, Ignore shipping zones y Countries, las advertencias de la parte superior de la página de la extensión, los límites de peso y Minimum order amount. Si el cliente aún no ha introducido un CEP completo o Loggi no devuelve precio, el método necesita un precio fijo: una fila para el país, una fila * o Price for countries not in the table. Comprueba que los productos tengan Requires Shipping en Yes.
Solo se muestran precios fijos: mira el campo Log en la página de la extensión. Los errores siempre se registran. Activa Debug log para ver cada paso y recarga la compra. Motivos habituales: falta el correo de la API, la clave o el ID de tienda, no hay dirección de recogida, no hay BRL exchange rate para una moneda de tienda distinta de BRL, aún no hay un CEP de 8 dígitos completo, un producto es mayor de 55 cm o pesa más de 20 kg, o la dirección está fuera de cobertura de Loggi.
HTTP 401 o 403 en el registro: Loggi rechazó el correo o la clave de la API. Compruébalos con Loggi y verifica que Staging coincide con las credenciales: las claves de pruebas y de producción son distintas.
Mi tienda vende en euros o dólares: Loggi responde en BRL. Introduce el BRL exchange rate (cuánto vale 1 BRL en la moneda predeterminada de tu tienda). Los precios fijos siempre están en la moneda predeterminada de la tienda.
Los precios no son exactos: rellena el peso y las dimensiones de tus productos. Sin ellos, los productos cuentan como 1 cm por lado y cada paquete como mínimo 100 g.
Por artículo no multiplica el precio de Loggi: es intencionado. Un precio en tiempo real de Loggi cubre todo el carrito. Per item se aplica solo a los precios fijos.
Los precios parecen desactualizados tras un cambio: haz clic en Save en la página de la extensión. Esto borra los precios de Loggi en caché.
La página dice "Warning: You do not have permission to modify VibeFox Loggi!": tu grupo de usuarios de administración quizá solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_loggi (OpenCart 3) o extension/vfd_loggi/shipping/vfd_loggi (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de Loggi puede reemplazarse con el ajuste vfd_lggi_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 Loggi. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Loggi, Sort order, Tax class y Geo zone. Los precios de Loggi en caché (con su tabla) siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de Loggi y el registro de depuración también se borran. 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 Loggi en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Loggi es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por Loggi.