VibeFox Andreani 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.
Cuenta de Andreani (solo para tarifas en tiempo real): las tarifas en tiempo real usan la API de cotizaciones de Andreani. Andreani emite credenciales de API, un código de cliente y números de contrato a los clientes empresa, 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, recogida en sucursal). Sin acceso a la API, usa precios fijos. El selector de sucursales funciona sin credenciales.
VibeFox license key: se compra en vibefox.net. Una clave funciona en un 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 busca VibeFox Andreani en la lista de módulos más tarde y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (consulta Clave de licencia).
4. Define el nombre, la fuente de tarifas, los precios por país (por ejemplo AR=5000) y, para las tarifas en tiempo real, las credenciales de la API, el código de cliente y el número de contrato (consulta Configuración). Haz clic en Save.
Al instalarse, el módulo crea dos transportistas:
Ambos transportistas están asignados a la zona de Argentina y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el tiempo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No definas precios allí: el precio siempre viene del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Andreani > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Tras guardar verás Settings saved. Cached token, branches and rates were cleared. Las advertencias sobre ajustes que faltan (credenciales de la API, número de contrato, tipo de cambio ARS, sin precio para Argentina, un transportista eliminado) aparecen en la parte superior de la página. También aparece una advertencia si el módulo no reconoce la unidad de peso o de dimensiones de la tienda (en ese caso, los pesos se leen como kg y las dimensiones como cm). Al guardar, se rechaza un nombre de más de 64 caracteres o un Min weight (kg) mayor que Max weight (kg), y no se guarda nada. 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
Enable/Disable: activa o desactiva el envío con Andreani. Es el mismo interruptor que el estado del transportista principal en Shipping > Carriers. La segunda opción tiene su propio interruptor.
Name: el nombre del transportista que ve el cliente en la finalización de compra. Por defecto: Andreani. Obligatorio.
Tax status: None, o Taxable con una de tus reglas de impuesto. Con una regla de impuesto, la tienda añade el impuesto al coste del 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. El ajuste se guarda en ambos transportistas de Andreani.
Andreani API (necesario para las 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 cambiarlo.
Client code: el código de cliente (código de cliente) facilitado por 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 la recogida 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 del transportista principal. La primera parte indica dónde recoge Andreani el paquete (tu domicilio 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=PRICE, por ejemplo AR=5000. Se usa en el modo fijo y como respaldo si falla la API. Los países sin línea no tienen precio fijo. Las líneas con otro formato se ignoran, y una advertencia las muestra al guardar.
ARS exchange rate: Andreani cotiza en pesos argentinos. Solo es necesario si la moneda predeterminada de tu tienda no es el ARS: el precio de 1 ARS en la moneda de tu tienda, por ejemplo 0.001. Sin él, no se usan las tarifas de la API.
Default product weight (kg): se usa para los productos sin peso al pedir tarifas de la API y al comprobar los límites de peso. Si está vacío, son 0,5 kg.
Calculation type: Per order cobra el precio una sola 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 es para todo el carrito y no se multiplica.
Disponibilidad
Min weight (kg): el peso mínimo del carrito para que aparezca el transportista. 0 significa sin límite.
Max weight (kg): el peso máximo del carrito. El transportista se oculta si se supera. Vacío significa 100 kg, 0 significa sin límite.
Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito (productos que necesitan envío, después de descuentos, sin impuestos) es al menos este importe. Déjalo vacío para mostrarlo siempre.
Ignore shipping zones: ofrece Andreani para los países de abajo sin configurar zonas. Al activarlo, ambos transportistas se vinculan a todas las zonas, y una zona creada después se vincula de inmediato. Al desactivarlo, los transportistas recuperan sus zonas anteriores.
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 gratis
Free shipping: activa el umbral de envío gratis.
Free shipping from: el subtotal del carrito a partir del cual el envío es gratis. Requiere que Free shipping esté activado.
Segunda opción
Un segundo transportista de Andreani con su propio nombre, modalidad de entrega y contrato, por ejemplo "a domicilio" en el transportista principal y "retiro en sucursal" aquí, para ofrecer ambos. Todos los demás ajustes son compartidos.
Enable second option: activa o desactiva el segundo transportista. Es el mismo interruptor que su estado en Shipping > Carriers. Por defecto: desactivado.
Second option name: el nombre de esta opción en la finalización 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, recogida en sucursal). Déjalo vacío para usar el contrato general.
Selector de sucursal en la finalización de compra (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 logs/vfd_andr_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran. Las credenciales y los tokens nunca se registran.
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 el módulo se borran todos sus ajustes y los transportistas. Si está desactivado, al desinstalar solo se desactivan los transportistas. Los datos de sucursal guardados en los pedidos siempre se conservan.
Cómo funciona en la finalización de compra
En el paso de entrega, PrestaShop pide al módulo el precio de cada transportista de Andreani. Solo cuentan los productos físicos: los productos virtuales no suman peso ni se incluyen en el subtotal. El módulo 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.
En el modo fijo, el precio se toma de Country prices. En los modos en tiempo real, el módulo 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 a partir de las dimensiones de los productos y el valor declarado (el subtotal del carrito en ARS). Solo se pide una tarifa en tiempo real para un código postal argentino válido. El importe en ARS se convierte con el ARS exchange rate cuando la moneda de tu tienda no es el ARS. El precio se calcula en la moneda predeterminada de tu tienda y después se muestra en la moneda que el cliente tiene seleccionada en el carrito.
El token de inicio de sesión se guarda en caché durante 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. Los errores de la API nunca se muestran al cliente: el transportista 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 gratis solo se aplica donde el transportista tiene precio: si la API de Andreani no devuelve tarifa y no hay precio fijo al que recurrir, el transportista no se muestra.
Si editas un 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 no crea envíos de Andreani, no imprime etiquetas ni hace seguimiento de paquetes. Para ello, usa el portal web de Andreani.
Puntos de recogida
Cuando se selecciona un transportista con Door to branch o Branch to branch, aparecen debajo, en el paso de entrega, una lista de provincias y una lista de sucursales. La provincia se preselecciona a partir de la dirección de entrega. La lista de sucursales procede de la API pública de sucursales de Andreani y se guarda en caché durante 12 horas. No se incluyen las sucursales que no entregan paquetes. 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 el carrito 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 y el botón de pedido en el paso de pago no avanzan, 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.
Una sucursal elegida en Andreani antes de que el cliente cambiara a otro transportista no forma parte del pedido.
Pedidos
El pedido guarda la modalidad de entrega y, para las modalidades con sucursal, la sucursal elegida.
Admin order page: un bloque de Andreani muestra la modalidad y la sucursal (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. Solo se pueden guardar sucursales de la lista de Andreani. Si la lista no está disponible, no se puede cambiar la sucursal.
Cliente: la sucursal se muestra como Andreani pickup branch: en la página de confirmación del pedido y en la página de detalles del pedido.
E-mails: en el correo de confirmación del pedido y en el correo de nuevo pedido a la tienda (módulo Mail alerts), la sucursal se añade al nombre del transportista. El correo a la tienda también muestra el ID de la sucursal.
Los pedidos existentes conservan sus datos de sucursal.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Andreani es el primer bloque de Modules > Module Manager > VibeFox Andreani > Configure, por 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 aparecen la línea Product: presta-shipping-andreani 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 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 el servidor de licencias no se puede contactar, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un 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, los transportistas de Andreani no se muestran a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda no sabe que has iniciado sesión en el back office, así que los transportistas también se ocultan para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio 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 necesitan 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 después de introducir la clave y después una vez por semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Andreani no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado (en el segundo transportista, también Enable second option). En Shipping > Carriers, comprueba que el transportista cubre la zona del país del cliente y su grupo de clientes, o activa Ignore shipping zones y revisa Countries. Comprueba que Country prices tiene una línea para el país (para precios fijos o como respaldo), y revisa los límites de peso y el Minimum subtotal. Lee las advertencias de la parte superior de la página Configure. Además, los productos pueden limitarse a ciertos transportistas en la página del producto.
Las tarifas en tiempo real no aparecen: activa Debug log, recarga la finalización de compra y mira el campo Log de la página del módulo. Muestra el motivo: faltan las credenciales o el número de contrato, un inicio de sesión fallido (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 viendo el precio fijo mientras corriges el problema.
Mi tienda no está en pesos argentinos: define 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 regla de impuesto en Tax status, se usa la tarifa de Andreani sin IVA y PrestaShop 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 y que la regla de impuesto esté configurada para Argentina.
No hay sucursales en la lista: la API de sucursales de Andreani no respondió. Una solicitud fallida se reintenta después de 5 minutos. Revisa el registro.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra el token, la lista de sucursales y las tarifas guardadas en caché.
La página indica que no se encontró un transportista de Andreani: 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 Andreani y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. El token, la lista de sucursales y las tarifas guardadas en caché también se eliminan siempre. Si Remove data on uninstall está activado, los transportistas se borran (los pedidos conservan su historial), y se eliminan los ajustes, el registro y las elecciones de sucursal de los carritos sin pedido. Si está desactivado, los transportistas solo se desactivan y todos los ajustes se conservan. Volver a instalar el módulo, o un Reset del módulo, devuelve a ambos transportistas su estado anterior. Los datos de sucursal guardados en los pedidos nunca se borran.
Andreani es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Andreani ni cuenta con su respaldo.