VibeFox 99Minutos for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posterior (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Clave de API de 99minutos (solo para la comprobación de cobertura): consíguela con tu gestor de cuenta de 99minutos o en el portal para desarrolladores de 99minutos (developers.99minutos.com). Las claves de sandbox y de producción son distintas. Si solo usas la matriz de precios, no necesitas clave de API.
Países: 99minutos entrega en México, Colombia, Chile y Perú. Los países a los que envías deben estar activados en System > Localisation > Countries.
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_99minutos-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_99minutos.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_99minutos-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 99Minutos 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 el campo License key del bloque de licencia, en la parte superior de la página Edit, y haz clic en Activate (ver Clave de licencia).
5. Rellena la Price matrix (al menos una fila, por ejemplo "* Default") y, opcionalmente, la clave de API y el modo de comprobación de cobertura (ver Configuración). Activa Enable 99Minutos y haz clic en Save.
OpenCart 4
1. En el administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_99minutos.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 de 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 99Minutos, 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 los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable 99Minutos y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de 99minutos que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra los resultados de cobertura en caché. Si un valor es incorrecto, no se guarda nada y la página muestra el motivo, por ejemplo Enter a method title (1 to 64 characters)., un mensaje de que un campo debe ser un número igual o mayor que 0, o de que Min weight (kg) no puede ser mayor que Max weight (kg). Tras guardar, los avisos que aparecen sobre los ajustes indican cuándo el método no puede funcionar tal como está configurado: la matriz de precios está vacía, se ha elegido un modo de comprobación de cobertura sin clave de API, la matriz tiene filas para países que 99minutos no atiende, o la tienda no tiene la clase de peso "kg" y su unidad de peso no la reconoce la extensión (en ese caso los pesos se toman como kilogramos). Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
General
Los ajustes se aplican a todas las zonas geográficas. 99Minutos solo se ofrece para México, Colombia, Chile y Perú como países de destino.
Enable 99Minutos: muestra u oculta 99Minutos en el proceso de compra. Por defecto: desactivado.
Method title: el nombre del método de envío que el cliente ve en el carrito y en el proceso de compra. Por defecto: 99Minutos. Obligatorio, hasta 64 caracteres.
Tax class: la clase de impuesto del coste de envío, o No tax (por defecto). Con una clase de impuesto, OpenCart añade el impuesto al precio de la matriz.
Sort order: la posición de 99Minutos entre los métodos de envío del proceso de compra. Un número entero.
API de 99minutos (comprobación de cobertura) (opcional)
La API solo se usa para comprobar si 99minutos entrega en el código postal del cliente. El precio siempre sale de la matriz.
Coverage check: si el código postal se comprueba y cómo.
Con una comprobación de cobertura, el método aparece solo después de que el cliente introduzca un código postal. Los resultados se guardan en caché: con cobertura durante 6 horas, sin cobertura durante 30 minutos, error de API durante 5 minutos, pero nunca más que la duración de la caché de OpenCart (1 hora por defecto). Solo se envía a 99minutos el código postal, en mayúsculas y con letras y números únicamente.
API key: tu clave de API de 99minutos, enviada como token Bearer al endpoint de cobertura de 99minutos. Es obligatoria cuando la comprobación de cobertura está activada. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla. La clave se guarda tal como la escribes; solo se quitan los espacios que haya alrededor.
Remove the saved API key: aparece solo cuando hay una clave guardada. Actívalo y haz clic en Save para borrar la clave.
Environment: Sandbox (test) (por defecto) o Production. Sandbox y producción usan claves de API distintas, así que elige el entorno que corresponde a tu clave.
Tarifas
Los precios están en la moneda predeterminada de tu tienda, sin impuestos, y se usan tal como los introduces. El precio final se muestra en la moneda del cliente.
Price matrix: una tabla de países de destino y precios. Haz clic en Add country para añadir una fila y en el botón × para eliminarla. Cada fila tiene un Country (* Default, México, Colombia, Chile o Perú), un Base price y precios para los tamaños XS (hasta 1 kg), S (hasta 2 kg), M (hasta 3 kg), L (hasta 5 kg) y XL (más de 5 kg). Un precio de tamaño vacío o 0 usa el Base price. La fila * Default se aplica a los países que no tienen fila propia. Si un país tiene varias filas, se usa la primera. Se aceptan tanto el punto como la coma como separador decimal; los precios vacíos, no válidos o negativos se guardan como 0. Hasta que la matriz tenga al menos una fila, el método no se muestra en el proceso de compra.
Calculation: Per order — size by the total cart weight (por defecto) aplica un único precio según el tamaño del paquete de todo el carrito. Per item — each unit priced by its own weight calcula el precio de cada unidad según el tamaño de su propio peso y los suma.
Free shipping: activa el envío gratuito a partir de un importe de pedido.
Free shipping from: el subtotal de los productos que requieren envío (después del cupón y antes de impuestos) a partir del cual la tarifa es 0. Se usa solo si Free shipping está activado.
Restricciones
Min weight (kg): oculta el método si el carrito pesa menos. 0 significa sin límite (por defecto). No puede ser mayor que Max weight (kg). Los pesos de los productos se convierten desde su clase de peso.
Max weight (kg): oculta el método si el carrito pesa más. Por defecto: 25. 0 significa sin límite; un campo vacío significa 25 kg.
Minimum subtotal: muestra el método solo si el subtotal de los productos que requieren envío (después del cupón y antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Geo zone: ofrece 99Minutos solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Restrict countries: ofrece el método solo para los países indicados abajo. Es un filtro adicional sobre Geo zone.
Countries: una lista de los países de 99minutos (México, Colombia, Chile, Perú). Se usa solo cuando Restrict countries está activado. Déjala vacía para permitir todos los países de 99minutos.
Avanzado
Debug log: registra los cálculos de tarifas en storage/logs/vfd_99m_debug.log.php. El archivo no se puede leer desde la web. Los errores de la API se registran aunque esta opción esté desactivada. Las claves de API y los nombres y direcciones de los clientes nunca se registran. Desactiva el registro cuando termines. Cuando el archivo alcanza 5 MB, se mueve a vfd_99m_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 99minutos, la caché de cobertura y el registro. Si está desactivado (por defecto), se conservan para una reinstalación. Los pedidos se conservan en cualquier caso.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes en un 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 el proceso de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de 99Minutos. Si hay una Geo zone y la dirección está fuera de ella, 99Minutos 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. El método se ofrece solo cuando el país de entrega es México, Colombia, Chile o Perú (y está en la lista Countries si Restrict countries está activado). Después, la extensión comprueba los límites de peso y el Minimum subtotal. El importe del pedido es el precio de los productos que requieren envío, después del descuento del cupón y antes de impuestos. Las tarjetas regalo, los puntos de fidelidad y el crédito de la tienda no se tienen en cuenta.
Si hay activada una comprobación de cobertura, la extensión consulta a la API de 99minutos si el código postal tiene cobertura. El tiempo de espera de la petición es de 10 segundos y la respuesta se guarda en caché, así que el mismo código postal no genera una nueva petición. Los errores de la API nunca se muestran al cliente: en el modo Strict el método se oculta, y en el modo Soft se usa el precio de la matriz. El envío gratuito no omite la comprobación de cobertura.
El precio se toma de la fila de la matriz del país de entrega, o de la fila * Default. Si no existe ninguna de las dos, el método se oculta. Si Free shipping está activado y el importe del pedido alcanza Free shipping from, la tarifa es 0. El precio se calcula en 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.
La extensión no obtiene tarifas en tiempo real de 99minutos: los precios siempre salen de tu matriz. No crea envíos ni pedidos en 99minutos, no imprime guías, no rastrea paquetes, no ofrece puntos de recogida Punto99 ni gestiona el pago contra reembolso. 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 OpenCart. Crea los envíos en tu cuenta de 99minutos como de costumbre.
En OpenCart 4 el cliente hace clic en Choose en el bloque del método de envío de la página de compra y elige 99Minutos en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox 99Minutos es el primer bloque de la página Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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-99minutos 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 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 es aceptada, 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 que cambie 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 solo dominio. Gestionas tus licencias y dominios en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío 99Minutos no se muestra a los clientes en el proceso de compra y no se calcula ninguna tarifa. Un usuario 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), 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 una vez la página Edit, aparece un recordatorio en el Dashboard del panel de administración. 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 panel de administración o la página Edit: 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 ninguna tarea cron. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.
Solución de problemas
99Minutos no aparece en el proceso de compra: comprueba que la licencia esté activa y que Enable 99Minutos esté activado. El país de entrega debe ser México, Colombia, Chile o Perú y estar activado en System > Localisation > Countries. Revisa Geo zone y Restrict countries. Comprueba que la Price matrix tenga una fila para ese país o una fila * Default, y revisa los límites de peso y el Minimum subtotal. Comprueba que los productos tengan Requires Shipping en Yes. Los avisos que aparecen tras Save indican los ajustes que ocultan el método.
El método aparece solo después de introducir un código postal: es lo esperado con una comprobación de cobertura. En el modo Strict aparece solo cuando la API confirma la cobertura.
El método siempre está oculto en el modo Strict: activa Debug log, recarga el proceso de compra y mira el campo Log en la página de la extensión. Un error HTTP 401 o 403 significa que la API ha rechazado la clave: revisa la clave y que Environment coincida con ella (las claves de sandbox y de producción son distintas). Usa el modo Soft si los clientes deben seguir viendo el precio de la matriz mientras la API no está disponible.
El precio no es el que esperabas: revisa Calculation (por pedido o por artículo) y los pesos y clases de peso de los productos. Un precio de tamaño vacío o 0 usa el Base price. Con una Tax class, el impuesto se suma al precio de la matriz.
Los resultados de cobertura parecen desactualizados tras un cambio: haz clic en Save en la página de la extensión. Así se borran los resultados de cobertura en caché.
La página dice "Warning: You do not have permission to modify VibeFox 99Minutos!": tu grupo de usuarios puede que solo tenga permiso para ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_99minutos (OpenCart 3) o extension/vfd_99minutos/shipping/vfd_99minutos (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de 99minutos puede reemplazarse con el ajuste vfd_99m_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 99Minutos. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart restablece siempre Enable 99Minutos, Sort order, Tax class y Geo zone. Los resultados de cobertura en caché se eliminan siempre. Si Remove data on uninstall está activado, también se borran los ajustes de 99minutos y el registro de depuración. Si está desactivado, se conservan los demás ajustes 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 desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox 99Minutos en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.
99minutos es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por 99minutos.