VibeFox SMSA 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.
Tarifa de SMSA Express: los precios de la tabla de precios proceden de tu cuenta de SMSA o del equipo comercial de SMSA. Introdúcelos en la moneda predeterminada de tu tienda. Si tu tarifa está en SAR, AED u otra moneda, conviértela antes.
passKey de SMSA (solo para las tarifas en tiempo real): las tarifas en tiempo real usan el servicio web de SMSA (SECOM, operación getShipCharges). SMSA emite la passKey a petición: pídesela a tu gestor de cuenta de SMSA o escribe a info@smsaexpress.com y solicita acceso al servicio web de SMSA indicando tu número de cuenta. La passKey puede ser distinta de la clave de API del portal de comercio electrónico de SMSA. SMSA no tiene servidor de pruebas (sandbox) para este servicio.
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, más adelante, busca VibeFox SMSA Express en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página de configuración y haz clic en Activate (ver Clave de licencia).
4. Introduce tus precios de SMSA Express en la tabla de precios y haz clic en Save.
5. Opcional: en Live rates (API) activa Live charges, introduce tu passKey de SMSA, la ciudad y el país de origen y, si la moneda predeterminada de tu tienda no es SAR, el tipo de cambio.
Al instalar, el módulo crea el transportista SMSA Express con el texto del plazo de entrega SMSA Express courier. 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 lo calcula el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox SMSA Express > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de SMSA guardadas en caché. Un valor que no es un número, un número negativo, un tipo de cambio de 0, un código de moneda que no tiene 3 letras o un Minimum weight mayor que el Maximum weight se rechaza con un error, y no se guarda nada hasta que lo corrijas.
Cuando las tarifas en tiempo real están activadas, las advertencias sobre la configuración te avisan de una passKey, una ciudad de origen o un tipo de cambio que faltan, o de una tabla de precios vacía. También aparece una advertencia si el módulo no reconoce la unidad de peso de la tienda (en ese caso, los pesos de los productos se leen como kg). Configura kg, g, lb u oz en International > Localization (Local units).
General
Enable SMSA Express: activa o desactiva el transportista en todas las zonas a la vez. 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. Predeterminado: SMSA Express. Obligatorio, hasta 64 caracteres.
Tax: la regla de impuesto del transportista, o No tax. Elige No tax si tus precios (la tabla y los importes de SMSA) ya incluyen impuestos, por ejemplo el IVA saudí.
Tarifas en tiempo real (API) (opcional; si SMSA no devuelve ningún importe, se usa la tabla de precios)
Live charges: obtiene el importe del envío de SMSA Express. Predeterminado: desactivado.
SMSA passKey: la clave del servicio web de SMSA (SECOM). 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. Marca Remove the saved passKey para eliminarla. Si el registro muestra "Invalid Passkey", esa clave no la acepta este servicio. Pide a SMSA una passKey para el servicio web.
Ship-from city: la ciudad desde la que se envían tus paquetes, escrita como lo hace SMSA, por ejemplo Riyadh, Jeddah o Dammam. Déjalo vacío para usar la ciudad de la tienda de Shop Parameters > Contact > Stores.
Ship-from country: el país desde el que se envían tus paquetes. Por defecto es el país de tu tienda.
Shipment type: se envía a SMSA como tipo de envío. DLV (el predeterminado) es entrega estándar. Cámbialo solo si SMSA te ha dado otro código.
Currency of SMSA charges: SMSA devuelve cada importe con su código de moneda, normalmente SAR (el predeterminado). Un importe en cualquier moneda distinta de esta o de la moneda predeterminada de tu tienda no se usa.
Exchange rate: el precio de 1 unidad de la moneda de SMSA en la moneda predeterminada de tu tienda, por ejemplo 0.27. No hace falta cuando ambas monedas son iguales. Sin él, los importes en otra moneda no se usan y se aplica la tabla de precios. Se aceptan tanto el punto como la coma como separador decimal.
Precios (tu tarifa de SMSA Express en la moneda predeterminada de tu tienda; se usa cuando las tarifas en tiempo real están desactivadas y como alternativa cuando SMSA no devuelve ningún importe)
Price table: una fila por país de destino. Haz clic en Add country para añadir una fila y en el icono de papelera para eliminar una. La fila * Default (all other countries) se aplica a los países que no tienen fila propia. Cada fila tiene un precio base y columnas 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. Una columna de peso vacía o con 0 usa el precio base. Un precio base de 0 significa envío gratis. Las filas sin ningún precio no se guardan. Si un país tiene dos filas, se usa la primera. Se aceptan tanto "9.99" como "9,99".
Price for countries not in the table: se usa cuando la tabla no tiene fila para el país de destino (ni fila *) o la fila no tiene precio para ese peso. Déjalo vacío para ocultar el transportista en ese caso.
Price applies: cómo se calcula el precio.
Los pesos de los productos se convierten de la unidad de peso de tu tienda a kilogramos.
Condiciones
Minimum weight: oculta el transportista cuando el carrito pesa menos, en kg. 0 significa sin límite.
Maximum weight: oculta el transportista cuando el carrito pesa más, en kg. Predeterminado: 30. 0 o un campo vacío significa sin límite.
Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (después de descuentos y antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal del carrito (después de descuentos y antes de impuestos) a partir del cual el envío con SMSA Express es gratis. Cuando el carrito lo alcanza, el precio es 0 y no se envía ninguna solicitud a SMSA. Déjalo vacío para no ofrecer nunca envío gratis.
Disponibilidad sin zonas de envío
Normalmente el transportista se ofrece en las zonas a las que está asignado en Shipping > Carriers.
Ignore shipping zones: ofrece SMSA Express para los países indicados a continuación, sea cual sea la zona que coincida. Mientras esté activado, el transportista se añade a todas las zonas, incluidas las creadas más adelante. Al desactivarlo, se eliminan de nuevo las zonas añadidas.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra los cálculos de tarifas en logs/vfd_smsa_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. No se registran direcciones de clientes ni claves. Los errores de las tarifas en tiempo real siempre se registran, incluso con esta opción desactivada. Desactiva el registro cuando termines.
Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: cuando está activado, al desinstalar el módulo se eliminan los ajustes de SMSA Express, el transportista y el registro. Cuando está desactivado, todo se conserva para una reinstalación. Las tarifas en caché siempre se eliminan.
Cómo funciona al finalizar la compra
En el paso de envío, PrestaShop pide al módulo el precio de SMSA Express. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el importe del pedido. El módulo comprueba primero las condiciones: los países de Ignore shipping zones (si está activado), el peso del carrito y el importe mínimo del pedido. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna solicitud a SMSA.
Con las tarifas en tiempo real activadas, el módulo envía a SMSA la ciudad y el país de origen, la ciudad y el país del cliente, el tipo de envío, el peso del paquete en kg y un importe de pago contra reembolso de 0. SMSA responde con el importe y su moneda. El módulo lo convierte a la moneda predeterminada de tu tienda, y el precio se muestra después en la moneda del carrito del cliente. La tarifa en tiempo real solo se solicita cuando el cliente ha introducido una dirección de entrega con ciudad.
Cada importe se guarda en caché durante una hora, de modo que el mismo carrito no genera una nueva solicitud. Una solicitud fallida se guarda en caché durante 5 minutos. Tras un tiempo de espera o un error del servidor, no se vuelve a preguntar a SMSA durante 2 minutos. Tras una clave rechazada, no se vuelve a preguntar durante 5 minutos. Así, la finalización de compra nunca espera a un servicio que falla en cada actualización. El tiempo de espera de la solicitud es de 12 segundos.
Siempre que SMSA no devuelve un importe utilizable (sin passKey, sin ciudad introducida todavía, sin pesos de producto, clave no válida, tiempo de espera, error, sin servicio a la ciudad o moneda desconocida), se usa la tabla de precios. Si la tabla y Price for countries not in the table no dan ningún precio, el transportista se oculta. El cliente nunca ve un error. El motivo 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 el precio del envío. No crea envíos de SMSA, no imprime etiquetas AWB, no gestiona devoluciones ni hace seguimiento de paquetes. El pago contra reembolso y su comisión no se incluyen en la tarifa en tiempo real. No hay selector de puntos de venta minoristas de SMSA: el transportista es entrega a domicilio.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox SMSA Express es el primer bloque de Modules > Module Manager > VibeFox SMSA Express > Configure, 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: presta-shipping-smsa-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 el inglés y el 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. 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 transportista SMSA Express no se muestra a los clientes 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 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 requieren 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 tras introducir la clave, y después una vez a la 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
SMSA Express no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable SMSA Express está activado. En Shipping > Carriers comprueba que el transportista cubre la zona del país del cliente y su grupo (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 el país o * tiene un precio, o que Price for countries not in the table está configurado. Además, los productos pueden estar limitados a determinados transportistas en la ficha del producto.
Los clientes ven el precio de la tabla en lugar del importe de SMSA: SMSA necesita la ciudad del cliente, así que hasta que se introduce se muestra el precio de la tabla. La tabla también se usa cuando SMSA no responde, rechaza la clave o la ciudad, o devuelve el importe en una moneda sin tipo de cambio. Consulta el campo Log de la página del módulo para ver el motivo.
"Invalid Passkey" en el registro: el servicio web de SMSA no acepta la clave. Pide a SMSA una passKey para el servicio web.
La ciudad del cliente no se acepta: SMSA espera su propia forma de escribir las ciudades. Revisa la ciudad en la dirección de entrega y la Ship-from city.
Los ajustes no se guardan y aparece un error: un campo numérico contiene texto o un valor negativo, el tipo de cambio es 0, el código de moneda no tiene 3 letras o Minimum weight es mayor que Maximum weight. Corrige el valor indicado en el mensaje y haz clic de nuevo en Save.
El impuesto del envío se cobra dos veces: tu tarifa o los importes de SMSA pueden incluir ya el IVA. Pon Tax en No tax.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las tarifas de SMSA guardadas en caché.
La página indica que no se encontró el transportista SMSA Express: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox SMSA Express y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las tarifas 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 al restablecerlo, el transportista recupera el estado que tenía antes.
SMSA Express es una marca comercial de su respectivo titular. Este módulo no está afiliado ni avalado por SMSA Express.