VibeFox Envioclick 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.
Cuenta de Envioclick (solo para tarifas en tiempo real): una cuenta de Envioclick en México o Colombia con acceso a la API. La clave de API está en tu cuenta de Envioclick, en Mi cuenta (arriba a la derecha) > Información del API. Si solo usas precios fijos, no necesitas una cuenta de Envioclick.
User-Agent (solo México): Envioclick México exige un valor de User-Agent en cada solicitud a la API. Pídeselo al soporte de Envioclick (soporte.tecnico@envioclick.com).
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_envioclick-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_envioclick.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_envioclick-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 Envioclick 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 (ver Clave de licencia).
5. Introduce la clave de API, elige el país de la API, introduce el User-Agent (México), el código postal de origen o el código DANE y la dirección de origen. Si la moneda predeterminada de tu tienda no es MXN ni COP, introduce el tipo de cambio. Opcionalmente, añade precios fijos por país y un coste de reserva. Activa Enable Envioclick y haz clic en Save.
OpenCart 4
1. En el administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_envioclick.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 Envioclick, 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 para 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 Envioclick y guardes. Si vuelves a instalar la extensión después de desinstalarla, se vuelven a usar los ajustes de Envioclick que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Envioclick > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda la página entera sin recargarla. Cada guardado también borra las cotizaciones de Envioclick en caché. Los campos numéricos aceptan tanto el punto como la coma como separador decimal. Solo los usuarios administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
La sección General muestra advertencias cuando las tarifas en tiempo real no pueden funcionar con los ajustes guardados: no hay tipo de cambio para una moneda de tienda distinta de MXN o COP, no hay User-Agent para México, no hay código postal o código DANE de origen, o no hay dirección de origen para Colombia. También avisa si la unidad de peso o de longitud de la tienda no se reconoce; en ese caso, añade una clase de peso con la unidad kg en System > Localisation > Weight Classes o una clase de longitud con la unidad cm en System > Localisation > Length Classes. Al guardar, la extensión comprueba que Method title tiene entre 1 y 64 caracteres, que los campos numéricos contienen números no negativos, que Currency conversion rate es mayor que 0, que Minimum weight (kg) no es mayor que Maximum weight (kg), que el código de origen tiene 5 dígitos para México o 8 dígitos (o el código de municipio de 5 dígitos) para Colombia, que cada fila de Price per country tiene un país válido y un precio, y que Sort order es un número entero. Si alguna comprobación falla, no se guarda nada y la página indica los errores.
General
El cliente ve una sola tarifa de Envioclick, la del transportista más barato o más rápido. Puedes limitar el método a una zona geográfica o a países en Availability.
Enable Envioclick: muestra u oculta Envioclick en la finalización de compra. Predeterminado: desactivado.
Method title: el nombre del método de envío que se muestra al cliente en el carrito y en la finalización de compra, de 64 caracteres como máximo. Predeterminado: Envioclick Shipping. Obligatorio.
Carrier in the title: añade al título el transportista de Envioclick y el plazo de entrega estimado de una tarifa en tiempo real, por ejemplo «Envioclick Shipping (Estafeta Express, 1 day)». OpenCart guarda este título con el pedido, así que también aparece en los correos del pedido y en las páginas de pedidos. El transportista se guarda en el pedido en cualquier caso. Predeterminado: activado.
Sort order: la posición de Envioclick entre los métodos de envío en la finalización de compra. Un número entero.
API de Envioclick (tarifas en tiempo real)
Opcional. Sin clave de API solo se usan los precios fijos. La sección enlaza con la documentación de la API de Envioclick para México y Colombia. Las tarifas en tiempo real solo se solicitan para destinos del país de la API. El envío a otros países usa los precios fijos.
API key: tu clave de API de Envioclick, de Mi cuenta > Información del API. Se envía en la cabecera «Authorization» y nunca se muestra a los clientes ni se escribe en el registro. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.
Remove the saved API key: actívalo y guarda para eliminar la clave guardada; entonces solo se usan los precios fijos. Una clave escrita en API key sustituye a la guardada. El interruptor se desactiva solo tras guardar.
API country: el país de tu cuenta de Envioclick.
User-Agent (Mexico): el valor que emite el soporte de Envioclick (soporte.tecnico@envioclick.com), por ejemplo EcUserAgent-2/123456. Obligatorio para México; sin él no se solicitan tarifas en tiempo real para México. Opcional para Colombia.
Carrier choice: Cheapest (predeterminado) o Fastest (then cheapest). Envioclick devuelve cotizaciones de varios transportistas y el cliente recibe una sola tarifa.
Branch pickup rates: tener también en cuenta las tarifas «Ocurre», en las que el cliente recoge el paquete en la sucursal del transportista. Si está desactivado, solo se usan las tarifas de entrega a domicilio. Nunca se usan servicios de pago contra reembolso (COD). Predeterminado: desactivado.
Currency conversion rate: Envioclick cotiza en MXN (México) o COP (Colombia). Si la moneda predeterminada de tu tienda es otra, introduce el valor de 1 MXN o 1 COP en la moneda de tu tienda, por ejemplo 0,05. El valor declarado del paquete se convierte de la misma forma. Déjalo vacío si la moneda de tu tienda es MXN o COP. Sin él, no se usan tarifas en tiempo real con otra moneda.
Envío desde
Se usa para las tarifas en tiempo real. OpenCart no tiene código postal, ciudad ni calle de la tienda, así que introdúcelos aquí.
Origin postcode / DANE code: México: el código postal de 5 dígitos. Colombia: el código DANE de 8 dígitos del municipio, por ejemplo 11001000 para Bogotá; un código de municipio de 5 dígitos (11001) se completa con 000.
Origin address: la calle y el número de la dirección de recogida. Obligatoria para Colombia, opcional para México.
Precios fijos
Se usan cuando no hay tarifa en tiempo real: sin clave de API, con un destino fuera del país de la API, o con un error de la API o sin transportista para la ruta.
Price per country: una lista de países y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add country para añadir una fila y en el botón × para quitar una. Elige * All other countries para un precio que se use en todos los países sin fila propia.
Fallback cost: se usa cuando no hay tarifa en tiempo real y ninguna fila de la tabla coincide. Déjalo vacío para ocultar el método en ese caso.
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 del carrito. Las tarifas en tiempo real de Envioclick siempre son por envío.
Condiciones
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (predeterminado).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Predeterminado: 25. 0 significa sin límite.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón y antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: envío gratuito cuando el subtotal de los productos que necesitan envío (después del cupón y antes de impuestos) alcanza este importe. En ese caso no se hace ninguna solicitud a la API. Déjalo vacío para no ofrecer nunca envío gratuito.
Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Las cotizaciones de Envioclick ya incluyen los impuestos de los transportistas, así que elige No tax para no cobrar impuestos dos veces sobre el envío.
Disponibilidad
Normalmente el método se ofrece para direcciones de la zona geográfica seleccionada, o en todas partes.
Geo zone: ofrece Envioclick 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 cuando Ignore shipping zones está activado.
Ignore shipping zones: no comprueba la zona geográfica; decide la lista de países de abajo. Predeterminado: desactivado.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de tarifas y los errores de la API en storage/logs/vfd_evc_debug.log.php (en OpenCart 4, system/storage/logs/vfd_evc_debug.log.php). El archivo no se puede leer desde la web. La clave de API y las direcciones de los clientes no se registran. Mientras el registro está desactivado no se escribe nada, ni siquiera los errores de la API. Desactívalo cuando termines. Cuando el archivo llega a 5 MB, se traslada a vfd_evc_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 Envioclick, las cotizaciones en caché y el registro. Si está desactivado (predeterminado), se conservan para una reinstalación. Los datos de Envioclick de los pedidos realizados siempre se conservan.
Importación / Exportación
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 previamente 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 Envioclick. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, no se ofrece Envioclick. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no añaden peso ni se incluyen en el importe del pedido. Después, la extensión comprueba las condiciones: los países de Ignore shipping zones, 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. Los certificados 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 Envioclick.
Si hay una clave de API definida y el destino está en el país de la API, la extensión pide cotizaciones a Envioclick. En México, la solicitud se hace cuando el cliente ha introducido un código postal de 5 dígitos. En Colombia, se hace cuando el municipio se reconoce a partir de un código DANE de 8 dígitos en el campo del código postal, o a partir del departamento (la región de la dirección de OpenCart) y la ciudad; un nombre de ciudad que sea único en Colombia se reconoce sin el departamento. Los acentos y las mayúsculas no importan. La extensión elige la cotización más barata o la más rápida que no sea pago contra reembolso y la convierte 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.
El paquete es siempre una sola caja: el peso total convertido a kg a partir de las clases de peso de los productos, y un tamaño de caja a partir de las dimensiones de los productos convertidas a cm. Los productos sin dimensiones cuentan como 10 × 10 × 10 cm. Un carrito sin ningún peso se envía como 0,5 kg. El valor declarado es el importe del pedido.
Cada cotización se guarda en caché durante 1 hora para la misma ruta y el mismo paquete. Una solicitud fallida se guarda en caché durante 10 minutos, para que una API no disponible no ralentice cada actualización de la finalización de compra. Si Envioclick devuelve un error o no hay transportista para la ruta, el cliente no ve ningún error: se usa el precio fijo o el coste de reserva, o el método se oculta. El motivo se escribe en el registro de depuración cuando está activado.
La extensión solo calcula tarifas. No crea guías ni etiquetas, no solicita recolecciones y no rastrea ni cancela envíos. Ofrece una sola tarifa, no una elección entre transportistas, y no usa servicios de pago contra reembolso ni cotizaciones de varios paquetes. Las cotizaciones en tiempo real son solo nacionales.
En OpenCart 4, el cliente hace clic en Choose en el bloque del método de envío de la página de finalización de compra y elige Envioclick en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Pedidos
Cuando se realiza un pedido con Envioclick, la tarifa calculada en la finalización de compra se guarda con el pedido y ya no cambia. En Sales > Orders, la página del pedido muestra el panel Envioclick shipping con Envioclick carrier, Estimated delivery y Envioclick rate ID (para una tarifa en tiempo real), Price source (Envioclick live rate, Fixed price per country, Fallback cost o Free shipping threshold) y Calculated price (excl. tax). El panel se muestra incluso después de desactivar el método.
En OpenCart 4, la finalización de compra mantiene un solo pedido y lo actualiza cada vez que el cliente vuelve a confirmar. La tarifa guardada se sustituye entonces por la última tarifa de la finalización de compra. Si el cliente cambia a otro método de envío, el panel ya no se muestra para ese pedido. Los cambios del pedido en el administrador no modifican la tarifa guardada.
Si Carrier in the title está activado, el transportista forma parte del nombre del método de envío del pedido. Si está desactivado, se añade una línea Shipping carrier: con el transportista de una tarifa en tiempo real al correo del nuevo pedido y a la página del pedido en la cuenta del cliente, mientras la extensión esté activada. Crea la guía en tu cuenta de Envioclick. Los pedidos realizados con un precio fijo no tienen transportista de Envioclick.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Envioclick es el primer bloque de Extensions > Extensions > Shipping > VibeFox Envioclick > 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 volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-envioclick 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 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 acceder al 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, Envioclick no se muestra a los clientes en la finalización de 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 está oculto para todos. 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 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 después de introducir la clave, y después una vez por semana. No se necesita ningún cron job. Al desinstalar la extensión siempre se elimina la clave de licencia y el estado de la licencia.
Solución de problemas
Envioclick no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable Envioclick está activado. Revisa Geo zone, o Ignore shipping zones y Countries, los límites de peso y Minimum order amount. Sin tarifa en tiempo real, el método necesita un precio fijo para el país, una fila * All other countries o un Fallback cost. Comprueba que los productos tienen Requires Shipping en Yes.
Las tarifas en tiempo real no aparecen: lee las advertencias de la sección General, después activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Motivos habituales: no hay tipo de cambio (la moneda de la tienda no es MXN ni COP), no hay User-Agent (México), no hay código postal o código DANE de origen, el código postal del cliente (México) o la ciudad (Colombia) aún no se ha introducido, el destino está fuera del país de la API, o no hay transportista para la ruta.
¿Por qué un tipo de cambio? Envioclick devuelve precios solo en pesos mexicanos o colombianos. La extensión nunca muestra un importe en pesos como si fuera otra moneda.
Colombia: la ciudad no se reconoce: comprueba que el cliente selecciona el departamento como región de la dirección y escribe bien el nombre del municipio. También funciona un código DANE de 8 dígitos escrito como código postal.
El impuesto se cobra dos veces en el envío: las cotizaciones de Envioclick ya incluyen los impuestos de los transportistas. Define Tax class como No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Así se borran las cotizaciones en caché.
La página dice "Warning: You do not have permission to modify VibeFox Envioclick!": tu grupo de usuarios administradores solo puede ver los ajustes. Concede al grupo el permiso de modificación para extension/shipping/vfd_envioclick (OpenCart 3) o extension/vfd_envioclick/shipping/vfd_envioclick (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de cotización de Envioclick puede sustituirse con el ajuste vfd_evc_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 Envioclick. OpenCart siempre restablece Enable Envioclick, Sort order, Tax class y Geo zone. Las cotizaciones en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de Envioclick y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Los datos de Envioclick de los pedidos realizados se conservan en ambos casos, y los pedidos mantienen 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 y haz clic en Uninstall (el botón naranja −) junto a VibeFox Envioclick en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Envioclick es una marca comercial de su propietario. Esta extensión no está afiliada a Envioclick ni cuenta con su respaldo.