VibeFox Chilexpress for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior, con la extensión cURL para las tarifas en tiempo real. El módulo no se instala en versiones anteriores de PHP.
Claves de API de Chilexpress (solo para tarifas en tiempo real): crea una cuenta en el portal de desarrolladores de Chilexpress (developers.wschilexpress.com) y suscríbete a dos productos: Rating (Cotizador) y Coverage (Coberturas / Georreferencia). Cada producto tiene su propia clave de suscripción. Las claves de prueba funcionan solo con el entorno de prueba; las claves de producción se emiten a clientes empresariales de Chilexpress con contrato de cliente. También necesitas el código county de Chilexpress de la comuna desde la que envías, por ejemplo STGO. Si solo usas precios fijos, no necesitas claves de API.
Regiones chilenas (solo para tarifas en tiempo real): las tarifas en tiempo real necesitan la región de la dirección de entrega. PrestaShop no tiene regiones chilenas por defecto; el módulo puede añadirlas por ti (consulta Chilean regions más abajo). El país Chile debe existir en la tienda.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
1. En el back office, 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 después VibeFox Chilexpress 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 (véase Clave de licencia).
4. Rellena la tabla Country prices. Para las tarifas en tiempo real, introduce ambas claves de suscripción, el código county de origen y, si la moneda de la tienda no es CLP, el tipo de cambio a CLP; haz clic en Add Chilean regions si la página lo pide; después elige la fuente de tarifas (véase Configuración) y haz clic en Save.
Al instalar, el módulo crea el transportista Chilexpress con el texto de plazo de entrega Chilexpress courier. El transportista está vinculado a la zona de Chile 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. Para ofrecer Chilexpress en otras zonas, añádelas al transportista en esa página, o activa Ignore shipping zones.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Chilexpress > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de Chilexpress y las listas de comunas en caché. Los cambios requieren el permiso "configure" del módulo; sin él, la página muestra You do not have permission to configure this module.
La página muestra los problemas en la parte superior: hay tarifas de la API seleccionadas pero falta una clave, el código county de origen o el tipo de cambio a CLP; la tabla de precios no tiene fila para Chile ni para el valor por defecto; la tienda no tiene regiones chilenas o el formulario de dirección chileno no tiene campo de región; la unidad de peso o de dimensiones de la tienda no la reconoce el módulo (en ese caso se toma como kg o cm; configúrala en International > Localization, Local units); el transportista fue eliminado. Los números se pueden escribir con punto o con coma, según el idioma de tu back office. Un número no válido o negativo, un CLP exchange rate de 0, un Min weight (kg) mayor que Max weight (kg) o un Name de más de 64 caracteres son errores, y no se guarda nada hasta que los corrijas.
General
Enable/Disable: activa o desactiva el envío con Chilexpress. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del método de envío que ve el cliente en la finalización de compra. Es el nombre del transportista. Por defecto: Chilexpress. Obligatorio, hasta 64 caracteres.
Tax: la regla de impuesto del transportista, o No tax (el valor por defecto de un transportista nuevo). Las tarifas de la API de Chilexpress se usan tal como se cotizan. Elige No tax si la cotización ya incluye IVA y la tienda añadiría impuesto encima.
Tarifas
Rate source: de dónde viene el precio.
Las tarifas en tiempo real están disponibles solo para destinos en Chile. Los demás países siempre usan los precios fijos.
Country prices: una tabla de países de destino con una columna Price y precios opcionales por tamaño de paquete, en la moneda por defecto de tu tienda, sin impuestos. El tamaño se obtiene 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. Un tamaño dejado en 0 usa Price. Haz clic en Add country para añadir una fila y en el icono de papelera para eliminar una. La fila * Default se aplica a los países sin fila propia. Un país sin fila (y sin * Default) no tiene precio fijo, así que el transportista se oculta allí. Una fila cuyo precio y precios por tamaño son todos 0 da envío gratis. Una tabla vacía se muestra con una fila para Chile a 0, y la última fila no se puede eliminar, solo restablecer a 0; por eso introduce precios reales antes de guardar la página. Un país repetido o un precio no válido se corrige (el duplicado se ignora, el precio se pone a 0) y un aviso enumera las correcciones.
Calculation type: Per order cobra el precio fijo una vez. Per item (fixed price x number of items) lo multiplica por el número de artículos del carrito. Una tarifa de la API de Chilexpress siempre se cotiza para el paquete completo.
API de Chilexpress (tarifas en tiempo real)
La sección empieza con enlaces al portal de desarrolladores y a las páginas de suscripción de Rating y Coverage.
Test environment: usa el entorno de prueba de Chilexpress (qaservices.wschilexpress.com). Úsalo con claves de prueba y desactívalo en una tienda real.
Rating API key: la clave de suscripción del producto Rating (Cotizador).
Coverage API key: la clave de suscripción del producto Coverage (Coberturas / Georreferencia). Se usa para encontrar el código county de Chilexpress de la comuna del cliente (el campo Ciudad de la dirección, junto con su región).
Después de guardar, el campo de clave queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. La clave se guarda tal como la escribes; solo se eliminan los espacios alrededor.
Remove the saved Rating API key y Remove the saved Coverage API key: se muestran solo cuando hay una clave guardada. Actívala y haz clic en Save para borrarla.
Origin county code: el código county de Chilexpress (comuna) desde el que envías, de 2 a 5 letras, por ejemplo STGO (Santiago Centro), PROV (Providencia) o VALP (Valparaíso). Está vacío después de instalar. Un valor que no es un código county se rechaza con un error.
Service: el servicio de Chilexpress usado para la tarifa. Si no se ofrece para el destino, se usa el servicio más barato disponible.
CLP exchange rate: Chilexpress cotiza en pesos chilenos. Solo se necesita si la moneda por defecto de tu tienda no es CLP: el precio de 1 CLP en esa moneda, por ejemplo 0.001. Sin él no se usan las tarifas de la API. Si la moneda de la tienda es CLP, déjalo vacío. El valor debe ser mayor que 0.
Chilean regions: las comunas de Chile se buscan por región, así que las tarifas en tiempo real necesitan la región de la dirección. Si la tienda no tiene regiones chilenas, el campo muestra el botón Add Chilean regions. Este añade las 16 regiones como estados de Chile (códigos ISO RM, VS…), activa "Contains states" para Chile y añade el campo de región al formulario de dirección chilena. Las regiones que ya existen (por código o por nombre) no se añaden dos veces. Cuando todo está listo, el campo muestra Chilean addresses have a region con el número de regiones.
Disponibilidad
Min weight (kg): el peso mínimo del carrito para que aparezca el transportista. 0 significa sin límite.
Max weight (kg): el transportista se oculta por encima de este peso del carrito. Por defecto: 25. 0 significa sin límite; un campo vacío significa 25 kg. Min weight (kg) no puede ser mayor que este valor.
Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito (productos que requieren envío, después de descuentos, sin impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Ignore shipping zones: ofrece el transportista para los países de abajo aunque su zona no esté vinculada a él: el transportista se vincula a todas las zonas, y las zonas creadas después también se vinculan. Al desactivarlo, el transportista recupera sus zonas anteriores.
Countries: los países de destino para ese modo, elegidos entre los países activos de la tienda. Déjalo vacío para permitir todos los países. Este campo solo se usa si Ignore shipping zones está activado.
Envío gratis
Free shipping: activa el umbral de envío gratis.
Free shipping from: el subtotal del carrito (productos que requieren envío, después de descuentos, sin impuestos) a partir del cual el envío es gratis. Se usa solo si Free shipping está activado. En ese caso no se hace ninguna solicitud a la API.
Avanzado
Debug log: escribe las solicitudes a la API y los cálculos de tarifas en logs/vfd_chx_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. Las claves de API y las direcciones de los clientes nunca se registran.
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 borran todos sus ajustes, el transportista, las tarifas en caché, los registros y los servicios guardados con los pedidos. Si está desactivado, todo se conserva para una reinstalación. Los pedidos en sí siempre se conservan.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de Chilexpress. Solo cuentan los productos que requieren envío: los productos virtuales no suman peso ni entran en el subtotal. El subtotal se toma después de las reglas del carrito (cupones), sin impuestos, en la moneda por defecto de tu tienda. El módulo primero comprueba las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna solicitud a Chilexpress.
Para una dirección en Chile y una fuente de tarifas de API, el módulo toma la región de la dirección y la comuna del campo Ciudad, y busca el código county de Chilexpress en la lista de comunas de esa región (Coverage API). Se ignoran los acentos, los espacios y las variantes ortográficas, así que Ñuñoa y Nunoa coinciden, y Santiago coincide con Santiago Centro. También se acepta un código county escrito en el campo Ciudad. Después, el módulo envía a la Rating API el código county de origen y de destino, el peso del carrito (al menos 0,1 kg), las dimensiones del paquete (largo y ancho del producto más grande, alturas apiladas) y el subtotal del carrito en CLP como valor declarado. Chilexpress devuelve sus servicios; el módulo usa el servicio elegido o el más barato, y convierte el importe en pesos a la moneda por defecto de tu tienda. El precio se redondea a los decimales de esa moneda y después se muestra en la moneda del carrito del cliente.
Las tarifas se guardan en caché durante 1 hora y las listas de comunas durante 7 días. Una solicitud fallida se recuerda durante 5 minutos, para que una API lenta o 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 Chilexpress devuelve un error, ningún servicio con precio, o la comuna o la región no se reconoce, el cliente no ve ningún error. En el modo solo API, el transportista se oculta; en los demás casos se usa el precio fijo. 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 envíos ni órdenes de transporte (OT), no imprime etiquetas, no reserva recogidas ni rastrea paquetes; reserva el envío en tu cuenta de Chilexpress. Los clientes no pueden elegir una oficina de Chilexpress, y no hay selector de comunas: el cliente escribe la comuna en el campo estándar Ciudad. Los envíos internacionales usan los precios fijos.
Pedidos
Cuando se realiza un pedido con el transportista Chilexpress, el módulo guarda cómo se calculó su precio. La página del pedido en el back office muestra un bloque Chilexpress con Chilexpress service (para una tarifa en tiempo real, el servicio que cotizó Chilexpress, por ejemplo Express) y Price source: Live rate (Chilexpress Rating API), Fixed price o Free shipping.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Chilexpress es el primer bloque de la página Modules > Module Manager > VibeFox Chilexpress > 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 quitar la clave de esta tienda. Debajo están la línea Product: presta-shipping-chilexpress y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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, 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. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el transportista Chilexpress no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. El frontal 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 recordatorio 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 tras introducir la clave, y después una vez a la semana. No hace falta 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
Chilexpress no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o que Ignore shipping zones esté activado y el país esté en Countries). Revisa los límites de peso y el Minimum subtotal. Con precios fijos, comprueba que el país o * Default tenga una fila. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.
El envío en Chile es gratis cuando no debería serlo: la fila de Chile (o * Default) de Country prices tiene 0 en Price y en las columnas de tamaño. Introduce los precios y haz clic en Save.
No se muestra la tarifa en tiempo real y se usa el precio fijo: primero revisa los avisos de la parte superior de la página del módulo. Si no hay avisos, activa Debug log, recarga la finalización de compra y mira el campo Log de la página del módulo. Causas típicas: la dirección no tiene región o falta el campo de región (usa Add Chilean regions), una comuna que Chilexpress no reconoce (revisa el campo Ciudad y la región), una clave de otro producto o entorno, o un destino sin cobertura de Chilexpress.
HTTP 401 o 403 en el registro: la clave de suscripción es incorrecta, está inactiva o es de otro producto o entorno. Las claves de prueba funcionan solo con Test environment activado.
Las tarifas de la API no se usan en una tienda con otra moneda: introduce el CLP exchange rate.
¿Las tarifas de la API llevan IVA o no? Se usan tal como las cotiza Chilexpress. Si tu tienda añade impuesto al envío y la cotización ya incluye IVA, 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 tarifas en caché y las listas de comunas.
La página muestra "The Chilexpress carrier was not found": el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
La página muestra "The country Chile does not exist in this shop": añade o activa Chile en International > Locations > Countries, y luego usa Add Chilean regions.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Chilexpress y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las tarifas en caché y las listas de comunas siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes, el registro y los servicios guardados con los pedidos. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, se restaura el transportista guardado con su estado anterior. Las regiones chilenas añadidas con Add Chilean regions permanecen en la tienda.
Chilexpress es una marca registrada de su respectivo titular. Este módulo no está afiliado ni respaldado por Chilexpress.