VibeFox SF Express 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 SF Express (solo para precios en tiempo real): los precios en tiempo real usan la plataforma abierta FengQiao de SF Express (open.sf-express.com). Necesitas una cuenta mensual de SF Express y una cuenta de desarrollador en FengQiao. Regístrate allí, crea una aplicación, añade a ella la API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) y copia el código de cliente y el checkword. Los checkwords del sandbox y de producción son distintos. Si solo usas la tabla de precios, no necesitas una cuenta de SF Express.
Provincias chinas (solo para precios en tiempo real): el precio en tiempo real necesita la provincia de la dirección de entrega. PrestaShop no tiene provincias chinas por defecto. El módulo puede añadirlas por ti (véase Chinese provinces más abajo).
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 carga, haz clic en Configure, o busca más tarde VibeFox SF Express en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).
4. Rellena la tabla de precios y/o el coste alternativo y haz clic en Save.
5. Para los precios en tiempo real en China continental, introduce el código de cliente y el checkword, la provincia y la ciudad de origen (o configura una dirección de tienda en China) y, si la moneda de tu tienda no es CNY, el tipo de cambio. Haz clic en Add Chinese provinces si la página lo pide. Prueba primero con Sandbox y las credenciales de sandbox.
Al instalar, el módulo crea el transportista SF Express con el texto de plazo de entrega Courier delivery. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre viene del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox SF Express > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra los precios de SF Express en caché.
Al guardar, el módulo comprueba los números. Un valor que no es un número, un importe o peso negativo, un tipo de cambio de 0, un Min weight superior a Max weight o un precio incorrecto en la tabla de precios se rechaza con un mensaje, y no se guarda nada hasta que lo corrijas. Las advertencias sobre los ajustes te indican cuándo los precios en tiempo real están configurados a medias (se listan los ajustes que faltan), cuándo falta el tipo de cambio, cuándo las direcciones chinas no tienen campo de provincia, o cuándo la unidad de peso o de dimensiones de tu tienda no es conocida por el módulo. Las unidades se configuran en International > Localization (Local units).
General
Enable SF Express: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista que se muestra en el carrito y en la finalización de compra. Por defecto: SF Express. Obligatorio, 64 caracteres como máximo.
Tax: la regla de impuesto del transportista, o No tax. Con una regla de impuesto, el impuesto de envío de tu tienda se añade al coste. Elige No tax si el precio de SF Express ya incluye todo lo que quieres cobrar.
API de SF Express FengQiao (precios en tiempo real) (opcional, para direcciones de entrega en China continental)
Customer code (partnerID): el código de cliente (顾客编码) de tu aplicación de FengQiao. Al borrarlo también se borra el checkword guardado, así puedes eliminar las credenciales.
Checkword: el checkword (校验码) del mismo entorno. Solo se usa para firmar las solicitudes y nunca se envía ni se registra. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Sandbox: usa el sandbox de FengQiao (sfapi-sbox.sf-express.com) para hacer pruebas con credenciales de sandbox. Los precios del sandbox no son reales. Desactívalo en una tienda en producción. Por defecto: desactivado.
SF Express product: qué producto de SF Express se muestra en el precio.
Sender province: la provincia desde la que se envían los paquetes. Déjalo vacío para usar la provincia de la dirección de la tienda en Shop Parameters > Contact > Stores, cuando la tienda está en China.
Sender city: el nombre estándar de la ciudad china, por ejemplo 深圳市. Déjalo vacío para usar la ciudad de la tienda, cuando la tienda está en China.
Currency conversion rate: los precios de SF Express están en CNY (yuanes). Si la moneda por defecto de tu tienda no es CNY, indica cuántas unidades de tu moneda vale un CNY (1 CNY = ? unidades). Sin él, no se usan los precios en tiempo real. Si la moneda de tu tienda es CNY, los precios se usan tal cual. Se aceptan tanto el punto como la coma como separador decimal.
Chinese provinces: indica si las direcciones chinas pueden tener provincia. Si no, haz clic en Add Chinese provinces. El botón añade las 32 provincias, regiones autónomas y municipios como estados de China (códigos ISO como GD y BJ, nombres como "Guangdong / 广东"), activa "Contains states" para China y añade el campo de estado al formulario de dirección chino. Las provincias que ya existen no se vuelven a añadir. Sin este clic no se cambia nada.
Tabla de precios y alternativa (se usa para Hong Kong, Macao, Taiwán y otros países, cuando los precios en tiempo real no están configurados o cuando SF Express no devuelve precio; los precios están en la moneda por defecto de tu tienda, sin impuestos)
Country prices: una tabla con un precio base por país. Haz clic en Add country para añadir una fila y en el icono de papelera para eliminar una. La fila * All other countries se aplica a todos los países sin fila propia. Un precio de tramo de peso superior a 0 sustituye al precio base para los paquetes de ese tramo: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg y XL >5 kg. Un precio base de 0 significa envío gratuito. Un precio base vacío significa que no hay precio para ese país y se usa el coste alternativo. Se aceptan tanto "9.99" como "9,99". Una fila sin ningún precio no se guarda.
Fallback cost: se usa cuando ni SF Express ni la tabla dan un precio. Déjalo vacío para ocultar el transportista en ese caso.
Table / fallback price is: cómo se cobran los precios de la tabla y los alternativos.
Los precios en tiempo real de SF Express siempre se calculan para el pedido completo.
Condiciones
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual el envío es gratuito. Déjalo vacío para no ofrecer nunca envío gratuito. El envío gratuito se comprueba antes de buscar cualquier precio, así que a partir de este importe el transportista se ofrece gratis para cada destino disponible, incluso para un país sin fila en la tabla o sin Fallback cost.
Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Min weight: el peso mínimo del carrito en kg. Los pesos de los productos se convierten desde la unidad de peso de tu tienda. 0 significa sin límite.
Max weight: el peso máximo del carrito en kg. Por defecto: 50. 0 o vacío significa sin límite.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece SF Express para los países indicados abajo, independientemente de la zona que coincida. Al guardar, el transportista se añade a todas las zonas, y también a las zonas que se creen más adelante. Al desactivar la opción, se eliminan las zonas añadidas. Si está desactivada, el transportista aparece solo en sus propias zonas.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países activos. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de precios en logs/vfd_sfex_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. No se escriben el checkword ni las direcciones de los clientes.
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 el módulo se eliminan los ajustes, el transportista, los precios en caché y los registros. Si está desactivado, se conserva todo para una reinstalación.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de SF Express. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el subtotal. El módulo comprueba primero las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. Si el subtotal alcanza Free shipping from, el precio es 0 y no se envía ninguna solicitud a SF Express.
Para una dirección de entrega en China continental con el código de cliente y el checkword configurados, el módulo envía a SF Express la provincia y la ciudad de origen, la provincia y la ciudad del cliente, el peso del carrito y el volumen del carrito (a partir de los productos con las tres dimensiones). La solicitud se firma con tu checkword. SF Express devuelve los precios en CNY, y el módulo convierte el elegido a la moneda por defecto de tu tienda. Después, el precio se muestra en la moneda del carrito del cliente.
SF Express reconoce las direcciones por los nombres chinos estándar. La provincia del cliente se toma del campo de estado de la dirección. La ciudad debe escribirse en chino, por ejemplo 广州市. Para Beijing, Shanghai, Tianjin y Chongqing, la ciudad se rellena automáticamente. Una ciudad escrita con letras latinas, como "Guangzhou", recibe el precio de la tabla.
Cada precio se guarda en caché durante una hora, así 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 SF Express en cada actualización. El tiempo de espera HTTP es de 10 segundos.
Si no hay precio en tiempo real, el precio se toma de la tabla de precios y, después, del Fallback cost. Si no se aplica ninguno, el transportista se oculta. El cliente nunca ve un error. El error se escribe en el registro.
Si editas el 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 solo calcula precios. No crea guías ni etiquetas, no crea pedidos en SF Express, no reserva recogidas, no cancela ni hace seguimiento de envíos. Crea y sigue los envíos en tu cuenta de SF Express como de costumbre. Los clientes no pueden elegir un punto de servicio ni una taquilla de SF. SF Express se usa como mensajería puerta a puerta. Los precios en tiempo real existen solo para direcciones de entrega en China continental. El módulo se desarrolló con la documentación de FengQiao y respuestas simuladas, así que confirma los precios con tu cuenta de SF Express (primero en sandbox) antes de pasar a producción.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox SF Express es el primero de la página Modules > Module Manager > VibeFox SF Express > Configure, por 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-sf-express 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 contactar 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. 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, el transportista SF Express no se muestra a los clientes en la finalización de compra y no se calcula ningún precio. El front office de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un aviso 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 por semana. No hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
SF Express no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable SF Express esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o activa Ignore shipping zones y revisa Countries). Revisa los límites de peso y el Minimum subtotal. Comprueba que la tabla o el Fallback cost tengan un precio para el país. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.
El precio viene de la tabla, no de SF Express: los precios en tiempo real necesitan el código de cliente y el checkword, una provincia y una ciudad de origen, una dirección de entrega en China continental con una provincia y un nombre de ciudad china y (para tiendas que no usan CNY) el tipo de cambio. Lee las advertencias de la parte superior de la página del módulo, después activa Debug log, recarga la finalización de compra y mira el campo Log para ver el motivo. Una solicitud fallida se repite después de 10 minutos.
El formulario de dirección de China no tiene provincia: haz clic en Add Chinese provinces en la sección de la API de la página del módulo.
Error A1006 en el registro: firma no válida. El checkword es incorrecto o pertenece al otro entorno. Revisa el ajuste Sandbox.
Error A1004 en el registro: la API de consulta de precios no está añadida a tu aplicación de FengQiao.
Hong Kong: funciona con la tabla de precios y el coste alternativo. La consulta de precios de FengQiao es solo para direcciones de China continental.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra los precios de SF Express en caché.
La página indica que no se encontró el transportista SF Express: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Para desarrolladores: el hook actionVfdSfExpressQuoteRequest modifica la solicitud de precio, por ejemplo para usar otro código de producto. actionVfdSfExpressApiUrl cambia la URL de la pasarela.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox SF Express y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Los precios en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, o con un Reset, el transportista recupera el estado que tenía antes. Los pedidos existentes conservan sus líneas de envío.
SF Express es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por SF Express.