VibeFox Frenet 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 Frenet (solo para cotizaciones en directo): crea una cuenta gratuita en el panel de Frenet (painel.frenet.com.br), activa los transportistas que uses y copia tu token de API. Si solo usas precios fijos, no necesitas una cuenta de Frenet.
Productos: rellena el peso y las dimensiones para obtener precios exactos. Los productos sin ellos se cotizan como 0,3 kg y 16 × 11 × 2 cm (la caja mínima de Correios).
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_frenet-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_frenet.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_frenet-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, también 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 Frenet 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 del bloque de licencia de la parte superior de la página Edit y haz clic en Activate (véase Clave de licencia).
5. Pega el token de API e introduce el CEP de origen. Si tu moneda predeterminada no es BRL, introduce el tipo de cambio a BRL. Opcionalmente, añade precios fijos y un coste de reserva. Activa Enable Frenet y haz clic en Save.
OpenCart 4
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_frenet.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 Frenet, haz clic en Install (el botón verde +) y después 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 iguales en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable Frenet y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Frenet que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. Cada guardado también borra las cotizaciones de Frenet en caché. Los campos de precio aceptan tanto el punto como la coma como separador decimal. Si un valor es incorrecto, no se guarda nada y la página muestra el motivo, por ejemplo Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. o "…" must not be negative. También se rechazan un BRL exchange rate de 0 o menos y un Minimum weight (kg) superior a Maximum weight (kg). Solo los usuarios administradores con el permiso de modificación de esta extensión pueden guardar los ajustes.
En la parte superior de la página, y de nuevo tras cada guardado, la extensión muestra advertencias: falta el token de API (se usan solo precios fijos, o el método nunca se muestra si tampoco hay precios fijos), falta el CEP de origen, el CEP de origen no tiene 8 dígitos o la moneda predeterminada no es BRL y no hay tipo de cambio. También avisa si tu tienda no tiene una clase de peso con la unidad kg ni una clase de longitud con la unidad cm. Los pesos y las dimensiones de los productos se convierten entonces según el nombre de la unidad de su clase, y las unidades desconocidas se leen como kg o cm. Revisa System > Localisation > Weight Classes y Length Classes.
General
Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica en Conditions, o usar Ignore shipping zones. El precio siempre procede de esta extensión.
Enable Frenet: muestra u oculta Frenet en la finalización de compra. Predeterminado: desactivado.
Method title: el nombre del método de envío que ve el cliente en el carrito y en la finalización de compra. Predeterminado: Frenet. Obligatorio, 64 caracteres como máximo, sin los caracteres < > ; = # { }.
Sort order: la posición de Frenet entre los métodos de envío en la finalización de compra. Un número entero.
Cotizaciones en directo de Frenet
Frenet compara los transportistas activados en tu cuenta de Frenet (Correios, Jadlog, Loggi y otros) y devuelve sus precios para el carrito. Las cotizaciones en directo solo se piden para direcciones en Brasil con un CEP completo de 8 dígitos. La sección tiene un enlace al panel de Frenet.
API token: tu token de API de Frenet, del panel de Frenet. Déjalo vacío para usar solo precios fijos. Tras guardar, el campo queda vacío y muestra A token is saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. Para borrar el token guardado, marca Remove the saved token y guarda.
Origin CEP: el código postal (CEP) desde el que se envían los paquetes, por ejemplo 01001-000. OpenCart no tiene código postal de tienda, así que las cotizaciones en directo necesitan este campo. Un CEP sin 8 dígitos se guarda tal como lo escribiste, y la página muestra Frenet: the origin CEP must have 8 digits.
Service to offer: Cheapest service (predeterminado) o Fastest service. Frenet devuelve varios servicios y el método muestra un solo precio. El transportista, el servicio y el plazo de entrega elegidos se guardan con el pedido.
BRL exchange rate: Frenet cotiza en reales brasileños. Si tu moneda predeterminada no es BRL, introduce cuánto equivale 1 BRL en tu moneda predeterminada, por ejemplo 0.16. El precio cotizado y el valor declarado del pedido se convierten con este tipo. Sin él no se usan las cotizaciones en directo. Cuando tu moneda predeterminada es BRL, el campo indica que los precios de Frenet se usan tal cual.
Precios fijos
Se usan cuando no hay token de API, para los países que Frenet no atiende y siempre que Frenet no devuelva ningún precio (API caída, CEP no atendido).
Price per country: una tabla con las columnas Country, Price, XS, S, M, L y XL, con precios en tu moneda predeterminada, sin impuestos. Haz clic en Add country para añadir una fila. Las columnas de tamaño dependen del peso del carrito: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg, XL por encima de 5 kg. Se usa Price cuando la columna de tamaño está vacía. Un Price de 0 significa envío gratuito para ese país. Usa * Default (all other countries) para todos los países sin fila propia. Las filas sin ningún precio se eliminan al guardar.
Fallback cost: se usa cuando ni Frenet ni la tabla dan un precio. Déjalo vacío para ocultar el método.
Fixed price applies: Per order (predeterminado) cobra el precio una sola vez. Per item (price × quantity) lo multiplica por el número de artículos. Esto solo se aplica a los precios fijos y al coste de reserva. Las cotizaciones de Frenet ya cubren todo el carrito.
Condiciones
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite.
Maximum weight (kg): oculta el método por encima de este peso del carrito. Predeterminado: 30 (también se usa cuando el campo está vacío). 0 significa sin límite. No puede ser inferior a Minimum weight (kg).
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) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal (después del cupón, antes de impuestos) a partir del cual el envío es gratuito. Déjalo vacío para no dar nunca envío gratuito.
Tax class: la clase de impuesto que se añade al coste de envío, o No tax. Los precios de Frenet son precios finales del transportista. Elige No tax si OpenCart no debe añadir impuestos sobre ellos.
Geo zone: ofrece Frenet solo para direcciones de esta zona geográfica. All zones significa sin límite. No se usa con Ignore shipping zones. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Disponibilidad sin zonas de envío
Normalmente el método se ofrece en la zona geográfica elegida en Conditions (en todas las zonas si no se elige ninguna).
Ignore shipping zones: ofrece Frenet para los países indicados a continuación, sea cual sea la zona geográfica que coincida. La Geo zone de Conditions no se comprueba en ese caso.
Countries: los países de destino para ese modo, elegidos entre los países activos de tu tienda. Déjalo vacío para usar todos los países a los que envías. Solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra cada solicitud y respuesta de cotización en storage/logs/vfd_frn_debug.log.php (en OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API siempre se registran. El token nunca se registra y el CEP del cliente se acorta. Desactívalo cuando termines. Cuando el archivo llega a 5 MB, se traslada a vfd_frn_debug.old.log.php y se inicia un registro nuevo.
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 todos los ajustes de Frenet y el registro. Si está desactivado, se conserva todo para una reinstalación. Las cotizaciones en caché siempre se eliminan. Los servicios de Frenet guardados con los pedidos forman parte del historial de pedidos y se conservan.
Importar / Exportar
Exportar: haz clic en Download JSON para guardar los ajustes en un archivo JSON. El token de API no se exporta.
Importar: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. El token de API guardado 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 Frenet. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección queda fuera de ella, Frenet no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no se incluyen en el importe del pedido. Después, la extensión comprueba la lista de países (si Ignore shipping zones está activado), el peso del carrito y el 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. Si se aplica envío gratuito, el precio es 0 y no se envía ninguna solicitud a Frenet.
Para una dirección en Brasil con un CEP completo de 8 dígitos, y cuando están definidos el token de API y el CEP de origen, la extensión envía a Frenet los CEP de origen y de destino, cada artículo del carrito (peso en kg, dimensiones en cm, cantidad, el Model del producto y sus categorías), el valor del pedido en BRL y el código de cupón del carrito. No se hace ninguna solicitud mientras el CEP esté incompleto. Frenet devuelve los servicios de tus transportistas activados. Los servicios con error o sin precio se omiten. La extensión elige el servicio más barato o el más rápido y convierte el precio a tu moneda predeterminada. El precio se redondea a los decimales de tu moneda predeterminada y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
Cada respuesta se guarda en caché durante 1 hora para el mismo carrito y la misma dirección. Una solicitud fallida, o un CEP que ningún transportista activado atiende, se recuerda durante 10 minutos. El tiempo de espera de la API es de 10 segundos. En estos casos el cliente no ve ningún error: se usa el precio fijo o el coste de reserva, o el método se oculta si no hay ninguno. El motivo se escribe en el registro. Para direcciones fuera de Brasil solo se usan precios fijos.
En OpenCart 4 el cliente hace clic en Choose en el bloque de método de envío de la página de finalización de compra y elige Frenet en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
La extensión solo calcula tarifas. No crea envíos, no imprime etiquetas ni hace seguimiento de paquetes. Muestra un servicio de Frenet por carrito, no varios, y no tiene puntos de recogida ni taquillas. Frenet cotiza solo dentro de Brasil; usa los precios fijos para otros países.
Pedidos
Cuando se realiza un pedido con Frenet, la extensión guarda cómo se calculó su precio de envío: exactamente la opción que el cliente vio en el paso de envío, sin una nueva solicitud a Frenet. La página del pedido en Sales > Orders muestra entonces un bloque de Frenet con estas líneas:
Carrier: el transportista y el servicio de Frenet, por ejemplo un servicio de Correios o de Jadlog. Se muestra en las cotizaciones en directo.
Delivery time: el plazo de entrega en días hábiles devuelto por Frenet. Se muestra en las cotizaciones en directo.
Price source: Live Frenet quote, Fixed price (price per country), Fallback cost o Free shipping.
En OpenCart 4 el bloque se muestra encima de History. OpenCart 4 actualiza el mismo pedido cuando el cliente lo confirma de nuevo: los datos de Frenet guardados también se actualizan y, si el cliente ha elegido otro método de envío, los datos de Frenet del pedido se eliminan.
El bloque también se muestra cuando la extensión está desactivada. Estos datos se conservan al desinstalar la extensión, también con Remove data on uninstall.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Frenet es el primero de la página Extensions > Extensions > Shipping > VibeFox Frenet > Edit, por 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 eliminar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-frenet 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 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 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 contactar con el servidor de licencias, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un solo 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. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Frenet no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador con sesión iniciada 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. 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. Después de abrir una vez la página Edit, 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 renovación. El estado se vuelve a comprobar automáticamente al abrir 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 por semana. No se necesita ningún cron job. Al desinstalar la extensión se eliminan siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Frenet no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Frenet esté activado. Revisa la Geo zone, o Ignore shipping zones y Countries, los límites de peso y el Minimum order amount. Revisa las advertencias en la parte superior de la página de la extensión. Motivos habituales: el cliente aún no ha introducido un CEP completo de 8 dígitos y no hay precios fijos, o Frenet no devolvió ningún servicio para la ruta y no hay precio fijo. Comprueba que los productos tengan Requires Shipping en Yes.
Las cotizaciones en directo no aparecen: activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Muestra el motivo: falta el CEP de origen, no hay tipo de cambio a BRL, el CEP del cliente está incompleto, se supera un límite de peso o de importe, o aparecen los mensajes de los servicios omitidos.
El registro indica que el token de API fue rechazado (HTTP 401 o 403): copia de nuevo el token desde el panel de Frenet y pégalo en API token.
El registro indica que Frenet no devolvió servicios: activa al menos un transportista en el panel de Frenet.
Mi tienda vende en euros o dólares: Frenet responde en BRL. Introduce el BRL exchange rate (cuánto equivale 1 BRL en tu moneda predeterminada).
Se cobra impuesto sobre el precio de Frenet: los precios de Frenet son precios finales del transportista. Pon Tax class en No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las cotizaciones de Frenet en caché.
La página dice "Warning: You do not have permission to modify VibeFox Frenet!": es posible que el grupo de usuarios de tu administrador solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_frenet (OpenCart 3) o extension/vfd_frenet/shipping/vfd_frenet (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de cotización de Frenet puede sustituirse con el ajuste vfd_frn_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 Frenet. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Frenet, Sort order, Tax class y Geo zone. Las cotizaciones en caché siempre se eliminan. El evento de OpenCart de la extensión también se elimina (en OpenCart 4, además, los eventos que guardan los datos de Frenet de los pedidos nuevos), de modo que el bloque de Frenet ya no se muestra en la página del pedido. Los datos de Frenet guardados con los pedidos se conservan y se muestran de nuevo tras una reinstalación. Si Remove data on uninstall está activado, los ajustes de Frenet y el registro de depuración también se borran. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al instalar la extensión de nuevo. 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 después de la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox Frenet en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Frenet es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Frenet ni cuenta con su respaldo.