VibeFox Envioclick for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
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. Pide ese valor al soporte de Envioclick (soporte.tecnico@envioclick.com).
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
1. En el panel de administración ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure o busca más tarde VibeFox Envioclick en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (consulta Clave de licencia).
4. Introduce la clave de API, elige el país de la API, introduce el User-Agent (México), el código postal o el código DANE de origen y la dirección de origen. Si la moneda predeterminada de tu tienda no es MXN ni COP, introduce el tipo de cambio de moneda. Para Colombia, haz clic en Add Colombian departments si la página lo ofrece.
5. Opcionalmente, añade precios fijos por país y un coste alternativo, y después haz clic en Save.
Al instalar, el módulo crea el transportista Envioclick Shipping con el texto de plazo de entrega Courier delivery by the best Envioclick carrier. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre viene del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Envioclick > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. 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.
Cuando hay una clave de API configurada, la página muestra avisos en la parte superior si las tarifas en tiempo real no pueden funcionar: no hay tipo de cambio para una moneda de la 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. La página también avisa si la unidad de peso o de dimensiones de tu tienda no se reconoce; configura kg, g, lb u oz y cm, mm, m o in en International > Localization (Local units). Al guardar, el módulo comprueba que Method title sea un nombre de transportista válido, que los campos numéricos contengan números no negativos, que Currency conversion rate sea mayor que 0, que Minimum weight no sea mayor que Maximum weight y que el código de origen tenga 5 dígitos para México u 8 dígitos (o el código de municipio de 5 dígitos) para Colombia. Si una comprobación falla, se muestra un error y no se guarda nada.
General
Las zonas, los grupos de clientes y los límites de tamaño del transportista se configuran en Shipping > Carriers (o usa Ignore shipping zones más abajo). Los ajustes de esta página se aplican a todas las zonas.
Enable Envioclick: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista que ve el cliente en el carrito y en la finalización de compra. Predeterminado: Envioclick Shipping. Obligatorio.
Carrier in the title: muestra el transportista de Envioclick y el plazo de entrega estimado de una tarifa en tiempo real debajo del transportista en la finalización de compra, por ejemplo "Estafeta Express, 1 day". El transportista se guarda en el pedido y se muestra en las páginas de pedido en cualquier caso. Predeterminado: activado.
Envioclick API (live rates)
Opcional. Sin clave de API solo se usan los precios fijos. La sección incluye enlaces a 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. Los envíos a otros países usan 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". Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Remove the saved API key: se muestra solo mientras hay una clave guardada. Elige Yes y guarda para eliminar la clave; entonces solo se usan los precios fijos. Una clave escrita en API key sustituye a la guardada.
API country: el país de tu cuenta de Envioclick.
Colombian departments: solo Colombia. PrestaShop no tiene departamentos colombianos de forma predeterminada. Sin ellos, solo se reconocen los nombres de ciudad que son únicos en Colombia; el departamento distingue los municipios con el mismo nombre. El botón Add Colombian departments añade los 33 departamentos como estados de Colombia (códigos ISO ANT, DC, etc.), activa "Contains states" para Colombia y añade el campo de departamento al formulario de dirección colombiano. Los departamentos que ya existen no se añaden dos veces. Cuando todo está listo, el campo muestra cuántos departamentos tienen las direcciones colombianas.
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: considera también 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 los servicios de pago contra entrega (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 la tienda es MXN o COP. Sin él, las tarifas en tiempo real no se usan en otra moneda.
Origen del envío
Se usa para las tarifas en tiempo real. Los campos vacíos se toman de la dirección de la tienda en Shop Parameters > Contact > Stores si la tienda está en el país de la API.
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á; el código de municipio de 5 dígitos (11001) también funciona.
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 ante un error de la API o cuando no hay transportista para la ruta.
Price per country: una tabla de códigos de país de 2 letras y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add row para añadir un país y en el icono de papelera para eliminarlo. Usa * como código de país para 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 transportista en ese caso.
Fixed price applies: Per order 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: oculta el transportista por debajo de este peso del carrito, en kg. 0 significa sin límite.
Maximum weight: oculta el transportista por encima de este peso del carrito, en kg. Predeterminado: 25. 0 significa sin límite.
Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (después de descuentos, antes de impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: envío gratis cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcanza este importe. En ese caso no se hace ninguna solicitud a Envioclick. Déjalo vacío para no ofrecer nunca envío gratis.
Tax: la regla de impuesto del transportista, o No tax. 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 sin zonas de envío
Normalmente el transportista se ofrece en las zonas que se le asignan en Shipping > Carriers.
Ignore shipping zones: ofrece Envioclick para los países indicados abajo aunque el transportista no esté asignado a su zona. Al activarlo, el transportista se asigna a todas las zonas, incluidas las que se creen después. Al desactivarlo, el transportista recupera sus zonas anteriores.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías (países activos). Solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra los cálculos de tarifas y los errores de la API en logs/vfd_evc_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir 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. Desactívalo cuando termines.
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 el módulo se eliminan los ajustes de Envioclick, el transportista, las cotizaciones en caché y los registros. El transportista guardado en pedidos anteriores se conserva. Si está desactivado, todo se conserva para una reinstalación.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de Envioclick. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el importe del pedido. El módulo comprueba primero las condiciones: los países de Ignore shipping zones, el peso del carrito y el importe mínimo del pedido. Si se aplica envío gratis, el precio es 0 y no se envía ninguna solicitud a Envioclick.
Si hay una clave de API configurada y el destino está en el país de la API, el módulo pide a Envioclick las cotizaciones. 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 se reconocen el departamento y el municipio (no importan los acentos ni las mayúsculas). El módulo elige la cotización más barata o la más rápida que no sea pago contra entrega y la convierte a la moneda predeterminada de tu tienda. Después, el precio se muestra en la moneda del carrito del cliente.
El paquete es siempre una sola caja: el peso total convertido a kg, y el largo y el ancho del artículo más grande, con una altura que mantiene el volumen total de todos los artículos. Los productos sin dimensiones cuentan como 10 × 10 × 10 cm. Un carrito sin peso se envía como 0,5 kg. El valor declarado es el subtotal del carrito.
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. El tiempo de espera de la API es de 10 segundos. Si Envioclick devuelve un error o ningún transportista para la ruta, el cliente no ve ningún error: se usa el precio fijo o el transportista se oculta. El motivo se escribe en el registro de depuración.
Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.
El módulo solo calcula tarifas. No crea guías ni etiquetas, no solicita recogidas y no rastrea ni cancela envíos. Ofrece una sola tarifa, no una elección entre transportistas, y no usa servicios de pago contra entrega ni cotizaciones de varios paquetes. Las cotizaciones en tiempo real son solo nacionales.
Pedidos
Cuando se realiza un pedido con el transportista de Envioclick, la tarifa calculada para su carrito se guarda con el pedido y ya no cambia. La página de pedido del administrador muestra el bloque 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). En el caso de una tarifa en tiempo real, la página de pedido del cliente muestra Shipping carrier. Crea la guía en tu cuenta de Envioclick.
Los pedidos con precio fijo no tienen transportista de Envioclick.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Envioclick es el primer bloque de Modules > Module Manager > VibeFox Envioclick > Configure, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-envioclick y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar 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 transportista de Envioclick no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un aviso en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: 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. Desinstalar o restablecer el módulo elimina siempre 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. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y su grupo, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y el Minimum order amount. Sin tarifa en tiempo real, el transportista necesita un precio fijo para el país, una fila * o un Fallback cost. Los productos también pueden limitarse a ciertos transportistas en la página del producto.
Las tarifas en tiempo real no aparecen: lee los avisos de la parte superior de la página del módulo, después activa el Debug log, recarga la finalización de compra y mira el campo Log de la página del módulo. 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. El módulo nunca muestra un importe en pesos como si fuera otra moneda.
Colombia: la ciudad no se reconoce: haz clic en Add Colombian departments en la página del módulo para que los clientes puedan elegir el departamento, y comprueba que el nombre del municipio esté bien escrito. Un código DANE de 8 dígitos escrito como código postal también funciona.
Se cobran impuestos dos veces en el envío: las cotizaciones de Envioclick ya incluyen los impuestos de los transportistas. Pon Tax en No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las cotizaciones en caché.
La página indica que no se encontró el transportista de Envioclick: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Envioclick y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las cotizaciones en caché y las tarifas guardadas de los carritos sin pedido siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se eliminan los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, el transportista guardado recupera su estado anterior. En ambos casos se conservan los datos de Envioclick de los pedidos realizados.
Envioclick es una marca comercial de su titular. Este módulo no está afiliado ni respaldado por Envioclick.