VibeFox CTT 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 comercio electrónico de CTT (solo para tarifas en vivo y puntos de CTT): las tarifas en vivo 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 solicita 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: pregúntaselo 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 de 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
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 CTT 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 del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Rellena la tabla de precios (como mínimo, una fila Portugal o * Default) y haz clic en Save. Opcionalmente, rellena las claves de API de CTT y el Carrier ID, y activa Live rates y Enable CTT point carrier (ver Configuración).
Al instalar, el módulo crea dos transportistas. CTT (entrega en la dirección del cliente, con el texto de tiempo de entrega CTT delivery to your address) está activado. CTT point / parcel locker (con el texto de tiempo de entrega Pickup at a CTT point or parcel locker) está desactivado hasta que lo actives. Ambos están vinculados a la zona de Portugal y a todos los grupos de clientes. Puedes cambiar zonas, grupos de clientes, tiempo de entrega, logotipo y 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 CTT > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Los precios y las condiciones se aplican a ambos transportistas de CTT. Cada guardado borra las respuestas de CTT en caché, incluidos el token de API y las listas de puntos de CTT.
Las advertencias situadas encima de los ajustes te informan de una tabla de precios vacía, de un precio que falta para Portugal, de claves de API incompletas, de un Carrier ID que falta, de una moneda de la tienda distinta de EUR sin tipo de cambio, de un fallo de conexión con la API de CTT y de un transportista de CTT eliminado. Los valores no válidos se notifican al guardar: un número no válido no se guarda, y un destino desconocido o una fila duplicada en la tabla de precios se elimina. Si el módulo no reconoce la unidad de peso o de dimensiones de tu tienda, una advertencia te pide que configures las unidades en International > Localization (Local units).
General
Enable/Disable: activa o desactiva la entrega de CTT en la dirección del cliente. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del transportista que ve el cliente en la finalización de compra, por ejemplo "CTT Expresso". Por defecto: CTT. Obligatorio, hasta 64 caracteres.
Tax status: None significa que los precios son definitivos. Taxable con una regla de impuesto significa que PrestaShop añade ese impuesto de envío (por ejemplo, IVA) sobre los precios. La elección se guarda en ambos transportistas de CTT.
Entrega en un punto de CTT o taquilla automática
El segundo transportista de CTT. El cliente busca puntos de CTT por código postal o ciudad y debe elegir uno antes de continuar. Necesita las claves de API de CTT y el Carrier ID. Sin ellos, es un transportista sin selección de punto.
Enable CTT point carrier: activa o desactiva el transportista de puntos de CTT. Es el mismo interruptor que su estado en Shipping > Carriers. Por defecto: desactivado.
CTT point carrier name: el nombre de esta opción en la finalización de compra. Por defecto: CTT point / parcel locker. Obligatorio, hasta 64 caracteres.
API de comercio electrónico de CTT (tarifas en vivo, 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 que se usa para firmar cada solicitud (HMAC-SHA256). Nunca se envía a CTT ni se escribe en el registro.
Ambas claves no se vuelven a mostrar tras guardarlas. La descripción del campo indica entonces Saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlas. Marca Remove the saved public and private key y guarda para eliminar ambas.
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 vivo y la búsqueda de puntos de CTT. Una vez guardadas las claves y el App ID, los transportistas de tu cuenta aparecen en una lista bajo el campo, y los que admiten puntos de CTT se marcan con (CTT points). Solo números.
Live rates: el módulo 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. Mientras la dirección esté incompleta, o siempre que CTT no devuelva un precio, se usa la tabla de precios. CTT denomina a este precio una estimación. Por defecto: desactivado.
Service ID: opcional. Cuando CTT devuelve varios servicios, se usa el que tenga 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 dato, las tarifas en vivo en otra moneda no se usan y se aplica la tabla de precios.
Default product size (cm): largo x ancho x alto que se envía a CTT para los productos sin dimensiones. Por defecto: 30x20x15. Los productos con dimensiones usan las suyas. Las dimensiones se convierten a cm y los pesos a gramos según las unidades de tu tienda.
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 vivo desactivadas, esta tabla define el precio. Con las tarifas en vivo activadas, es la tarifa alternativa.
Price table: una fila por destino. Elige un país, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) 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 con ambos campos vacíos oculta el transportista. La fila de Azores se usa para los códigos postales portugueses 9500-9999, y la fila de Madeira (incluido Porto Santo) para 9000-9499. Sin ellas se aplica la fila Portugal. Haz clic en Add destination para añadir una fila y en el icono de papelera para eliminarla. Los precios aceptan punto o coma decimal. La tabla está vacía tras la instalación.
Calculation: cómo se encuentra el precio de la tabla.
Un precio de CTT en vivo siempre corresponde a todo el envío.
Condiciones
Min weight (kg): el peso mínimo del carrito para que aparezcan los transportistas. 0 significa sin límite.
Max weight (kg): los transportistas se ocultan por encima de este peso del carrito. Por defecto: 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): los ajustes no se guardan.
Minimum order amount: muestra los transportistas solo cuando el subtotal del carrito (productos que necesitan envío, después de descuentos y antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlos siempre.
Envío gratuito
Free shipping: activa la entrega gratuita de CTT a partir del importe indicado abajo.
Free shipping from: el subtotal del carrito (después de descuentos y antes de impuestos) a partir del cual los transportistas cuestan 0. Solo se aplica a los destinos que tienen precio. Se usa solo cuando Free shipping está activado.
Disponibilidad sin zonas de envío
Normalmente, los transportistas se ofrecen en las zonas de envío a las que están vinculados en Shipping > Carriers.
Ignore shipping zones: ofrece los transportistas en los países indicados abajo sin vincularlos a su zona. Al activarlo, ambos transportistas se vinculan a todas las zonas activas (también a las zonas que crees más adelante). Al desactivarlo, recuperan las zonas que tenían antes.
Countries: los países de destino para ese modo. Por defecto: Portugal. Déjalo vacío para permitir todos los países. Se usa solo cuando Ignore shipping zones está activado. Los clientes de las zonas que tenían antes los transportistas siempre reciben servicio.
Avanzado
Debug log: registra el cálculo de precios y las llamadas a la API de CTT en logs/vfd_ctt_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API de CTT siempre se registran, incluso con esta opción desactivada. Las claves, los tokens y las direcciones de los clientes 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 borran sus ajustes y sus transportistas. Si está desactivado, al desinstalar solo se desactivan los transportistas. Los pedidos, incluido el punto de CTT elegido, nunca se modifican.
Cómo funciona la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de cada transportista de CTT. Solo cuentan los productos físicos: los productos virtuales no suman peso ni se incluyen en el importe del pedido. El módulo comprueba primero Ignore shipping zones y sus países, 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 devuelve ningún precio (error de API, tiempo de espera agotado, sin cobertura, una función no habilitada para tu App ID), el precio sale de la tabla. Si se aplica el envío gratuito, el precio es 0. El precio se calcula en la moneda predeterminada de tu tienda y luego se muestra en la moneda del carrito del cliente.
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 tiempo de espera de la API es de 12 segundos. Los errores de la API nunca llegan al cliente: se usa el precio de la tabla o se oculta el transportista si el destino no tiene precio.
Si editas un 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.
Con las claves de API rellenadas, el módulo envía a CTT la dirección de entrega, los pesos y las dimensiones de los productos y la URL de tu tienda para obtener un precio o los puntos de CTT más cercanos.
El módulo no crea envíos, no imprime etiquetas, no solicita recogidas, no proporciona números de seguimiento ni muestra un mapa de puntos de CTT. Hay una sola tabla de precios y un solo conjunto de ajustes de API para ambos transportistas.
Puntos de recogida
Cuando el cliente selecciona el transportista de puntos de CTT, 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 o Intro) y elegir uno de la lista. La elección se guarda en el carrito al instante. Solo se acepta un punto de la lista de CTT para esa búsqueda.
Hay que elegir un punto antes de que el cliente pueda continuar. Cuando el cliente hace clic en Continue en el paso de envío, el módulo vuelve a comprobar 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, ve The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Las listas de puntos de CTT se guardan en caché durante 6 horas. 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.
El selector de puntos funciona con los temas Classic y Hummingbird. Solo está activo cuando están rellenas la clave pública, la clave privada, el App ID y el Carrier ID.
El punto elegido se guarda en el pedido. Se muestra en la página de administración del pedido, en el bloque CTT point (nombre e ID), en la página de confirmación del pedido, en los detalles del pedido de la cuenta del cliente y en el correo electrónico de confirmación del pedido como CTT point: junto al nombre del transportista. El nuevo correo de pedido del módulo Mail alerts también muestra el ID del punto.
En la página de administración del pedido, 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. y se añade un mensaje privado del pedido, CTT point changed to:, con el nuevo punto. Cambiar el punto requiere permiso para editar pedidos.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox CTT es el primero de la página Modules > Module Manager > VibeFox CTT > Configure, 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-ctt 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 (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 conectar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un 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, no se muestra a los clientes ninguno de los dos transportistas de CTT (entrega en la dirección o en un punto de CTT) 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 los transportistas también se ocultan 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 necesitan 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
CTT no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable (o Enable CTT point carrier) 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 está permitido. Comprueba que el destino tiene una fila en la tabla de precios (o una fila * Default), que el peso del carrito está dentro de Min weight y Max weight y que se alcanza el Minimum order amount. En la página del producto también se pueden limitar los productos a ciertos transportistas.
El cliente no puede elegir un punto de CTT: el selector aparece solo debajo del transportista de puntos de CTT, y solo cuando la clave pública, la clave privada, el App ID y el Carrier ID están rellenos. Revisa las advertencias encima de los ajustes, activa Debug log y mira el campo Log en la página del módulo.
Las tarifas en vivo no aparecen: se usa la tabla de precios hasta que el cliente ha introducido la calle, el código postal y la ciudad. Revisa las advertencias encima de los ajustes y el registro. Una respuesta "405" significa que la función no está habilitada para tu App ID: pregúntalo a CTT. En una tienda que no usa euros, rellena Exchange rate.
La conexión con la API de CTT falló: la advertencia encima de los ajustes muestra el error. Revisa las claves y el App ID. El módulo vuelve a intentarlo automáticamente tras unos minutos.
Precios con o sin IVA: con Tax status en una regla Taxable, PrestaShop añade el impuesto de envío sobre el precio. Con None, el precio es definitivo.
Los precios parecen desactualizados tras un cambio: haz clic en Save en la página del módulo. Esto borra las respuestas de CTT en caché.
La página indica que no se encontró un transportista de CTT: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo. Un restablecimiento conserva los ajustes y el estado activado/desactivado de ambos transportistas.
Para desarrolladores: la dirección de la API de CTT se puede cambiar con la clave de configuración vfd_ctt_API_URL.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox CTT y elige Uninstall. La clave de licencia, el estado de la licencia, las respuestas de CTT en caché y el token de API siempre se eliminan. Si Remove data on uninstall está activado, se eliminan ambos transportistas (los pedidos conservan su historial), así como los ajustes, el registro y los puntos de CTT de los carritos que nunca se convirtieron en pedidos. Si está desactivado, los transportistas solo se desactivan y se conservan todos los ajustes. Al volver a instalar el módulo, cada transportista recupera el estado activado/desactivado que tenía. Los puntos de CTT guardados en los pedidos siempre se conservan.
CTT es una marca comercial de su respectivo propietario. Este módulo no está afiliado ni respaldado por CTT.