VibeFox Andreani 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), con el tema predeterminado.

PHP: 8.0 o posterior.

Cuenta de Andreani (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API de cotizaciones de Andreani. Andreani entrega credenciales de API, un código de cliente y números de contrato a los clientes comerciales, normalmente a partir de unos 300 envíos al mes. Consulta developers.andreani.com o escribe a ventapyme@andreani.com. Necesitas el nombre de usuario y la contraseña de la API, el código de cliente y el número de contrato. Andreani emite un contrato distinto para cada servicio (entrega a domicilio, retiro en sucursal). Sin acceso a la API, usa tarifas fijas. El selector de sucursales funciona sin credenciales.

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_andreani-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_andreani.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_andreani-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 Andreani 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 (ver Clave de licencia).

5. Configura el nombre, el origen de las tarifas, los precios por país (por ejemplo AR=5000) y, para tarifas en tiempo real, las credenciales de la API, el código de cliente y el número de contrato (ver Configuración). Haz clic en Save.

OpenCart 4

1. En el administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_andreani.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 de 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 Andreani, 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 los mismos en ambas versiones.

Tras la instalación, Enable/Disable y Enable second option están desactivados, y Andreani no se ofrece en el proceso de compra hasta que actives una opción y hagas clic en Save. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes de Andreani que conservaste, pero ambas opciones quedan desactivadas: actívalas y haz clic en Save.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Andreani > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Tras guardar verás Settings saved. Cached token, branches and rates were cleared. Solo los administradores con el permiso de modificación de esta extensión pueden guardar los ajustes.

En la parte superior de la página aparecen advertencias sobre ajustes que faltan: tarifas de API seleccionadas sin el nombre de usuario y la contraseña de la API o sin número de contrato, falta de ARS exchange rate cuando la moneda de la tienda no es ARS, o falta de precio para Argentina en Country prices. También aparece una advertencia si la unidad de peso o de longitud de la tienda no la reconoce la extensión (entonces los pesos se leen como kg, y las dimensiones como cm).

Al guardar, se rechaza sin guardar nada un nombre vacío, un nombre de más de 64 caracteres o con alguno de los caracteres < > ; = # { }, un Min weight (kg) mayor que Max weight (kg), o un Sort order que no sea un número entero. Un valor que no es un número, un número negativo o un ARS exchange rate de 0 o menos no se guarda, y una advertencia indica el campo.

General

Andreani tiene dos opciones en el proceso de compra: la opción principal, configurada aquí y en Andreani API y Delivery and rates, y la Second option. Ambas se muestran bajo el encabezado Andreani en el paso de método de envío.

Enable/Disable: activa o desactiva la opción principal de Andreani. Por defecto: desactivado. La segunda opción tiene su propio interruptor.

Name: el nombre de la opción principal que ve el cliente en el proceso de compra. Por defecto: Andreani. Obligatorio.

Tax status: None (the API rate is taken with IVA) (por defecto), o una de tus clases de impuesto. Con una clase de impuesto, OpenCart añade impuesto al coste de envío, así que la tarifa de la API se toma sin IVA. Con None, la tarifa de la API se toma con IVA incluido. Lo usan ambas opciones.

Sort order: la posición de Andreani entre los métodos de envío en el proceso de compra. Un número entero.

Andreani API (necesario para tarifas en tiempo real)

Environment: Sandbox / QA (apisqa.andreani.com) (por defecto) o Production (apis.andreani.com). Usa el entorno al que pertenecen tus credenciales.

API username: tu nombre de usuario de la API de Andreani.

API password: tu contraseña de la API de Andreani. Tras guardar, el campo queda vacío y muestra Saved - leave empty to keep it. Clearing the API username removes it too. Escribe un valor nuevo solo si quieres cambiarla.

Client code: el código de cliente (código de cliente) que te facilita Andreani, por ejemplo CL0000000.

Contract number: el contrato del servicio usado para las tarifas, por ejemplo entrega a domicilio. La segunda opción puede usar otro contrato, por ejemplo para retiro en sucursal.

Origin branch code: sucursal de origen opcional (sucursalOrigen) para las cotizaciones. Déjalo vacío para usar la sucursal configurada en tu contrato.

Entrega y tarifas

Delivery modality: la modalidad de la opción principal. La primera parte indica dónde recoge Andreani el paquete (tu dirección o una sucursal donde lo dejas). La segunda parte indica dónde lo recibe el cliente.

Rate source: cómo se calcula el precio.

Country prices: un precio fijo por país de destino en la moneda predeterminada de tu tienda, sin impuestos, una línea por país con el formato CC=PRECIO, por ejemplo AR=5000. Se usa en el modo fijo y como alternativa de la API. Los países sin línea no tienen precio fijo. Las líneas con otro formato se ignoran, y al guardar una advertencia las enumera.

ARS exchange rate: Andreani cotiza en pesos argentinos. Solo hace falta si la moneda predeterminada de tu tienda no es ARS: el precio de 1 ARS en la moneda de tu tienda, por ejemplo 0.001. Sin él, no se usan tarifas de la API.

Default product weight (kg): se usa para los productos sin peso al pedir tarifas a la API y al comprobar los límites de peso. Vacío significa 0,5 kg.

Calculation type: Per order (por defecto) cobra el precio una vez. Per item (price x number of items) multiplica el precio fijo de Country prices por el número de artículos del carrito. Una tarifa en tiempo real de Andreani ya corresponde a todo el carrito y no se multiplica.

Disponibilidad

Min weight (kg): el peso mínimo del carrito para que aparezca el método. 0 significa sin límite (por defecto).

Max weight (kg): el peso máximo del carrito. El método se oculta si se supera. Por defecto: 100. Vacío significa 100 kg, 0 significa sin límite.

Minimum subtotal: muestra el método solo cuando el subtotal del carrito (productos que requieren envío, después del cupón, sin impuestos, en la moneda predeterminada de tu tienda) es al menos este importe. Déjalo vacío para mostrarlo siempre.

Geo zone: ofrece Andreani 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. No se usa cuando Ignore shipping zones está activado.

Ignore shipping zones: ofrece Andreani para los países indicados abajo, sea cual sea la zona geográfica. Por defecto: desactivado.

Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Solo se usa cuando Ignore shipping zones está activado.

Envío gratuito

Free shipping: activa el umbral de envío gratuito. Por defecto: desactivado.

Free shipping from: el subtotal del carrito (en la moneda predeterminada de tu tienda) a partir del cual el envío es gratuito. Requiere que Free shipping esté activado.

Segunda opción

Una segunda opción de Andreani con su propio nombre, modalidad de entrega y contrato, por ejemplo "a domicilio" en la opción principal y "retiro en sucursal" aquí, para ofrecer ambas. El resto de ajustes se comparten.

Enable second option: ofrece la segunda opción en el proceso de compra. Por defecto: desactivado.

Second option name: el nombre de esta opción en el proceso de compra. Por defecto: Andreani - branch pickup. Obligatorio.

Delivery modality: Use global setting o una de las cuatro modalidades. Por defecto: Door to branch (Puerta a Sucursal).

Contract number: Andreani emite un contrato distinto por servicio (entrega a domicilio, retiro en sucursal). Déjalo vacío para usar el contrato global.

Selector de sucursales (se muestra para Door to branch y Branch to branch)

Province select width: el ancho CSS de la lista de provincias, por ejemplo 100% o 300px. Por defecto: 100%.

Branch select width: el ancho CSS de la lista de sucursales, por ejemplo 100% o 400px. Por defecto: 100%.

Avanzado

Debug log: registra las solicitudes a la API y los cálculos de tarifas en storage/logs/vfd_andr_debug.log.php. El archivo no se puede leer desde la web. Los errores se registran siempre. Las credenciales y los tokens nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_andr_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 todos los ajustes de Andreani y el registro. Si está desactivado (por defecto), se conservan para una reinstalación. Los datos de sucursal guardados en los pedidos se conservan siempre.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes en un archivo JSON. La contraseña de la API no se exporta.

Import: pega un 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 de la API guardada se conserva.

Cómo funciona en el proceso de compra

Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de cada opción de Andreani activada. Si hay una Geo zone definida y Ignore shipping zones está desactivado, Andreani no se ofrece a direcciones fuera de la zona geográfica. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni se incluyen en el subtotal. A continuación, la extensión comprueba los países (cuando Ignore shipping zones está activado), el peso del carrito (los pesos de los productos se convierten a kg, y los productos sin peso usan Default product weight (kg)) y el Minimum subtotal. El subtotal es el precio de los productos que requieren envío, después del descuento del cupón y antes de impuestos.

En el modo fijo, el precio se toma de Country prices. En los modos de tarifas en tiempo real, la extensión inicia sesión en la API de Andreani y solicita una cotización con el código postal de destino, el contrato, el código de cliente, el peso en kg, el volumen calculado a partir de las dimensiones de los productos y el valor declarado (el subtotal del carrito en ARS). Una tarifa en tiempo real solo se solicita para un código postal argentino válido (4 dígitos, o un CPA como C1425ABC). El importe en ARS se convierte con ARS exchange rate cuando la moneda de la tienda no es ARS. El precio se calcula en la moneda predeterminada de la tienda, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax status seleccionada.

El token de inicio de sesión se conserva hasta 23 horas y se renueva automáticamente cuando Andreani lo rechaza. Las cotizaciones se guardan en caché durante 1 hora. Una llamada fallida a la API no se repite durante 5 minutos. Todo esto se almacena en la caché de OpenCart, así que una entrada nunca se conserva más tiempo que la duración de la caché de OpenCart (1 hora por defecto), y después simplemente se vuelve a solicitar. Los errores de la API nunca se muestran al cliente: la opción se oculta, o se usa el precio fijo en el modo de respaldo. El motivo se escribe en el registro.

Si Free shipping está activado y el subtotal del carrito alcanza Free shipping from, el precio es 0. El envío gratuito solo se aplica donde la opción tiene precio: si la API de Andreani no devuelve tarifa y no hay precio fijo al que recurrir, la opción no se muestra.

La extensión no crea envíos de Andreani, no imprime etiquetas ni rastrea paquetes. Para ello, usa el portal web de Andreani.

En OpenCart 4 el cliente hace clic en Choose en el bloque del método de envío de la página de compra y elige una opción de Andreani en la ventana Shipping method options. Las opciones funcionan igual que en OpenCart 3; la selección de sucursal se describe en Puntos de retiro.

Puntos de retiro

Cuando se ofrece una opción con Door to branch o Branch to branch, aparecen justo debajo de ella, en el paso de método de envío, una lista de provincias y una lista de sucursales. La provincia se preselecciona según la región de la dirección de entrega. La lista de sucursales proviene de la API pública de sucursales de Andreani y se guarda en caché hasta 12 horas (dentro de la duración de la caché de OpenCart). No aparecen las sucursales que no reciben paquetes. El paso de entrega en sí nunca espera a Andreani: si la lista aún no está en caché, se carga en segundo plano y el cliente ve brevemente Loading Andreani branches.... Si no hay sucursales disponibles, el cliente ve No Andreani branches available right now. Please try again later or choose another shipping method.

La elección se guarda en cuanto el cliente la selecciona. Solo se acepta una sucursal de la lista actual de Andreani. Sin sucursal, Continue en el paso de entrega no avanza, y el cliente ve Please select an Andreani pickup branch. El servidor vuelve a comprobar la sucursal cuando el cliente continúa. Si la sucursal ya no está en la lista, el cliente ve The selected Andreani branch is not available. Please choose another one.

En OpenCart 4 la lista de provincias y la lista de sucursales aparecen en la ventana Shipping method options, justo debajo de la opción de sucursal de Andreani, con los mismos textos y comprobaciones. Continue en la ventana sin sucursal se detiene con Please select an Andreani pickup branch. bajo la opción. Si la tienda rechaza la sucursal cuando el cliente continúa, el mensaje aparece en la parte superior de la página de compra y la ventana permanece abierta. OpenCart 4 mantiene un pedido para la compra y lo actualiza en cada confirmación; la sucursal del pedido se actualiza con él, y se elimina cuando el cliente cambia el pedido a otro método de envío.

Una sucursal elegida con una opción de Andreani no pertenece a un pedido realizado con otra opción u otro método de envío.

El selector está hecho para el proceso de compra de una página del tema predeterminado de OpenCart 3 y para el proceso de compra del tema predeterminado de OpenCart 4. Un tema con una estructura distinta en el paso de entrega puede necesitar cambios en el script del selector.

Pedidos

El pedido guarda la modalidad de entrega y, para las modalidades con sucursal, la sucursal elegida.

Shipping method of the order: la sucursal se añade al texto del método de envío, por ejemplo Andreani - branch pickup: y el nombre de la sucursal. Si el nombre de la opción no menciona una sucursal, se añade el texto Pickup branch: (o Andreani pickup branch: cuando el nombre no contiene Andreani) delante del nombre de la sucursal, por ejemplo Andreani - Pickup branch: y el nombre de la sucursal. Este texto aparece en los correos de pedido al cliente y a la tienda, en el historial de pedidos del cliente, en la factura y en la página del pedido del administrador. OpenCart limita el texto a 128 caracteres; los datos completos de la sucursal los guarda la extensión. La página de éxito del pedido de OpenCart no muestra el método de envío.

Admin order page: en Sales > Orders, abre un pedido. Un panel de Andreani muestra Andreani modality y, para las modalidades con sucursal, Andreani branch (nombre, ID y provincia). Haz clic en Edit, elige otra provincia y otra sucursal y haz clic en Save para cambiarla. Verás Branch updated., y el texto de la sucursal en el método de envío del pedido también se reemplaza. Solo se pueden guardar sucursales de la lista de Andreani. Si la lista no está disponible, verás The Andreani branch list is not available right now - the branch cannot be changed. Cambiar la sucursal requiere el permiso de modificación para sale/order y acceso a extension/shipping/vfd_andreani (OpenCart 3) o extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4). El panel también se muestra en pedidos ya realizados con Andreani aunque la extensión esté desactivada.

Mientras la extensión esté desactivada, el panel de Andreani no se muestra. Los datos de la sucursal se conservan y el texto del método de envío del pedido no cambia. Los pedidos existentes conservan sus datos de sucursal.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Andreani es el primero en Extensions > Extensions > Shipping > VibeFox Andreani > Edit, 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 comprobar el estado de nuevo, 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-andreani y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para 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 es aceptada, 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 que cambie 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, las opciones de envío de Andreani no se muestran a los clientes en el proceso 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. Tras abrir una vez la página Edit, 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 necesitan 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 ninguna tarea cron. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Andreani no aparece en el proceso de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado (para la segunda opción, también Enable second option) y que hiciste clic en Save tras la instalación. Revisa Geo zone, o Ignore shipping zones y Countries. Comprueba que Country prices tenga una línea para el país (para precios fijos o como alternativa), los límites de peso y el Minimum subtotal. Lee las advertencias de la parte superior de la página Edit. Comprueba que los productos tengan Requires Shipping en Yes.

Las tarifas en tiempo real no aparecen: activa Debug log, recarga el proceso de compra y mira el campo Log de la página de la extensión. Muestra el motivo: faltan credenciales o el número de contrato, falla el inicio de sesión (usuario, contraseña o entorno incorrectos), todavía no hay un código postal argentino válido, no hay tipo de cambio o hay un error HTTP de Andreani. Con Andreani API, fixed price if the API fails, los clientes siguen recibiendo el precio fijo mientras corriges el problema.

Mi tienda no está en pesos argentinos: establece ARS exchange rate con el valor de 1 ARS en la moneda predeterminada de tu tienda.

El impuesto del envío parece incorrecto: con una clase de impuesto en Tax status, se usa la tarifa de Andreani sin IVA y OpenCart añade su propio impuesto. Con None, se usa la tarifa con IVA y no se añade impuesto. Comprueba que los impuestos estén activados en la configuración de la tienda y que la clase de impuesto tenga tarifas para Argentina.

No hay sucursales en la lista: la API de sucursales de Andreani no respondió. Una solicitud fallida se reintenta tras 5 minutos. Revisa el registro.

Se preselecciona una provincia equivocada: la provincia se lee de la región de la dirección de entrega. El cliente siempre puede elegir otra provincia.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra el token, la lista de sucursales y las tarifas guardados en caché.

La página dice "Warning: You do not have permission to modify VibeFox Andreani!": tu grupo de usuarios de administración puede tener solo permiso de visualización de los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_andreani (OpenCart 3) o extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4) en System > Users > User Groups.

Para desarrolladores: los hosts de la API de Andreani pueden sustituirse con el ajuste vfd_andr_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 Andreani. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart restablece siempre el estado, Sort order, Tax status y Geo zone. La extensión elimina siempre sus manejadores de la página de pedido y del proceso de compra, así como el token, la lista de sucursales y las tarifas en caché. Si Remove data on uninstall está activado, también se borran todos los ajustes de Andreani y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al reinstalar la extensión. Los datos de sucursal guardados en los pedidos nunca se borran, y 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 desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox Andreani en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

Andreani es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por Andreani.