VibeFox CTT for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Cuenta de comercio electrónico de CTT (solo para tarifas en vivo y puntos CTT): las tarifas en vivo y la entrega en un punto 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 CTT) puede usar tu App ID. Por último, necesitas el Carrier ID de CTT en tu cuenta. La página de ajustes muestra los transportistas de tu cuenta una vez guardadas las claves. Si solo usas la tabla de precios y la entrega a domicilio, no necesitas claves de API.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_ctt a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox CTT, o haz clic en Settings debajo del nombre del plugin en la página Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Rellena la tabla de precios (al menos una fila Portugal o * Default). Opcionalmente, rellena las claves de API de CTT y el Carrier ID y activa Live rates (ver Configuración).
6. En WooCommerce > Settings > Shipping > Shipping zones, abre o crea una zona para Portugal y añade VibeFox CTT. En los ajustes del método elige el título y el tipo de entrega. O activa Ignore shipping zones y elige los países.
Configuración
Los precios, las claves de API y las condiciones están en una sola página: WooCommerce > Settings > Shipping > VibeFox CTT. Se aplican a todas las zonas de envío. Cuando añades el método a una zona, la ventana de la zona tiene dos campos:
Title (zone): el nombre de esta opción en la finalización de compra en esta zona. Déjalo vacío para usar el Name global.
Delivery: To the customer's address (por defecto) o To a CTT point or parcel locker chosen at checkout. Un punto CTT necesita las claves de API de CTT y el Carrier ID en los ajustes globales. Añade el método dos veces a una zona para ofrecer entrega a domicilio y entrega en un punto CTT una al lado de la otra.
Las advertencias sobre los ajustes te avisan de un precio que falta para Portugal, claves de API incompletas, un Carrier ID que falta, una moneda de la tienda sin tipo de cambio y una conexión fallida con la API de CTT. Cada vez que guardas los ajustes, se borran las respuestas de CTT guardadas en caché.
General
Enable/Disable: activa o desactiva el método en todas las zonas a la vez.
Name: el nombre del método de envío que se muestra en la finalización de compra, por ejemplo "CTT Expresso". Por defecto: CTT. El Title de una zona lo sustituye.
Tax status: Taxable añade el impuesto de envío de WooCommerce (por ejemplo, IVA) sobre el precio; None significa que el precio es final.
API de comercio electrónico de CTT (tarifas en vivo, puntos 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 petición (HMAC-SHA256). Nunca se envía a CTT ni se escribe en el registro.
App ID (X-APPID): la clave de aplicación que CTT emite para tu integración.
Carrier ID: el ID del transportista de CTT en tu cuenta, que se usa para las tarifas en vivo y la búsqueda de puntos CTT. Una vez guardadas las claves, los transportistas de tu cuenta aparecen debajo del campo, y los que admiten puntos CTT están marcados.
Live rates: pide a CTT el precio (estimación de coste) cuando 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 llama 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 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): longitud x anchura x altura que se envían 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 a partir de las unidades de tu tienda.
Precios (el título de la sección muestra la moneda de tu tienda)
Introduce los precios de tu contrato con CTT o de la lista pública de precios de CTT, en la moneda de tu tienda. Con las tarifas en vivo desactivadas, esta tabla fija el precio. Con las tarifas en vivo activadas, es la 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 precio base (Price) 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 Azores se usa para los códigos postales portugueses 9500-9999; la 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 × para eliminar una. Los precios aceptan punto o coma decimal. Las filas no válidas se notifican al guardar.
Calculation: cómo se encuentra el precio de la tabla.
Un precio de CTT en vivo siempre es para el envío completo.
Condiciones
Min weight (kg): el peso mínimo del carrito para que aparezca el método. 0 significa sin límite.
Max weight (kg): el método se oculta por encima de este peso del carrito. Por defecto: 30 (los paquetes de CTT llegan hasta 30 kg). 0 significa sin límite.
Minimum order amount: muestra el método solo cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Excluded shipping classes: oculta el método cuando algún artículo del carrito pertenece a una de estas clases de envío de WooCommerce.
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, antes de impuestos) a partir del cual este método cuesta 0. Solo se aplica cuando el método tiene un precio. Se usa solo cuando Free shipping está activado.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece el método en los países indicados abajo cuando la zona del cliente no lo contiene.
Countries: los países de destino para ese modo. Por defecto: Portugal. Déjalo vacío para usar todos los países a los que envías. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra el cálculo de precios y las llamadas a la API de CTT en WooCommerce > Status > Logs, origen vfd-ctt. Los errores de la API de CTT siempre se registran, aunque esta opción esté desactivada. Las claves, los tokens y las direcciones de los clientes nunca se registran.
Remove data on uninstall: cuando está activado, al borrar el plugin se eliminan sus ajustes y sus métodos de zona. Desactivar el plugin nunca borra datos. Los pedidos nunca se modifican.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, WooCommerce pide al plugin un precio. Primero, el plugin comprueba el peso del carrito, el importe mínimo del pedido y las clases de envío excluidas. 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 muestra el precio devuelto. En caso contrario, o cuando CTT no devuelve ningún precio (error de la API, tiempo de espera agotado, sin cobertura, una función no activada para tu App ID), el precio sale de la tabla. Si se aplica el envío gratuito, el precio es 0.
Un precio de CTT se guarda en caché durante 1 hora, para que el mismo carrito no genere una nueva petición. Una petición 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.
El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con High-Performance Order Storage (HPOS) de WooCommerce.
Con las claves de API rellenadas, el plugin 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 CTT más cercanos.
El plugin no crea envíos, no imprime etiquetas, no solicita recogidas, no proporciona números de seguimiento ni muestra un mapa de puntos CTT. Hay una sola tabla de precios y un solo conjunto de ajustes de API para toda la tienda. Las zonas se diferencian por título y tipo de entrega.
Puntos de recogida
Para un método de zona con Delivery en un punto CTT, aparecen debajo del método, en la finalización de compra, un campo de búsqueda y una lista. La dirección de entrega se busca automáticamente. El cliente puede buscar otros puntos CTT por código postal o ciudad y debe elegir uno antes de realizar el pedido. Esto también se comprueba en el servidor. Las listas de puntos CTT se guardan en caché durante 6 horas. Si no se puede contactar con CTT, el cliente ve un mensaje y puede volver a intentarlo más tarde o elegir otro método de envío.
El punto elegido se guarda en el pedido. Se muestra en la administración del pedido, debajo de la dirección de envío, en la página de pedido recibido, en My account > Orders y en los correos del pedido (HTML y texto plano) como CTT point.
En la administración del pedido, haz clic en Change junto al punto CTT, busca por código postal o ciudad y elige otro punto. El cambio se guarda al momento y añade una nota al pedido.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox CTT. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Eliminar la clave de un sitio 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. Los gestores de la tienda que han iniciado sesión sí lo ven, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
CTT no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el método esté añadido a la zona del país del cliente (o que Ignore shipping zones esté activado y el país permitido). 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 ningún producto pertenezca a una clase de envío excluida.
El cliente no puede elegir un punto CTT: el selector aparece solo para un método de zona con Delivery en un punto CTT, y solo cuando la clave pública, la clave privada, el App ID y el Carrier ID están rellenados. Activa el Debug log y revisa WooCommerce > Status > Logs.
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 sobre los ajustes y el registro. La respuesta "405" significa que la función no está activada para tu App ID: pregunta a CTT. En una tienda que no usa euros, rellena Exchange rate.
La conexión con la API de CTT ha fallado: la advertencia sobre los ajustes muestra el error. Revisa las claves y el App ID. El plugin vuelve a intentarlo automáticamente al cabo de unos minutos.
Precios con o sin IVA: con Tax status en Taxable, WooCommerce añade el impuesto de envío sobre el precio. Con None, el precio es final.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan, al igual que las respuestas de CTT guardadas en caché y el token de API. Los ajustes y los métodos de zona solo se eliminan si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos, incluido el punto CTT elegido, nunca se modifican, y los pedidos existentes conservan sus líneas de envío.
CTT es una marca comercial de su respectivo titular. Este plugin no está afiliado ni respaldado por CTT.