VibeFox SF Express 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 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 de 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, que es la zona de OpenCart (Region / State) de la dirección. OpenCart tiene las zonas de China, pero falta Tíbet. La extensión puede añadirla por ti (ver Chinese provinces más abajo).
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_sf_express-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_sf_express.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 el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_sf_express-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 del paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox SF Express y haz clic en Install (el botón verde +).
3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes.
4. Introduce tu clave de licencia de VibeFox en License key, en el 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 y/o el coste de reserva.
6. 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 y, si la moneda de tu tienda no es CNY, el tipo de conversión de moneda. Haz clic en Add Chinese provinces si la página lo pide. Prueba primero con Sandbox y credenciales de sandbox.
7. Activa Enable SF Express y haz clic en Save.
OpenCart 4
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_sf_express.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 SF Express, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).
4. Introduce la clave de licencia y los ajustes como en los pasos 4 a 7 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable SF Express y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de SF Express que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. Las secciones aparecen a la izquierda. Se aplican a todas las zonas geo. Un botón Save al final guarda toda la página sin recargarla. Cada guardado también borra los precios de SF Express en caché. Solo los administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
Al guardar, la extensión comprueba los valores. Un título de método vacío, de más de 64 caracteres o con los caracteres < > ; = # { }, un valor que no sea un número, un importe o un peso negativo, un tipo de conversión de moneda de 0, un Min weight (kg) mayor que Max weight (kg), un precio incorrecto en la tabla de precios o un orden de clasificación que no sea un número entero se rechazan con un mensaje, y no se guarda nada hasta que lo corrijas. Los avisos que aparecen sobre los ajustes te indican cuándo los precios en tiempo real están configurados solo en parte (se enumeran los ajustes que faltan), cuando falta el tipo de conversión de moneda, cuando la tienda no tiene zonas de China, o cuando la tienda no tiene una clase de peso en kg o una clase de longitud en cm y su unidad predeterminada no es conocida por la extensión.
General
Enable SF Express: muestra u oculta SF Express en la finalización de compra. Predeterminado: desactivado.
Method title: el nombre del método que se muestra en el carrito y en la finalización de compra. Predeterminado: SF Express. Obligatorio, 64 caracteres como máximo.
Tax class: la clase de impuesto del coste de envío, o No tax. Con una clase de impuesto, se añade a este coste el impuesto de envío de tu tienda. Elige No tax si el precio de SF Express ya incluye todo lo que quieres cobrar.
Sort order: la posición de SF Express entre los métodos de envío de la finalización de compra. Un número entero.
API FengQiao de SF Express (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 peticiones y nunca se envía ni se registra. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.
Sandbox: usa el entorno de pruebas de FengQiao (sfapi-sbox.sf-express.com) para probar con credenciales de sandbox. Los precios de sandbox no son reales. Desactívalo en una tienda en producción. Predeterminado: desactivado.
SF Express product: qué producto de SF Express se muestra con su precio.
Sender province: la provincia desde la que se envían los paquetes, por ejemplo Guangdong / 广东. La primera opción usa la región de tu tienda (System > Settings > Store > Local) cuando la tienda está en China. Después muestra Same as the store region con el nombre de la provincia; en caso contrario, — Select —.
Sender city: el nombre estándar en chino de la ciudad, por ejemplo 深圳市. Obligatorio para los precios en tiempo real: la dirección de la tienda en OpenCart es texto libre, así que la ciudad nunca se toma de ella.
Currency conversion rate: los precios de SF Express están en CNY (yuanes). Si la moneda predeterminada de tu tienda no es CNY, introduce cuántas unidades de tu moneda vale un CNY (1 CNY = ? unidades), por ejemplo 0.13. Sin él, no se usan los precios en tiempo real. Si la moneda de tu tienda es CNY, el campo indica que no es necesario y los precios se usan tal cual. Se aceptan tanto el punto como la coma como separador decimal.
Chinese provinces: muestra cuántas de las 32 provincias, regiones autónomas y municipios de SF Express son zonas de China en OpenCart, y cuáles faltan. Las direcciones de una provincia que falta obtienen el precio de la tabla. Haz clic en Add Chinese provinces para añadir solo las que faltan como zonas de China (código ISO, un nombre como "Tibet / 西藏"). Las zonas existentes no se modifican. Nada cambia sin este clic. Las zonas añadidas así se conservan en la tienda tras una desinstalación.
Tabla de precios y reserva (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 predeterminada 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 botón de eliminar para borrar una. La fila * All other countries se aplica a todos los países que no tengan fila propia. Un precio de tramo de peso mayor que 0 sustituye al precio base para los paquetes de ese tramo: XS hasta 1 kg, S hasta 2 kg, M hasta 3 kg, L hasta 5 kg y XL por encima de 5 kg. Un precio Base de 0 significa envío gratuito. Un precio base vacío significa que no hay precio para este país y se usa el coste de reserva. 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 método en ese caso.
Table / fallback price is: cómo se cobran los precios de tabla y de reserva.
Los precios en tiempo real de SF Express siempre se calculan para el pedido completo.
Condiciones
Free shipping from: el subtotal del carrito (productos que requieren envío, después del cupón, 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 desde este importe el método se ofrece gratis para cualquier destino en el que esté disponible, incluso un país sin fila en la tabla o sin Fallback cost.
Minimum subtotal: muestra el método solo cuando el subtotal del carrito alcanza este importe. Déjalo vacío para mostrarlo siempre.
Min weight (kg): el peso mínimo del carrito en kg. Los pesos de los productos se convierten desde su clase de peso. 0 significa sin límite.
Max weight (kg): el peso máximo del carrito en kg. Predeterminado: 50. 0 o vacío significa sin límite.
Geo zone: ofrece SF Express solo para direcciones de esta zona geo. All zones (predeterminado) significa sin límite. Las zonas geo se gestionan en System > Localisation > Geo Zones. No se comprueba cuando Ignore shipping zones está activado.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece SF Express para los países indicados abajo, sea cual sea la zona geo. Si está desactivado, decide la zona geo y no se usa la lista de países.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países activados. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de precios en storage/logs/vfd_sfex_debug.log.php. El archivo no se puede leer 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. Cuando el archivo alcanza 5 MB, se mueve a vfd_sfex_debug.old.log.php y se inicia un registro nuevo.
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 la extensión se borran los ajustes y el registro. Si está desactivado (predeterminado), los ajustes se conservan para una reinstalación. Los precios en caché siempre se borran.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON, sin el checkword.
Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Los valores se comprueban como en un guardado normal. Se conserva el checkword guardado.
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 SF Express. Si hay una Geo zone configurada y la dirección está fuera de ella, SF Express no se ofrece (salvo que Ignore shipping zones esté activado). Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no se incluyen en el subtotal. El subtotal es el precio de estos productos después del descuento del cupón y antes de impuestos. Los vales de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. La extensión comprueba después 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 petición a SF Express.
Para una dirección de entrega en China continental con código de cliente y checkword configurados, la extensión envía a SF Express tu provincia y ciudad de origen, la provincia y ciudad del cliente, el peso del carrito (al menos 0,1 kg) y el volumen del carrito (de los productos con las tres dimensiones). La petición se firma con tu checkword. SF Express devuelve los precios en CNY; la extensión convierte el elegido a la moneda predeterminada de tu tienda y lo redondea a sus decimales. Después, el precio se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada.
SF Express reconoce las direcciones por sus nombres estándar en chino. La provincia del cliente procede de la zona Region / State de la dirección, identificada por su nombre. La zona "Hong Kong" no es una provincia de China continental y obtiene el precio de la tabla. La ciudad debe escribirse en chino, por ejemplo 广州市. Para Pekín, Shanghái, Tianjin y Chongqing la ciudad se rellena automáticamente. Una ciudad escrita en letras latinas, como "Guangzhou", obtiene el precio de la tabla.
Cada precio se guarda en caché durante una hora, para que el mismo carrito no genere una nueva petición. Una petición 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 procede de la tabla de precios y, después, del Fallback cost. Si no se aplica ninguno, el método se oculta. El cliente nunca ve un error. El error se escribe en el registro.
La extensión solo calcula precios. No crea guías ni etiquetas, no crea pedidos en SF Express, no reserva recogidas, ni cancela o rastrea envíos. Crea y rastrea los envíos en tu cuenta de SF Express como de costumbre. Los clientes no pueden elegir un punto de servicio ni un casillero de SF. SF Express se usa como mensajería puerta a puerta. Los precios en tiempo real solo existen para direcciones de entrega en China continental. La extensión se creó 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.
En OpenCart 4 el cliente pulsa Choose en el bloque de métodos de envío de la página de finalización de compra y elige SF Express en la ventana Shipping method options, donde se muestra el título del método con el precio. El método funciona igual que en OpenCart 3.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox SF Express es el primer bloque de Extensions > Extensions > Shipping > VibeFox SF Express > Edit, por 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-sf-express y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de 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 contactar 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. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el método de envío de SF Express no se muestra a los clientes en la finalización de compra y no se calcula ningún precio. Un usuario administrador que haya iniciado sesión en el panel de 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 del administrador, así que sin una clave activa el método queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del administrador. 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 requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del administrador: 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 es necesario ningún cron job. Desinstalar la extensión 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. Revisa Geo zone o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y Minimum subtotal. Comprueba que la tabla o el Fallback cost tengan precio para el país. Comprueba que los productos tengan Requires Shipping en Yes.
El precio procede de la tabla, no de SF Express: los precios en tiempo real necesitan el código de cliente y el checkword, una provincia y ciudad de origen, una dirección de entrega en China continental con provincia y un nombre de ciudad en chino, y (en tiendas que no usan CNY) el tipo de conversión de moneda. Lee los avisos de la parte superior de la página de la extensión, luego activa el Debug log, recarga la finalización de compra y mira el campo Log para ver el motivo. Una petición fallida se reintenta después de 10 minutos.
El registro muestra un error de firma: el checkword es incorrecto o pertenece al otro entorno. Revisa el ajuste Sandbox. Si SF Express indica que la API no está permitida, añade la API de consulta de precios a tu aplicación de FengQiao.
Las direcciones de Tíbet obtienen el precio de la tabla: haz clic en Add Chinese provinces en la sección de API de la página de la extensión.
Hong Kong: funciona con la tabla de precios y el coste de reserva. La consulta de precios de FengQiao es para direcciones de China continental.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra los precios de SF Express en caché.
La página dice "Warning: You do not have permission to modify VibeFox SF Express!": tu grupo de usuarios de administración solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_sf_express (OpenCart 3) o extension/vfd_sf_express/shipping/vfd_sf_express (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: los eventos de OpenCart vfd_sf_express/quote_request y vfd_sf_express/api_url permiten que otra extensión cambie la petición de precio (por ejemplo, a otro código de producto) y la URL de la pasarela.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox SF Express. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable SF Express, Sort order, Tax class y Geo zone. Los precios en caché siempre se eliminan. Si Remove data on uninstall está activado, los demás ajustes y el registro también se borran. Si está desactivado, se conservan y se usan de nuevo al reinstalar la extensión. Las zonas de China añadidas con Add Chinese provinces se conservan. Los pedidos existentes mantienen su método de envío y su coste.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox SF Express en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.
SF Express es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por SF Express.