VibeFox CTT 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 comercio electrónico de CTT (solo para tarifas en tiempo real y puntos de CTT): las tarifas en tiempo real y la entrega en un punto de CTT usan la API de comercio electrónico de CTT. Necesitas una cuenta de comercio electrónico de CTT en enviosecommerce.ctt.pt (para clientes con contrato CTT Expresso, o pide a CTT una propuesta). En la página de gestión de claves de esa cuenta, crea un par de claves pública y privada. El App ID (X-APPID) lo emite CTT para tu integración: pregunta a tu contacto de comercio electrónico de CTT. CTT también decide qué funciones de la API (estimación de coste, puntos de CTT) puede usar tu App ID. Por último, necesitas el Carrier ID de CTT en tu cuenta. La página de configuración muestra los transportistas de tu cuenta una vez guardadas las claves. Si solo usas la tabla de precios y la entrega en la dirección, no necesitas claves de API.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_ctt-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_ctt.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 la administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_ctt-oc3-(version).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 CTT y haz clic en Install (el botón verde +).
3. Haz clic en Edit (el botón con lápiz) para abrir la página de configuración.
4. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Edit y haz clic en Activate (ver Clave de licencia).
5. Rellena la tabla de precios (al menos una fila Portugal o * Default), activa Enable/Disable y/o Enable CTT point option y haz clic en Save. Opcionalmente, rellena las claves de API de CTT, el App ID y el Carrier ID, y activa Live rates (ver Configuración).
OpenCart 4
1. En la administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_ctt.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 CTT, haz clic en Install (el botón verde +) y después en Edit (el botón con 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 configuración y sus campos son iguales en ambas versiones.
Tras la primera instalación, ambas opciones de envío están desactivadas hasta que actives una y guardes. Si vuelves a instalar la extensión después de desinstalarla sin eliminar los datos, se reutilizan los ajustes conservados y la extensión se vuelve a activar si alguna de las opciones estaba activada.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox CTT > Edit. Las secciones aparecen a la izquierda. Un botón Save al final guarda toda la página sin recargarla. Los precios y las condiciones se aplican a ambas opciones de CTT. Cada guardado borra las respuestas de CTT en caché: el token de API, los transportistas, los precios y las listas de puntos de CTT. Solo los usuarios de administración con el permiso de modificación para esta extensión pueden guardar los ajustes.
Los avisos en la parte superior de la página te informan de: una tabla de precios vacía, un precio que falta para Portugal, claves de API incompletas mientras las tarifas en tiempo real o la opción de punto de CTT están activadas, un Carrier ID que falta, una moneda de la tienda distinta de EUR sin tipo de cambio, una conexión fallida con la API de CTT, y una tienda sin clase de peso con la unidad kg o clase de longitud con la unidad cm (las unidades de los productos se convierten entonces según su nombre de unidad; revisa System > Localisation > Weight Classes y Length Classes). Si un nombre está vacío, no es válido o tiene más de 64 caracteres, si Min weight (kg) es mayor que Max weight (kg), o si Sort Order, la clase de impuesto o la zona geográfica no son válidos, la página muestra un error y no se guarda nada. Otros valores no válidos se notifican como avisos y el resto se guarda: un número no válido no se guarda, un tipo de cambio de 0 o menos se borra, un tamaño de producto no válido vuelve al valor predeterminado, un destino desconocido o una fila duplicada en la tabla de precios se elimina, y un precio de tabla no válido se deja vacío.
General
La extensión ofrece hasta dos opciones en la finalización de compra: entrega de CTT en la dirección del cliente y entrega en un punto de CTT o taquilla automática. Los precios y las condiciones se aplican a ambas.
Enable/Disable: activa o desactiva la entrega de CTT en la dirección del cliente.
Name: el nombre del método de envío que ve el cliente en la finalización de compra, por ejemplo "CTT Expresso". Predeterminado: CTT. Hasta 64 caracteres.
Tax class: la clase de impuesto del coste de envío. OpenCart añade ese impuesto (por ejemplo IVA) sobre los precios. --- None --- significa que los precios son definitivos. Se usa en ambas opciones.
Sort Order: la posición de CTT entre los métodos de envío en la finalización de compra. Un número entero.
Entrega en un punto de CTT o taquilla automática
La segunda opción de CTT. El cliente busca puntos de CTT por código postal o ciudad (la dirección de entrega se busca automáticamente) y debe elegir uno antes de continuar. Necesita las claves de API de CTT y el Carrier ID. Sin ellos, es una opción sin selección de punto.
Enable CTT point option: ofrece la entrega en un punto de CTT o taquilla automática. Predeterminado: desactivado.
CTT point option name: el nombre de esta opción en la finalización de compra. Predeterminado: CTT point / parcel locker. Hasta 64 caracteres.
API de comercio electrónico de CTT (tarifas en tiempo real, puntos de CTT) (opcional; sin claves se usa la tabla de precios)
Public key: la clave pública de la página de gestión de claves de tu cuenta de comercio electrónico de CTT.
Private key: la clave secreta usada para firmar cada solicitud (HMAC-SHA256). Nunca se envía a CTT ni se escribe en el registro.
Ambas claves nunca se vuelven a mostrar tras guardarlas. La descripción del campo entonces dice Saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Marca Remove the saved public and private key y guarda para eliminar ambas. Cuando no hay nada guardado, la sección muestra No keys saved.
App ID (X-APPID): la clave de aplicación emitida por CTT, enviada en la cabecera X-APPID.
Carrier ID: el ID del transportista de CTT en tu cuenta, usado para las tarifas en tiempo real y la búsqueda de puntos de CTT. Una vez guardadas las claves y el App ID, los transportistas de tu cuenta aparecen debajo del campo (Carriers of your CTT account:), marcando con CTT points los que admiten puntos de CTT. Solo números.
Live rates: pide a CTT el precio (estimación de coste) una vez que el cliente ha introducido la calle, el código postal y la ciudad. Se usa la tabla de precios mientras la dirección esté incompleta y siempre que CTT no proporcione un precio. CTT llama a este precio estimación. Predeterminado: desactivado.
Service ID: opcional. Cuando CTT devuelve varios servicios, se usa el que tiene este ServiceId. Déjalo vacío para usar el más barato.
Exchange rate: los precios de CTT están en euros. Si la moneda predeterminada de tu tienda es otra, indica cuántas unidades de la moneda de tu tienda equivalen a 1 unidad de la moneda de CTT. Sin este valor, las tarifas en tiempo real en otra moneda no se usan y se aplica la tabla de precios.
Default product size (cm): longitud x anchura x altura enviadas a CTT para los productos sin dimensiones. Predeterminado: 30x20x15. Los productos con dimensiones usan las suyas. Las dimensiones se convierten a cm y los pesos a gramos según las clases de longitud y peso de los productos.
Precios (el título de la sección muestra la moneda predeterminada de tu tienda)
Introduce los precios de tu contrato con CTT o de la lista pública de precios de CTT en ctt.pt, en la moneda predeterminada de la tienda, sin impuestos. Con las tarifas en tiempo real desactivadas, esta tabla define el precio. Con ellas activadas, es el precio de reserva.
Price table: una fila por destino. Elige un país, Portugal - Azores, Portugal - Madeira o * Default (other destinations). Cada fila tiene un Price base y precios opcionales para los tamaños XS (hasta 1 kg), S (hasta 2 kg), M (hasta 3 kg), L (hasta 5 kg) y XL (más de 5 kg). Un precio de tamaño vacío (o 0) usa el precio base. Una fila en la que ambos están vacíos oculta el método. La fila de las Azores se usa para los códigos postales portugueses 9500-9999, la de Madeira para 9000-9499. Sin ellas se aplica la fila Portugal. Haz clic en Add destination para añadir una fila y en el botón × para eliminarla. Los precios aceptan punto o coma decimal. La tabla está vacía tras la instalación.
Calculation: cómo se calcula el precio de la tabla.
Un precio de CTT en tiempo real es siempre para el envío completo.
Condiciones
Min weight (kg): el peso mínimo del carrito para que aparezcan las opciones de CTT. 0 significa sin límite.
Max weight (kg): las opciones de CTT se ocultan por encima de este peso del carrito. Predeterminado: 30 (los paquetes de CTT llegan hasta 30 kg). 0 significa sin límite. Min weight (kg) no puede ser mayor que Max weight (kg).
Minimum order amount: muestra las opciones de CTT 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 mostrarlas siempre.
Envío gratuito
Free shipping: activa la entrega gratuita de CTT 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 las opciones de CTT cuestan 0. Solo se aplica a los destinos que tienen precio. Se usa solo cuando Free shipping está activado.
Disponibilidad
Normalmente las opciones de CTT se ofrecen en la zona geográfica seleccionada abajo. All Zones significa en todas partes. Con Ignore shipping zones, no se comprueba la zona geográfica y decide Countries.
Geo Zone: la zona geográfica de la dirección de envío. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore shipping zones: no comprobar la zona geográfica; ofrecer CTT en los países de abajo.
Countries: los países de destino para ese modo. Predeterminado: Portugal. Déjalo vacío para permitir todos los países. Se usa solo con Ignore shipping zones.
Avanzado
Debug log: registra el cálculo de precios y las llamadas a la API de CTT en storage/logs/vfd_ctt_debug.log.php (en OpenCart 4, system/storage/logs/vfd_ctt_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API de CTT siempre se registran, incluso cuando esto está desactivado. Las claves, los tokens y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_ctt_debug.old.log.php y se inicia un registro nuevo.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes, el registro y los puntos de CTT de las finalizaciones de compra sin terminar. Si está desactivado (predeterminado), los ajustes se conservan para una nueva instalación. Los pedidos, incluido el punto de CTT elegido, nunca se modifican.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. La clave pública y la privada no se exportan.
Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. Las claves guardadas se conservan.
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 CTT. Con Ignore shipping zones, CTT se ofrece solo para un país de Countries (vacío = todos los países); en caso contrario, si hay una Geo Zone definida, solo para direcciones dentro de ella. Solo cuentan los productos con Requires Shipping configurado como Yes: los demás no suman peso ni se incluyen en el importe del pedido. La extensión comprueba el peso del carrito y el importe mínimo del pedido. Con Live rates activado y una dirección completa, envía a CTT la dirección de entrega y, para cada línea del carrito, la cantidad, el peso en gramos y las dimensiones en cm, y usa el precio devuelto. En caso contrario, o cuando CTT no da precio (error de API, tiempo de espera, sin cobertura, una función no activada para tu App ID), el precio sale de la tabla. Si se aplica envío gratuito, el precio es 0. Ambas opciones reciben el mismo precio. El precio se calcula en la moneda predeterminada de tu tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
Un precio de CTT se guarda en caché durante 1 hora, de modo que el mismo carrito no genera una nueva solicitud. Una solicitud fallida se recuerda durante 5 minutos, para que la finalización de compra no espere a CTT en cada actualización. El token de API, la lista de transportistas y las listas de puntos de CTT también se guardan en caché, como máximo durante la duración de la caché de OpenCart (1 hora por defecto). Los errores de la API nunca llegan al cliente: se usa el precio de la tabla, o el método se oculta si el destino no tiene precio.
Con las claves de API rellenadas, la extensión envía la dirección de entrega, los pesos y las dimensiones de los productos y la URL de tu tienda a CTT para obtener un precio o los puntos de CTT más cercanos.
La extensión no crea envíos, no imprime etiquetas, no solicita recogidas, no proporciona números de seguimiento ni muestra un mapa de los puntos de CTT. Hay una tabla de precios y un conjunto de ajustes de API para ambas opciones.
En OpenCart 4, el cliente hace clic en Choose en el bloque de método de envío de la página de finalización de compra y elige una opción de CTT en la ventana Shipping method options. Los precios son los mismos que en OpenCart 3.
Puntos de recogida
Cuando el cliente selecciona la opción de punto de CTT en el paso del método de entrega, aparecen debajo un campo de búsqueda y una lista. El código postal de la dirección de entrega se rellena y se busca automáticamente. El cliente puede buscar otros puntos de CTT por código postal o ciudad (botón Search) y elige uno de la lista. La elección se guarda al instante. Solo se acepta un punto de la lista de CTT para esa búsqueda.
El cliente debe elegir un punto antes de continuar. Cuando hace clic en Continue, la extensión comprueba el punto en el servidor. Sin punto, el cliente ve Please select a CTT point.; con un punto que no está en la lista de CTT, The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Si no se puede conectar con CTT, el cliente ve CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
La selección de punto solo está activa cuando la clave pública, la clave privada, el App ID y el Carrier ID están rellenados. Está hecha para el tema predeterminado de OpenCart y su finalización de compra; otros temas pueden necesitar cambios.
En OpenCart 4, el campo de búsqueda y la lista aparecen en la ventana Shipping method options, debajo de la opción de punto de CTT. El botón Continue de la ventana no avanza sin un punto válido, con los mismos mensajes. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar, y el punto de CTT del pedido se actualiza con él.
El punto elegido se añade al método de envío del pedido, por ejemplo CTT point / parcel locker: .... Así el cliente lo ve en el historial de pedidos de su cuenta y en los correos de pedido, y aparece impreso en la factura y en Sales > Orders. La página de éxito del pedido de OpenCart no muestra el método de envío.
En la página de pedido de la administración, el panel CTT point encima del historial muestra el nombre y el ID del punto. Para cambiarlo, introduce un código postal o una ciudad en Change CTT point, haz clic en Search, elige un punto y haz clic en Save. La página muestra CTT point updated., el texto del método de envío del pedido se actualiza y se añade una entrada en el historial CTT point changed to: ... sin notificar al cliente. Cambiar el punto requiere el permiso de modificación de pedidos (sale/order) y los ajustes de la API. El panel se muestra también para pedidos de CTT mientras la extensión está desactivada.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox CTT es el primer bloque de Extensions > Extensions > Shipping > VibeFox CTT > Edit, 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 volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-ctt y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios de administración con el permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma de la administración (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 con 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 conectar con el 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, CTT no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario de administración que haya iniciado sesión en la administración 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 de la administración, 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 de la administración. 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 de la administración 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 a la semana. No se necesita ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
CTT no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable (o Enable CTT point option) esté activado. Revisa Geo Zone, o Ignore shipping zones y Countries. Comprueba que el destino tenga una fila en la tabla de precios (o una fila * Default), que el peso del carrito esté entre Min weight y Max weight, que se alcance el Minimum order amount y que los productos tengan Requires Shipping en Yes.
El cliente no puede elegir un punto de CTT: el selector aparece solo bajo la opción de punto de CTT, y solo cuando la clave pública, la clave privada, el App ID y el Carrier ID están rellenados. Revisa los avisos en la parte superior de la página de configuración, activa el Debug log y mira el campo Log en la página de la extensión.
Las tarifas en tiempo real no aparecen: se usa la tabla de precios hasta que el cliente introduce la calle, el código postal y la ciudad. Revisa los avisos y el registro. Una respuesta "405" significa que la función no está activada para tu App ID: pide a CTT que la active. En una tienda que no usa euros, rellena Exchange rate.
La conexión con la API de CTT falló: el aviso en la parte superior de la página de configuración muestra el error. Revisa las claves y el App ID. La extensión lo vuelve a intentar automáticamente tras unos minutos.
Precios con o sin IVA: con una Tax class seleccionada, OpenCart añade ese impuesto sobre el precio. Con --- None ---, el precio es definitivo.
Los precios parecen desactualizados tras un cambio: haz clic en Save en la página de la extensión. Esto borra las respuestas de CTT guardadas en caché.
La página muestra "Warning: You do not have permission to modify VibeFox CTT!": es posible que el grupo de usuarios de administración solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_ctt (OpenCart 3) o extension/vfd_ctt/shipping/vfd_ctt (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de CTT puede sustituirse con el ajuste vfd_ctt_api_url (para pruebas); no tiene campo en la página de configuración.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox CTT. La clave de licencia y el estado de la licencia de esta extensión se eliminan siempre. OpenCart siempre restablece el estado de la extensión, Sort Order, Tax class y Geo Zone. Las respuestas de CTT en caché y el token de API siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes, el registro y los puntos de CTT de las finalizaciones de compra que nunca se convirtieron en pedidos. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensión. Los puntos de CTT guardados en pedidos siempre se conservan, y los pedidos existentes mantienen su método y coste de envío.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla y haz clic en Uninstall (el botón naranja −) junto a VibeFox CTT en la lista de extensiones instaladas, y luego en Delete (el botón rojo de papelera) para eliminar el paquete subido.
CTT es una marca comercial de su titular. Esta extensión no está afiliada a CTT ni cuenta con su respaldo.