VibeFox SMSA Express for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 o posterior (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Tarifa de SMSA Express: los precios de la tabla 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 primero.

passKey de SMSA (solo para cargos en tiempo real): los cargos en tiempo real usan el servicio web de SMSA (SECOM, operación getShipCharges). SMSA emite el passKey bajo petición: pídeselo a tu gestor de cuenta de SMSA o escribe a info@smsaexpress.com. El passKey puede ser distinto de la clave de API del portal de comercio electrónico de SMSA. SMSA no tiene servidor de pruebas (sandbox) para este servicio.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

El archivo descargado es un zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_smsa_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 administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_smsa_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 de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox SMSA 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 configuración.

4. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia, en la parte superior de la página Edit, y haz clic en Activate (véase Clave de licencia).

5. Introduce tus precios de SMSA Express en la tabla de precios.

6. 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.

7. Activa Enable SMSA Express y haz clic en Save.

OpenCart 4

1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_smsa_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 SMSA 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 para OpenCart 3. La página de configuración y sus campos son los mismos en ambas versiones.

Tras la instalación, el método está desactivado hasta que actives Enable SMSA Express y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de SMSA Express que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra los cargos de SMSA en caché. Un título de método no válido, 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, un precio incorrecto en la tabla, un Minimum weight (kg) mayor que el Maximum weight (kg) o un orden de clasificación que no es un número entero se rechazan con un error, y no se guarda nada hasta que lo corrijas. Solo los administradores con el permiso de modificación de esta extensión pueden guardar la configuración.

Cuando los cargos en tiempo real están activados, las advertencias de la configuración te avisan de un 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 la tienda no tiene una clase de peso en kg y su unidad de peso predeterminada no la conoce la extensión (los pesos de los productos se leen entonces como kg). Añade una clase de peso en kg en System > Localisation > Weight Classes.

General

Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica en Conditions, o a una lista de países con Ignore shipping zones.

Enable SMSA Express: muestra u oculta SMSA Express en la finalización de compra. Predeterminado: desactivado.

Method title: el nombre del método de envío que el cliente ve en el carrito y en la finalización de compra. Predeterminado: SMSA Express. Obligatorio, máximo 64 caracteres, sin los caracteres < > ; = # { }.

Sort order: la posición de SMSA Express entre los métodos de envío en la finalización de compra. Un número entero.

Live rates (API) (opcional; si SMSA no devuelve ningún cargo, se usa la tabla de precios)

Live charges: obtiene el cargo de envío de SMSA Express. Si está desactivado, no se envía nada a SMSA durante la finalización de compra. 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 para cambiarla. Marca Remove the saved passKey para eliminarla. Si el registro muestra "Invalid Passkey", esta clave no la acepta este servicio. Pide a SMSA un 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. Obligatoria para los cargos en tiempo real: OpenCart no tiene ciudad de tienda, así que nunca se toma de la dirección de la tienda.

Ship-from country: el país desde el que se envían tus paquetes. La primera opción, Store country, usa el país de tu tienda según System > Settings > Store > Local. Es el valor predeterminado.

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 dio otro código.

Currency of SMSA charges: el código de 3 letras de la moneda en la que SMSA devuelve los cargos, normalmente SAR (el predeterminado). Un cargo 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 cargos en otra moneda no se usan y se aplica la tabla de precios.

Prices (tu tarifa de SMSA Express en la moneda predeterminada de tu tienda; se usa cuando los cargos en tiempo real están desactivados y como alternativa cuando SMSA no devuelve ningún cargo)

Price table: una fila por país de destino. Haz clic en Add country para añadir una fila. La fila * All other countries se aplica a los países sin fila propia. Cada fila tiene un precio Base y columnas de peso: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg y XL >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 (y no hay fila *) o la fila no tiene precio para este peso. Déjalo vacío para ocultar el método en ese caso.

Price applies: cómo se calcula el precio.

Los pesos de los productos se convierten de su clase de peso de OpenCart a kilogramos.

Conditions

Minimum weight (kg): oculta el método cuando el carrito pesa menos. 0 significa sin límite (predeterminado).

Maximum weight (kg): oculta el método cuando el carrito pesa más. Predeterminado: 30. 0 o un campo vacío significa sin límite.

Minimum order amount: muestra el método solo cuando el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.

Free shipping from: el subtotal de los productos que requieren envío (después del cupón, antes de impuestos) a partir del cual el envío de SMSA Express es gratis. Cuando el carrito lo alcanza, el precio es 0 y no se envía ninguna petición a SMSA. Déjalo vacío para no ofrecer nunca envío gratis.

Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Elige No tax si tus precios (la tabla y los cargos de SMSA) ya incluyen impuestos, por ejemplo el IVA saudí.

Geo zone: ofrece SMSA Express solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. No se comprueba mientras Ignore shipping zones esté activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.

Availability without shipping zones

Normalmente el método se ofrece para las direcciones de la zona geográfica elegida en Conditions.

Ignore shipping zones: ofrece SMSA Express para los países indicados abajo, sea cual sea la zona geográfica. Si está desactivado, decide la zona geográfica y la lista de países no se usa.

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.

Advanced

Debug log: registra los cálculos de tarifas en storage/logs/vfd_smsa_debug.log.php. El archivo no se puede leer desde la web. No se registran direcciones de clientes ni claves. Los errores de los cargos en tiempo real siempre se registran, incluso con esta opción desactivada. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se traslada a vfd_smsa_debug.old.log.php y se inicia un registro nuevo.

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: si está activado, al desinstalar la extensión se borran los ajustes de SMSA Express y el registro de depuración. Si está desactivado (predeterminado), los ajustes se conservan para una reinstalación. Los cargos en caché siempre se eliminan.

Import / Export

Export: haz clic en Download JSON para guardar la configuración como archivo JSON. El passKey no se exporta.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar la configuración, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. El passKey guardado se conserva.

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 SMSA Express. Si hay una Geo zone definida (y Ignore shipping zones está desactivado) y la dirección está fuera de ella, SMSA Express no se ofrece. Solo cuentan los productos con Requires Shipping definido en Yes: los demás no añaden peso y no se incluyen en el importe del pedido. Después la extensión comprueba las condiciones: los países de Ignore shipping zones (si está activado), el peso del carrito y el importe mínimo del pedido. Los certificados regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica el envío gratis, el precio es 0 y no se envía ninguna petición a SMSA.

Con los cargos en tiempo real activados, la extensión 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 cargo y su moneda. La extensión lo convierte 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. Un cargo en tiempo real solo se pide después de que el cliente haya introducido una dirección de entrega con ciudad.

Cada cargo se guarda en caché durante una hora, así que el mismo carrito no provoca una nueva petición. Una petición 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 petición es de 12 segundos.

Siempre que SMSA no devuelve un cargo utilizable (sin passKey, sin ciudad introducida todavía, una clave no válida, un tiempo de espera, un error, ningún servicio a la ciudad o una 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 método se oculta. El cliente nunca ve un error. El motivo se escribe en el registro.

La extensión 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 están incluidos en el cargo en tiempo real. No hay selector de puntos de venta de SMSA: el método es entrega a domicilio. No añade nada a los pedidos: el pedido muestra el título del método y el coste de envío como cualquier otro método de envío de OpenCart.

En OpenCart 4 el cliente hace clic en Choose en el bloque de métodos de envío de la página de finalización de compra y elige SMSA Express en la ventana Shipping method options. 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 SMSA Express es el primer bloque de Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después el bloque muestra la clave oculta, 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 están la línea Product: opencart-shipping-smsa-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 de la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (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 el servidor de licencias no responde, 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, SMSA Express no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un administrador que haya iniciado sesión en el administrador 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 se oculta 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 renovarla. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del administrador o la página Edit: 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 se necesita ninguna tarea cron. Desinstalar la extensión 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. Revisa Geo zone (o, con Ignore shipping zones activado, Countries), los límites de peso y el Minimum order amount. Comprueba que el país o * tenga un precio, o que Price for countries not in the table esté definido. Comprueba que los productos tengan Requires Shipping definido en Yes.

Los clientes ven el precio de la tabla en lugar del cargo de SMSA: SMSA necesita la ciudad del cliente, así que hasta que se introduzca 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 cargo en una moneda sin tipo de cambio. Mira el campo Log de la página de la extensión para ver el motivo.

"Invalid Passkey" en el registro: la clave no la acepta el servicio web de SMSA. Pide a SMSA un passKey para el servicio web.

La ciudad del cliente no es aceptada: SMSA espera su propia forma de escribir las ciudades. Revisa la ciudad de 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 (kg) es mayor que Maximum weight (kg). Corrige el valor indicado en el mensaje y haz clic en Save de nuevo.

El impuesto se cobra dos veces en el envío: tu tarifa o los cargos de SMSA pueden incluir ya el IVA. Pon Tax class en No tax.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra los cargos de SMSA en caché.

La página muestra "Warning: You do not have permission to modify VibeFox SMSA Express!": es posible que tu grupo de usuarios solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_smsa_express (OpenCart 3) o extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: la dirección del servicio web de SMSA puede cambiarse con el ajuste vfd_smsa_api_url (para pruebas); no tiene campo en la página de configuración.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox SMSA Express. La clave de licencia y el estado de la licencia de esta extensión se eliminan siempre. OpenCart siempre restablece Enable SMSA Express, Sort order, Tax class y Geo zone. Los cargos en caché siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de SMSA Express y el registro de depuración también se borran. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al reinstalar la extensión. Los pedidos existentes conservan 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 la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox SMSA Express en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

SMSA Express es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por SMSA Express.