VibeFox Cargoson for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Cuenta de Cargoson (solo para precios en tiempo real): los precios en tiempo real usan la API de precios de fletes de Cargoson. Las consultas de precios de flete requieren una suscripción de Cargoson con acceso a la API (plan Advanced o superior en el momento de escribir esto). La clave de API se emite en tu cuenta de Cargoson; pide ayuda al soporte de Cargoson si tu plan no muestra los ajustes de API. Los precios proceden de los transportistas y 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 dominio.
Instalación
El paquete de 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_cargoson-oc3-(versión).ocmod.zip y el paquete de OpenCart 4 vfd_cargoson.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_cargoson-oc3-(versión).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 Cargoson 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 configuración.
4. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia situado en la parte superior de la página Edit y haz clic en Activate (ver Clave de licencia).
5. Elige cómo se calcula el coste de 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). Activa Enable Cargoson y haz clic en Save.
OpenCart 4
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_cargoson.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 Cargoson, 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 los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable Cargoson y guardes. Si vuelves a instalar la extensión después de desinstalarla, se vuelven a usar los ajustes de Cargoson que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. Las secciones aparecen a la izquierda. Un único botón Save al final guarda toda la página sin recargarla. Tras guardar verás Settings saved. Cached Cargoson prices were cleared. Los números decimales se pueden escribir con punto o con coma. No se guarda nada y la página muestra los errores si Method title está vacío o tiene más de 64 caracteres, si un campo numérico contiene texto o un número negativo, si Currency conversion rate es 0, si Minimum weight (kg) es mayor que Maximum weight (kg), si Price currency no es un código de 3 letras, si una fila de la tabla de precios tiene un país o un precio no válido, o si Sort order no es un número entero. Si la extensión no reconoce la unidad de peso de la tienda, un aviso tras guardar indica que los pesos de los productos se toman como kilogramos; añade una clase de peso con la unidad kg en System > Localisation > Weight Classes. Solo los usuarios administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
General
El cliente ve una única tarifa de Cargoson. Puedes limitar el método a una zona geográfica o a países en Availability.
Enable Cargoson: muestra u oculta Cargoson en la finalización de compra. Predeterminado: desactivado.
Method title: el nombre del método de envío que el cliente ve en el carrito y en la finalización de compra, como máximo 64 caracteres. Predeterminado: Cargoson. Obligatorio.
Shipping cost: cómo se calcula el precio.
El motivo de la falta de un precio en tiempo real se escribe en el registro de depuración. Nunca se muestra al cliente.
Sort order: la posición de Cargoson entre los métodos de envío en la finalización de compra. Un número entero.
API de Cargoson (obligatoria solo para precios en tiempo real)
API key: la clave de API de tu cuenta de Cargoson. Se envía solo a Cargoson y nunca se muestra a los clientes ni se escribe en el registro. Tras 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: actívalo y guarda para eliminar la clave guardada.
Carrier: qué precios se usan. El cliente ve una única tarifa.
Package type code: el 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 único paquete con el peso total del carrito.
Price currency: la moneda de los precios en tu cuenta de Cargoson, como código de 3 letras. Predeterminado: EUR. La API devuelve importes sin código de moneda.
Currency conversion rate: necesario solo 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, de modo que nunca se cobre al cliente en una moneda incorrecta.
Dirección de origen (dirección de recogida) (para precios en tiempo real)
Collection country: el país desde el que envías. La primera opción, Store country, usa el país de tu tienda.
Collection postcode: el código postal desde el que envías. Cargoson lo exige para los precios en tiempo real. La dirección de la tienda en OpenCart es texto libre, así que el código postal nunca se toma de ella: introdúcelo aquí.
La fecha de recogida enviada a Cargoson es hoy en la zona horaria de la tienda, o el lunes siguiente si es fin de semana.
Precios fijos (se usan cuando Shipping cost es Fixed prices, y como alternativa para los precios en tiempo real)
Price per country and size: una lista de filas con un Country, un Price y precios según el peso del carrito, en la moneda predeterminada de la tienda y sin impuestos: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg, XL por encima de 5 kg. Un precio de tamaño vacío o 0 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. Elige * All other countries para los precios que se usan en todos los países sin fila propia. Los países sin fila (cuando no hay fila *) no tienen tarifa fija, así que el método se oculta para ellos. Los precios deben ser números iguales o mayores que 0. Una fila vacía se ignora.
Fixed price applies: Per order (predeterminado) cobra el precio una 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 (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, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping: activa el envío gratuito de Cargoson a partir del importe indicado abajo.
Free shipping from: el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual el envío es gratuito. Se usa solo cuando Free shipping está activado.
Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Los precios de los transportistas en Cargoson suelen ser netos (sin IVA). Elige No tax si tus precios ya incluyen impuestos.
Disponibilidad
Geo zone: ofrece Cargoson solo a direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore shipping zones: no comprueba la zona geográfica; decide la lista de países de abajo.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Este campo se usa solo cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra cada cálculo de tarifas en storage/logs/vfd_cgs_debug.log.php. El archivo no se puede leer 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. Cuando el archivo llega a 5 MB, se traslada a vfd_cgs_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 Cargoson, los precios en caché y el registro. Si está desactivado (predeterminado), se conservan para una nueva instalación. Las cotizaciones de Cargoson de los pedidos realizados siempre se conservan.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como 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 igual que 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 Cargoson. Si hay una Geo zone definida, Ignore shipping zones está desactivado y la dirección está fuera de la zona, Cargoson no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso y no se incluyen en el importe del pedido. Los pesos de los productos se convierten de su clase de peso a kilogramos. Después, la extensión comprueba las condiciones: países permitidos, peso del carrito e 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. Las tarjetas 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 Cargoson.
En el modo fijo, el precio se toma de la tabla. En los modos en tiempo real, la extensión 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; la extensión elige el más barato (del transportista seleccionado, si lo hay) y, si hace falta, lo convierte a la moneda predeterminada. El precio se calcula en la moneda predeterminada, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
Cada respuesta se guarda en caché durante 1 hora, de modo 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, ningún precio para la ruta o un precio en otra moneda sin tipo de cambio, el cliente no ve ningún error: el método se oculta, o se usa el precio fijo en el modo de respaldo.
La extensión 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 de paquetes ni un punto de recogida. El carrito se cotiza como un único paquete con el peso total; las dimensiones del paquete no se envían. Solo se muestra el precio más barato, no una lista de transportistas.
En OpenCart 4 el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige Cargoson en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
Pedidos
Cuando un cliente realiza un pedido con Cargoson, la tarifa calculada en la finalización de compra se guarda con el pedido. En Sales > Orders, la página del pedido muestra un panel Cargoson shipping:
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.
El panel también se muestra mientras el método está desactivado. En OpenCart 4 el pedido se crea una vez en el paso de confirmación y se actualiza cada vez que el cliente vuelve a él, así que la cotización guardada es la última calculada en la finalización de compra; si el cliente cambia a otro método de envío, la cotización de Cargoson del pedido se elimina. Cambiar el pedido en el administrador no modifica la cotización, que tampoco cambia después. Reserva el envío en Cargoson o con tus propias integraciones.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Cargoson es el primer bloque de Extensions > Extensions > Shipping > VibeFox Cargoson > Edit, por encima de los ajustes. Introduce 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-cargoson 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 y una fecha. Tras cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, 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, Cargoson no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un 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 se oculta 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 requieren una renovación. El estado se comprueba de nuevo automáticamente al abrir el Dashboard del administrador o la página Edit: una vez al día durante los primeros 14 días tras introducir la clave y después una vez por semana. No hace falta ningún cron job. Desinstalar la extensión 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. Revisa la Geo zone (o Ignore shipping zones y Countries), los límites de peso y el Minimum order amount. En el modo fijo, comprueba que el país o * All other countries tenga un precio para el tamaño del carrito. Comprueba que los productos tengan Requires Shipping en Yes.
Los precios en tiempo real no aparecen: mira el campo Log de la página de la extensión. 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 Collection postcode, la clave de API está rechazada (clave incorrecta o caducada, o tu plan de Cargoson no tiene acceso a la API), 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 recibiendo 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: pon Price currency en la moneda de tus precios de Cargoson e introduce la Currency conversion rate.
El impuesto se cobra dos veces en el envío: tus precios de Cargoson ya incluyen IVA. Pon Tax class en No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra los precios de Cargoson en caché.
La página dice "Warning: You do not have permission to modify VibeFox Cargoson!": es posible que tu grupo de usuarios del administrador solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_cargoson (OpenCart 3) o extension/vfd_cargoson/shipping/vfd_cargoson (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de Cargoson se puede cambiar con el ajuste vfd_cgs_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 Cargoson. La clave de licencia y el estado de la licencia de esta extensión se eliminan siempre. OpenCart siempre restablece Enable Cargoson, Sort order, Tax class y Geo zone. Los precios en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de Cargoson y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al instalar la extensión de nuevo. Las cotizaciones de Cargoson de los pedidos realizados nunca se borran, y 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 tras la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Cargoson en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Cargoson es una marca comercial de su respectivo propietario. Esta extensión no está afiliada a Cargoson ni cuenta con su respaldo.