VibeFox Aramex for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posterior (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Cuenta de Aramex (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API Aramex Rate Calculator. Aramex da acceso a la API a sus titulares de cuenta. Pregunta a tu gestor de cuenta de Aramex o consulta el Aramex Developers Solution Center en el sitio web de Aramex. Necesitas seis valores: nombre de usuario de la API (normalmente una dirección de correo electrónico), contraseña, número de cuenta, PIN de la cuenta, entidad de la cuenta (por ejemplo DXB) y código de país de la cuenta (por ejemplo AE). Si solo usas precios fijos por país, no necesitas una cuenta de Aramex.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_aramex-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_aramex.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_aramex-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, 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 Aramex 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 el campo 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. Elige cómo se calcula el coste del envío, rellena las secciones correspondientes (véase Configuración), activa Enable Aramex 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_aramex.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 Aramex, 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 y 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.
Tras la instalación, el método queda desactivado hasta que actives Enable Aramex y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de Aramex que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Aramex > Edit. Las secciones aparecen a la izquierda. Un botón Save en la parte inferior guarda toda la página sin recargarla. Cada guardado también borra las tarifas de Aramex en caché. Si un valor es incorrecto, no se guarda nada y la página muestra el motivo, por ejemplo Enter a method title (1 to 64 characters)., un mensaje de que un campo debe ser un número, o The account country code must have 2 letters, e.g. AE. Solo los administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
General
Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica y a determinados países en Conditions.
Enable Aramex: muestra u oculta Aramex en la finalización de compra. Por defecto: 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. Por defecto: Aramex. Obligatorio.
Shipping cost: cómo se calcula el precio.
El motivo de que falte una tarifa en tiempo real se escribe en el registro de depuración. Nunca se muestra al cliente.
Sort order: la posición de Aramex entre los métodos de envío de la finalización de compra. Un número entero.
Cuenta de la API de Aramex (solo necesaria para tarifas en tiempo real; los seis campos son obligatorios)
Username: tu nombre de usuario de la API de Aramex, normalmente una dirección de correo electrónico. Si lo borras, también se borra la contraseña guardada.
Password: tu contraseña de la API de Aramex. 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.
Account number: el número de cliente de tu cuenta de Aramex. Si lo borras, también se borra el PIN guardado.
Account PIN: el PIN de tu cuenta de Aramex. Como la contraseña, no se vuelve a mostrar después de guardar.
Account entity: el código de entidad (oficina) de Aramex de tu cuenta, por ejemplo DXB, AMM o RUH.
Account country code: el código de país de 2 letras de tu cuenta de Aramex, por ejemplo AE.
Servicio de Aramex (se usa para tarifas en tiempo real)
Si la dirección de entrega está en el país de origen, el envío se cotiza como Domestic. Todos los demás envíos se cotizan como International express.
International service: el producto de Aramex para envíos al extranjero: PPX Priority Parcel Express (por defecto), PDX Priority Document Express, PLX Priority Letter Express (documentos de menos de 0,5 kg), DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express o GDX Ground Document Express.
Domestic service: el producto de Aramex para envíos dentro del país de origen: ONP Overnight (Parcel) (por defecto), OND Overnight (Document), SMP Same Day (Parcel), SMD Same Day (Document), SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express o HVY Heavy (20 kg o más).
Payment type: quién paga a Aramex el envío: Prepaid (shipper pays) (por defecto), Collect (receiver pays) o Third party. Normalmente se usa Prepaid.
API weight unit: la unidad que se envía a Aramex: Kilograms (KG) (por defecto) o Pounds (LB). Los pesos de los productos se convierten desde su clase de peso, y las dimensiones desde su clase de longitud. El peso facturable es el mayor entre el peso real y el peso volumétrico (largo × ancho × alto en cm / 5000). El mínimo es 0,5 kg, que también se aplica a los productos sin peso.
Currency conversion rate: se pide a Aramex que cotice en la moneda predeterminada de tu tienda. Si aun así responde en otra moneda, la tarifa se multiplica por este número (1 unidad de la moneda de Aramex = X unidades de la moneda predeterminada de tu tienda). Déjalo vacío para rechazar estas cotizaciones, de modo que nunca se cobre al cliente en una moneda incorrecta.
Origen del envío (se usa para tarifas en tiempo real)
Origin country: el país desde el que envías. La primera opción, Store country, usa el país de tu tienda.
Origin city: la ciudad desde la que envías. Aramex la exige. La dirección de la tienda en OpenCart es texto libre, así que la ciudad nunca se toma de ahí: introdúcela aquí.
Origin state / emirate: opcional.
Origin postcode: opcional.
Si el país de origen es el país de tu tienda, un estado vacío se toma de la región de tu tienda en System > Settings > Store > Local.
Precios fijos (se usan cuando Shipping cost es Fixed prices, y como alternativa para las tarifas en tiempo real)
Price per country: una lista de países y precios en la moneda predeterminada de tu tienda, sin impuestos. Haz clic en Add country para añadir una fila y en el botón × para quitar una. Elige * All other countries para un precio que se usa en todos los países sin fila propia. Los países sin precio (cuando no hay fila *) no tienen tarifa fija, así que el método se oculta para ellos.
Fixed price applies: Per order (por defecto) cobra el precio una vez. Per item (price × quantity) lo multiplica por el número de artículos del carrito. Las tarifas en tiempo real de Aramex siempre son por envío.
Condiciones
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (por defecto).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Por defecto: 100. 0 significa sin límite. Si dejas el campo vacío, se usan 100 kg.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping: activa el envío gratuito de Aramex a partir del importe indicado abajo.
Free shipping from: el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual el envío es gratuito. Solo se usa cuando Free shipping está activado.
Tax class: la clase de impuesto del coste del envío, o No tax (por defecto). Las tarifas en tiempo real de Aramex pueden incluir ya el IVA. En ese caso elige No tax para no cobrar el impuesto dos veces sobre el envío.
Geo zone: ofrece Aramex solo para direcciones de esta zona geográfica. All zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Countries: ofrece Aramex solo para estos países de destino. Déjalo vacío para permitir todos los países. Este límite se aplica junto con Geo zone.
Avanzado
Debug log: escribe los cálculos de tarifas y los errores de la API en storage/logs/vfd_armx_debug.log.php. El archivo no se puede leer desde la web. Las contraseñas, el PIN y las direcciones de los clientes nunca se registran. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_armx_debug.old.log.php y se inicia un registro nuevo.
Log: muestra el tamaño y las entradas más recientes 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 Aramex, las tarifas en caché y el registro. Si está desactivado (por defecto), se conservan para una reinstalación.
Importar / exportar
Exportar: haz clic en Download JSON para guardar los ajustes como archivo JSON. La contraseña y el PIN no se exportan.
Importar: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. La contraseña y el PIN guardados se conservan.
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 Aramex. Si hay una Geo zone y la dirección está fuera de ella, Aramex no se ofrece. Solo cuentan los productos con Requires Shipping ajustado a Yes: los demás productos no suman peso ni se incluyen en el importe del pedido. Después, la extensión comprueba las condiciones: países permitidos, peso del carrito e importe mínimo del pedido. El importe del pedido es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Si se aplica envío gratuito, el precio es 0 y no se envía ninguna solicitud a Aramex.
En el modo de precios fijos, el precio se toma de la tabla. En los modos de tarifas en tiempo real, la extensión envía a Aramex las direcciones de origen y de entrega, el peso facturable, el servicio y tu moneda predeterminada, y usa el total devuelto. Una tarifa en tiempo real solo se pide cuando la dirección de entrega tiene ciudad o código postal. El precio se calcula en tu moneda predeterminada, se redondea a sus decimales y se muestra al cliente en su moneda, con el impuesto de la Tax class seleccionada.
Cada respuesta se guarda en caché durante 1 hora, de modo 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 Aramex en cada actualización. El tiempo de espera de la API es de 10 segundos.
Si Aramex devuelve un error, un importe de cero o una cotización en otra moneda sin tipo de cambio, el cliente no ve ningún error. El método se oculta, o se usa el precio fijo en el modo de alternativa. El motivo se escribe en el registro de depuración.
La extensión solo calcula tarifas. No crea envíos de Aramex, no imprime etiquetas, no reserva recogidas, no hace seguimiento de paquetes ni permite que los clientes elijan una oficina de Aramex. No añade nada a los pedidos: el pedido muestra el nombre del método y el coste del envío como cualquier otro método de envío de OpenCart. El paquete siempre se envía a Aramex como una sola pieza.
En OpenCart 4, el cliente hace clic en Choose en el bloque del método de envío de la página de finalización de compra y elige Aramex 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 Aramex es el primero en la página Extensions > Extensions > Shipping > VibeFox Aramex > 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 están la línea Product: opencart-shipping-aramex y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los administradores con permiso de modificación 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 seguido de 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. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Aramex no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. 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 se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. 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 cuando abres el Dashboard del panel de administración 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 a la semana. No se necesita ningún cron job. Al desinstalar la extensión se eliminan siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Aramex no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Aramex esté activado. Revisa Geo zone, Countries, los límites de peso y Minimum order amount. En el modo de precios fijos, comprueba que el país o * All other countries tenga un precio. Comprueba que los productos tengan Requires Shipping ajustado a Yes.
Las tarifas en tiempo real no aparecen: activa el Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Muestra el motivo: faltan las credenciales de la API, código de error de Aramex, no hay ciudad de origen, no hay ciudad o código postal de entrega, un límite de peso o de importe, o una cotización en otra moneda. Con Aramex live rates, fixed prices if the API fails, los clientes siguen viendo el precio fijo mientras corriges el problema.
Error ERR75 en el registro: Aramex rechazó el inicio de sesión. Revisa el nombre de usuario, la contraseña, el número de cuenta, el PIN, la entidad y el código de país con tu gestor de cuenta de Aramex.
Se rechaza una cotización en otra moneda: Aramex respondió en una moneda distinta de tu moneda predeterminada. Introduce Currency conversion rate, o pide a Aramex que cotice en tu moneda.
El impuesto se cobra dos veces en el envío: los totales de Aramex 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 las tarifas de Aramex en caché.
La página dice "Warning: You do not have permission to modify VibeFox Aramex!": es posible que el grupo de usuarios de administración solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_aramex (OpenCart 3) o extension/vfd_aramex/shipping/vfd_aramex (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de Aramex se puede cambiar con el ajuste vfd_armx_api_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Aramex. OpenCart siempre restablece Enable Aramex, Sort order, Tax class y Geo zone. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de Aramex 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 volver a instalar 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 tras la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox Aramex en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Aramex es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Aramex.