VibeFox Cargoson 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 Cargoson (solo para precios en tiempo real): los precios en tiempo real usan la API de precios de flete de Cargoson. Las consultas de precios de flete requieren una suscripción a Cargoson con acceso a la API (plan Advanced o superior en el momento de escribir esto). La clave de API la emite tu cuenta de Cargoson; si tu plan no muestra la configuración de la API, pide ayuda al soporte de Cargoson. Los precios provienen de los transportistas y de las listas de precios conectados a esa cuenta. Si solo usas precios fijos, no necesitas una cuenta de Cargoson.
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 VibeFox Cargoson más tarde 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. Elige cómo se calcula el coste del envío y rellena las secciones correspondientes: los precios fijos y, para los precios en tiempo real, la clave de API y el código postal de recogida (ver Configuración). Haz clic en Save.
Al instalar, el módulo crea el transportista Cargoson con el texto del plazo de entrega Delivery by the cheapest Cargoson 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 definas precios allí: el precio siempre procede del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Cargoson > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. Después de guardar verás Settings saved. Cached Cargoson prices were cleared. Los decimales se pueden escribir con punto o con coma. No se guarda nada y la página muestra un error si un campo numérico contiene texto o un número negativo, si Currency conversion rate es 0, si Minimum weight es mayor que Maximum weight, si Method title tiene más de 64 caracteres, si Price currency no es un código de 3 letras, o si una fila de la tabla de precios tiene un código de país o un precio no válidos. Si el módulo no reconoce la unidad de peso de la tienda, después de guardar aparece una advertencia que dice que los pesos de los productos se toman como kilogramos; define la unidad en International > Localization (Local units).
General
Enable Cargoson: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista que se muestra en el carrito y en la finalización de compra. Predeterminado: Cargoson. Obligatorio. También es el nombre del transportista en Shipping > Carriers.
Shipping cost: cómo se calcula el precio.
El motivo de que falte un precio en tiempo real se escribe en el registro del módulo. Nunca se muestra al cliente.
API de Cargoson (solo necesaria para los precios en tiempo real)
API key: la clave de API de tu cuenta de Cargoson. Solo se envía a Cargoson 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 cambiarla.
Remove the saved API key: aparece cuando hay una clave guardada. Actívala y guarda para eliminar la clave.
Carrier: qué precios se usan. El cliente ve una sola tarifa.
Package type code: el código de tipo de paquete de Cargoson que se envía con la consulta de precio. Predeterminado: CLL. Los ejemplos de la API de Cargoson usan EUR (palé EUR) y FIN (palé FIN). Para paquetes, usa el código de paquete de tu cuenta de Cargoson. El pedido se envía como un solo paquete con el peso total del carrito.
Price currency: la moneda de los precios de tu cuenta de Cargoson, como código de 3 letras. Predeterminado: EUR. La API devuelve importes sin código de moneda.
Currency conversion rate: solo se necesita si la moneda de los precios es distinta de la moneda predeterminada de tu tienda: 1 unidad de la moneda de Cargoson = X unidades de la moneda predeterminada. Déjalo vacío para rechazar esos precios, así un cliente nunca paga en una moneda incorrecta.
Envío desde (dirección de recogida) (se usa para los precios en tiempo real)
Collection country: el país desde el que envías. Por defecto es el país de tu tienda.
Collection postcode: el código postal desde el que envías. Cargoson lo exige. Si está vacío y el país de recogida es el país de tu tienda, se usa el código postal de la tienda de Shop Parameters > Contact > Stores.
La fecha de recogida que se envía a Cargoson es hoy, en la zona horaria de la tienda, o el lunes siguiente si es fin de semana.
Precios fijos (se usa cuando Shipping cost es Fixed prices, y como alternativa para los precios en tiempo real)
Price per country and size: una tabla con una columna Country (código de 2 letras), una columna Price y precios según el peso del carrito en la moneda predeterminada de tu tienda, sin impuestos: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg, XL por encima de 5 kg. Si el precio de un tamaño está vacío o es 0, se usa la columna Price; un Price vacío significa que no hay tarifa fija para ese tamaño. Haz clic en Add country para añadir una fila y en el icono de papelera para eliminar una. Usa * como código de país para todos los países que no tengan fila propia. Los países sin fila (cuando no hay fila *) no tienen tarifa fija, así que el transportista se oculta para ellos. Los precios deben ser números iguales o superiores a 0. Una fila vacía se ignora.
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. Los precios en tiempo real de Cargoson 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: activa el envío gratuito cuando se alcanza el importe del pedido indicado abajo.
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual el envío es gratuito. Se usa solo cuando Free shipping está activado.
Tax: la regla de impuestos del transportista, o No tax. Los precios de los transportistas en Cargoson suelen ser netos (sin IVA). Elige No tax si tus precios ya incluyen impuestos.
Disponibilidad sin zonas de envío
Normalmente el transportista se ofrece en las zonas asignadas en Shipping > Carriers.
Ignore shipping zones: ofrece Cargoson para los países indicados abajo, sean cuales sean las zonas asignadas al transportista. Al activarlo y guardar, el transportista se asigna a todas las zonas; las zonas creadas más tarde también se asignan. Al desactivarlo y guardar, 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). Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra cada cálculo de tarifa en logs/vfd_cgs_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API y los precios rechazados siempre se registran, incluso con esta opción desactivada. La clave de API y el código postal del cliente nunca se registran.
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 el módulo se eliminan los ajustes de Cargoson, el transportista, los precios en caché, las cotizaciones de los pedidos y los registros. 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 Cargoson. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el importe del pedido. Los pesos de los productos se convierten de la unidad de tu tienda a kilogramos. El módulo primero comprueba las condiciones: país de entrega, peso del carrito e importe mínimo del pedido. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Cargoson.
En el modo de precios fijos, el precio se toma de la tabla. En los modos en tiempo real, el módulo envía a Cargoson la fecha de recogida, el país y el código postal de recogida, el país y el código postal de entrega, y un paquete con el código de tipo de paquete y el peso total del carrito (al menos 0,1 kg). Un precio en tiempo real solo se solicita cuando la dirección de entrega tiene código postal. Cargoson devuelve los precios de tus transportistas; el módulo elige el más barato (del transportista seleccionado, si lo hay) y lo convierte a tu moneda predeterminada si hace falta. El precio se calcula en la moneda predeterminada y después se muestra en la moneda del carrito del cliente.
Cada respuesta se guarda en caché durante 1 hora, así que el mismo carrito no genera una nueva solicitud. Una solicitud fallida se guarda en caché durante 10 minutos, para que la finalización de compra no espere a Cargoson en cada actualización. El tiempo de espera de la API es de 10 segundos. Si Cargoson devuelve un error, no devuelve ningún precio para la ruta o devuelve un precio en otra moneda sin tipo de conversión, el cliente no ve ningún error. El transportista se oculta, o se usa el precio fijo en el modo de alternativa.
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 reservas en Cargoson, no imprime etiquetas ni hace seguimiento de paquetes, y los clientes no pueden elegir una taquilla automática de paquetes ni un punto de recogida. El carrito se cotiza como un solo paquete con el peso total; las dimensiones del paquete no se envían. Solo se muestra el precio más bajo, no una lista de transportistas.
Pedidos
La página de un pedido de Cargoson muestra un bloque Cargoson shipping con la tarifa calculada en la finalización de compra:
Carrier, Service y Cargoson service ID: el transportista y el servicio de Cargoson cotizados, que se muestran cuando se usó un precio en tiempo real.
Price source: Cargoson live price, Fixed price o Free shipping threshold.
Calculated price (excl. tax): el precio en la moneda predeterminada de tu tienda.
La cotización se guarda al realizarse el pedido y no cambia después. Reserva el envío en Cargoson o con sus propias integraciones.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Cargoson es el primer bloque de Modules > Module Manager > VibeFox Cargoson > Configure, 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-cargoson y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso de configuración del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el 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. 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 de Cargoson 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 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 después de introducir la clave, y después una vez por semana. No es necesario configurar 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
Cargoson no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Cargoson esté activado. En Shipping > Carriers comprueba que el transportista cubre la zona del país del cliente y el grupo del cliente (o que Ignore shipping zones está activado y el país figura en Countries). Revisa los límites de peso y Minimum order amount. En el modo de precios fijos, comprueba que el país o * tenga un precio para el tamaño del carrito. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.
Los precios en tiempo real no aparecen: revisa el campo Log en la página del módulo. Los errores de la API siempre se registran; activa Debug log para ver cada cálculo. Motivos habituales: aún no se ha introducido el código postal de entrega, falta el código postal de recogida, la clave de API ha sido rechazada (clave incorrecta o caducada, o sin acceso a la API en tu plan de Cargoson), no hay transportista para la ruta o el peso, o hay un precio en otra moneda. Con Cargoson live prices, fixed prices if the API fails, los clientes siguen viendo el precio fijo mientras corriges el problema.
Cargoson rechaza el tipo de paquete: usa el código de paquete que tu cuenta de Cargoson utiliza en Package type code. El motivo aparece en el registro.
Se rechaza un precio en otra moneda: define Price currency como la moneda de tus precios de Cargoson e introduce el Currency conversion rate.
El IVA se cobra dos veces en el envío: tus precios de Cargoson ya incluyen el IVA. Define Tax como No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Así se borran los precios de Cargoson guardados en caché.
La página indica que no se encontró el transportista de Cargoson: 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 Cargoson y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Los precios en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes, las cotizaciones de los pedidos y el registro. Si está desactivado, el transportista solo se desactiva, los ajustes y las cotizaciones de los pedidos realizados se conservan, y solo se eliminan las cotizaciones de carritos sin pedido. Al volver a instalar el módulo, el transportista guardado recupera su estado anterior, así que Reset no activa un transportista que hubieras desactivado.
Cargoson es una marca registrada de su respectivo propietario. Este módulo no está afiliado a Cargoson ni cuenta con su respaldo.