VibeFox The Courier Guy 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.
Clave API de ShipLogic (para tarifas en tiempo real y lockers): The Courier Guy funciona sobre la plataforma ShipLogic. Crea una clave API en tu portal de mensajería de The Courier Guy, en Settings > API Keys (cuenta empresarial). Sin la clave, solo se usa la tabla de precios y el transportista de locker no se ofrece.
Envío a Sudáfrica: las tarifas en tiempo real y los lockers son solo para direcciones sudafricanas. Sudáfrica debe ser un país activo de la tienda (International > Locations > Countries).
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 The Courier Guy más tarde en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).
4. Introduce la API key de ShipLogic. Para las tarifas en tiempo real, rellena la dirección del remitente (calle, ciudad, provincia, código postal) y, si la moneda de tu tienda no es ZAR, la ZAR conversion rate.
5. Rellena la tabla de precios y/o un coste alternativo y haz clic en Save.
6. Para las tarifas de mensajería en tiempo real, haz clic en Add South African provinces en la sección Advanced si la página indica que las direcciones sudafricanas no tienen provincia.
Al instalarse, el módulo crea dos transportistas: The Courier Guy (texto del plazo de entrega The Courier Guy courier delivery to your door) y The Courier Guy locker (Delivery to a TCG locker of your choice). Ambos están activos, vinculados a la zona de Sudáfrica y a todos los grupos de clientes. Puedes cambiar zonas, grupos de clientes, plazo 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 The Courier Guy > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado borra las tarifas y los lockers en caché y el último error de ShipLogic. Las advertencias de la parte superior de la página te avisan cuando Sudáfrica no es un país activo, falta la clave API, falta la tasa de conversión ZAR o la dirección del remitente, no hay tabla de precios ni coste alternativo, las direcciones sudafricanas no tienen provincia, el módulo no reconoce la unidad de peso o de dimensiones de la tienda, o la última solicitud a ShipLogic ha fallado (con su fecha y error). Un número no válido (por ejemplo, negativo) no se guarda: la página indica el campo y conserva el valor anterior.
General
Courier to the door: activa o desactiva el transportista de mensajería. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Courier carrier name: el nombre del transportista de mensajería en el checkout. Por defecto: The Courier Guy. Obligatorio.
TCG locker: activa o desactiva el transportista de locker. El cliente elige un locker en el checkout. Solo se ofrece para direcciones sudafricanas y solo con la clave API de ShipLogic.
Locker carrier name: el nombre del transportista de locker en el checkout. Por defecto: The Courier Guy locker. Obligatorio.
Tax status: la regla de impuestos de ambos transportistas. Taxable: <tax rule>: las tarifas en tiempo real se toman sin IVA y PrestaShop añade el impuesto de envío de la regla seleccionada. None: las tarifas en tiempo real se toman con IVA incluido.
API de ShipLogic (tarifas en tiempo real y lockers)
API key: tu clave API de ShipLogic del portal de The Courier Guy. 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 si quieres cambiarla. Marca Remove the saved API key y guarda para eliminarla.
Account ID: opcional. El ID numérico de cuenta de ShipLogic, solo si tu clave tiene acceso a varias cuentas. Un valor que no sea numérico no se guarda.
Tarifas en tiempo real (para direcciones sudafricanas; si no hay tarifa en tiempo real disponible, se usa la tabla de precios)
Price source: de dónde procede el precio.
ZAR conversion rate: ShipLogic cotiza en rands sudafricanos (ZAR). Si la moneda predeterminada de tu tienda no es ZAR, indica cuánto vale 1 ZAR en tu moneda, por ejemplo 0.05. Sin este dato, no se usan las tarifas en tiempo real y se aplica la tabla de precios. Si la moneda de tu tienda es ZAR, déjalo vacío. La tasa no se actualiza automáticamente.
Dirección del remitente (para tarifas en tiempo real) (dónde recoge The Courier Guy los paquetes, en Sudáfrica; para las tarifas en tiempo real se necesitan la calle, la ciudad, la provincia y el código postal)
Sender company: el nombre de tu empresa.
Sender street address: por ejemplo, 12 My Road.
Sender suburb: el barrio de la dirección del remitente.
Sender city: la ciudad de la dirección del remitente.
Sender province: elige la provincia sudafricana de la lista.
Sender postal code: el código postal de la dirección del remitente.
Tabla de precios (tus propios precios en la moneda predeterminada de la tienda, sin impuestos: se usa con Price table only, fuera de Sudáfrica y siempre que no haya tarifa en tiempo real; se acepta coma o punto decimal)
Calculation type: se aplica solo a la tabla de precios. Una tarifa en tiempo real siempre es para todo el pedido.
Prices by weight: una tabla de países con una columna Price y los tramos de peso XS (hasta 1 kg), S (hasta 2 kg), M (hasta 3 kg), L (hasta 5 kg) y XL (más de 5 kg). Haz clic en Add row para añadir una fila (una nueva fila empieza con Sudáfrica) y en el icono de la papelera para eliminarla. Un tramo vacío o con 0 usa la columna Price. Un precio de 0 significa envío gratis. La fila * Any country se aplica a los países sin fila propia y a una fila de país sin ningún precio. Un precio que no sea un número se borra, y la página lo indica.
Fallback cost: se usa cuando no hay ni tarifa en tiempo real ni precio en la tabla. Déjalo vacío para ocultar los transportistas en ese caso.
Condiciones (ambos transportistas)
Min weight (kg): oculta los transportistas si el peso del carrito es inferior a este valor. 0 significa sin límite.
Max weight (kg): oculta los transportistas si el peso del carrito es superior a este valor. Por defecto: 30. 0 significa sin límite; vacío significa 30 kg. Si Min weight (kg) es mayor que Max weight (kg), la página muestra una advertencia y ambos límites conservan sus valores anteriores.
Minimum order amount: muestra los transportistas solo a partir de este subtotal del carrito (productos que requieren envío, sin impuestos, después de descuentos). Déjalo vacío para mostrarlos siempre.
Free shipping from: el subtotal del carrito a partir del cual el envío es gratuito. Déjalo vacío para no ofrecer nunca envío gratis. Cuando el subtotal lo alcanza, los transportistas se muestran con un precio de 0 y no se envía ninguna solicitud a ShipLogic para la tarifa.
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 el transportista del tipo de entrega indicado abajo para los países indicados abajo, aunque sus zonas no los incluyan. El transportista se vincula a cada zona activa, también a las zonas creadas más adelante. Al desactivar esta opción, recupera las zonas que tenía antes.
Delivery type without zones: Courier to the door o TCG locker (customer chooses a locker). Solo se usa con Ignore shipping zones.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Los lockers se ofrecen solo en Sudáfrica.
Avanzado
South African provinces: PrestaShop no tiene provincias sudafricanas, pero la tarifa de mensajería en tiempo real necesita la provincia de la dirección. Add South African provinces añade las 9 provincias (EC, FS, GP, KZN, LP, MP, NC, NW, WC) como estados de Sudáfrica y muestra el campo de estado en las direcciones sudafricanas. Las provincias que ya existen no se vuelven a añadir. Hasta entonces, la mensajería recibe el precio de la tabla.
Debug log: escribe mensajes de depuración en logs/vfd_tcgr_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, incluso con esta opción desactivada. La clave API y los datos 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á activada, al desinstalar el módulo se eliminan sus ajustes y transportistas. Si está desactivada, al desinstalar solo se desactivan los transportistas. Los lockers guardados en los pedidos siempre se conservan.
Cómo funciona en el checkout
En el paso de envío, PrestaShop pide al módulo el precio de cada transportista. 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 las condiciones: peso del carrito e importe mínimo del pedido. Si se aplica envío gratis, el precio es 0.
Courier to the door: el módulo pide a ShipLogic el servicio más barato desde tu dirección de remitente hasta la del cliente. La dirección debe tener calle, ciudad, provincia y código postal. Hasta entonces se usa la tabla de precios.
TCG locker: la tarifa en tiempo real es el servicio más barato de puerta a locker hasta el locker más cercano a la ciudad del cliente. No se recalcula para el locker que elija el cliente. El transportista de locker solo aparece para direcciones sudafricanas y solo con la clave API.
El pedido completo se cotiza como un único paquete: el peso total, la longitud y la anchura máximas, y las alturas apiladas. Los productos sin dimensiones cuentan como cubos de 10 cm. Los pesos y las dimensiones se convierten desde las unidades de tu tienda. El importe en rands se convierte a la moneda predeterminada y después se muestra en la moneda del carrito del cliente.
Las solicitudes a ShipLogic caducan a los 12 segundos. Las tarifas se guardan en caché durante 1 hora, los lockers durante 6 horas y los errores durante 10 minutos, para que una API lenta no ralentice cada actualización del checkout. Si no hay tarifa en tiempo real, el precio procede de la tabla y, después, de Fallback cost. Si no se aplica ninguno, el transportista se oculta. Los errores de la API nunca se muestran al cliente.
Los transportistas funcionan con los temas Classic y Hummingbird. 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.
El módulo no reserva envíos, no crea guías ni etiquetas y no actualiza el seguimiento automáticamente. No hay mapa de lockers: los lockers se eligen de una lista. Las tarifas en tiempo real y los lockers son solo para Sudáfrica. Otros países reciben la tabla de precios. Solo se muestra una tarifa por transportista (el nivel de servicio más barato), sin posibilidad de elegir niveles de servicio, seguro ni extras en el checkout.
Puntos de recogida
Cuando el cliente elige el transportista de locker, aparece un selector de lockers debajo. Muestra los lockers que ShipLogic devuelve para la ciudad de la dirección de entrega, del más cercano al más lejano. El cliente puede escribir otra ciudad, barrio o código postal y hacer clic en Search. Hay que elegir un locker antes de poder continuar: de lo contrario, el paso de envío muestra Please choose a The Courier Guy locker.
El locker se vuelve a comprobar en el servidor contra la lista de ShipLogic, también al realizar el pedido. Su nombre y proveedor se toman de ShipLogic, nunca del navegador. La elección se guarda en el carrito y se restablece cuando cambia la dirección de entrega.
Si no se puede acceder a ShipLogic, el selector indica que no se pueden cargar los lockers y que la tienda se pondrá en contacto con el cliente sobre el locker. El pedido puede realizarse entonces sin locker. Se marca en la página de pedido del administrador: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.
Pedidos
El locker elegido (nombre, ID y proveedor) se guarda con el pedido. Aparece en el bloque The Courier Guy de la página de pedido del administrador, en la página de confirmación del pedido, en los detalles del pedido del cliente y en el correo de confirmación del pedido. El correo de "nuevo pedido" de la tienda (módulo Mail alerts) también muestra el ID del locker, o que no se eligió ningún locker porque ShipLogic no estaba disponible.
Número de seguimiento de The Courier Guy: reserva el paquete en tu portal de The Courier Guy e introduce la referencia como número de seguimiento del envío en el bloque Shipping del pedido (Edit). El bloque The Courier Guy lo muestra. El cliente lo ve en los detalles del pedido y recibe el correo "en tránsito" de PrestaShop.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox The Courier Guy es el primer bloque de Modules > Module Manager > VibeFox The Courier Guy > Configure, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-the-courier-guy 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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al 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. 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 en el checkout ninguno de los transportistas de The Courier Guy (courier to the door o TCG locker) y no se calcula ninguna tarifa. El escaparate 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 el checkout. 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 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 tras introducir la clave, y después una vez a la semana. No se necesita ninguna tarea cron. Al desinstalar el módulo siempre se elimina la clave de licencia y el estado de la licencia. Reset de este módulo no borra datos, así que la clave y el estado se conservan.
Solución de problemas
The Courier Guy no aparece en el checkout: comprueba que la licencia esté activa y que el transportista esté activado (Courier to the door o TCG locker). En Shipping > Carriers, comprueba que el transportista cubra 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). Revisa los límites de peso y el Minimum order amount. Comprueba que la tabla o el Fallback cost tengan un precio. El transportista de locker solo aparece para direcciones sudafricanas y con la clave API. Además, los productos pueden limitarse a determinados transportistas en la página del producto.
Los clientes no ven la lista de lockers: los lockers necesitan la clave API, el transportista TCG locker activado y una dirección de entrega en Sudáfrica. La página de ajustes muestra el último error de ShipLogic, si lo hay, por ejemplo una clave rechazada.
El precio es siempre el de la tabla: revisa las advertencias de la página de ajustes. Una tarifa en tiempo real necesita la clave API, la dirección completa del remitente y, en tiendas que no usan rands, la tasa de conversión ZAR. Para la entrega a domicilio, la dirección del cliente necesita calle, ciudad, provincia y código postal: añade las provincias sudafricanas en la sección Advanced. Para los lockers, ShipLogic debe encontrar un locker cerca de la ciudad del cliente. Activa el Debug log, recarga el checkout y consulta el campo Log de la página del módulo.
ShipLogic no funciona: se muestra el precio de la tabla o el coste alternativo. Los pedidos con locker pueden realizarse sin locker y se marcan en el pedido.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las tarifas y los lockers en caché.
La página indica que no se encontró un transportista de The Courier Guy: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo. Restablecer conserva tus ajustes y el estado de activación de los transportistas existentes.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox The Courier Guy y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las tarifas y los lockers en caché y el último error de ShipLogic siempre se eliminan. Si Remove data on uninstall está activado, los transportistas se eliminan (los pedidos conservan su historial) y se eliminan los ajustes, el registro y los lockers de los carritos sin pedido. Si está desactivado, los transportistas solo se desactivan y se conservan todos los ajustes. Al volver a instalar el módulo, los transportistas recuperan el estado que tenían. Los lockers guardados en los pedidos nunca se eliminan.
The Courier Guy y ShipLogic son marcas comerciales de sus respectivos propietarios. Este módulo no está afiliado ni respaldado por The Courier Guy ni por ShipLogic.