VibeFox Balikobot 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 Balikobot (para tarifas en tiempo real y puntos de recogida): necesitas una cuenta de Balikobot con acceso a la API. El usuario de la API y la clave de la API están en la zona de cliente de Balikobot (client.balikobot.cz). El soporte de Balikobot (podpora@balikobot.cz) activa la API para tu cuenta y tus transportistas. Las tarifas en tiempo real requieren un transportista y un servicio para los que Balikobot admita "transportcosts". Los puntos de recogida requieren un transportista con soporte de "branchlocator" (por ejemplo, Česká pošta, Zásilkovna, PPL, DPD, GLS). Si no estás seguro, pregunta al soporte de Balikobot. Los precios fijos funcionan sin cuenta.
Clave de licencia de VibeFox: 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 Balikobot más tarde 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 Configure y haz clic en Activate (ver Clave de licencia).
4. Introduce el usuario y la clave de la API, elige el transportista y el tipo de servicio, la fuente del precio y los precios por país (ver Configuración). Para los servicios de recogida, activa Pickup point selection. Haz clic en Save.
Al instalar, el módulo crea el transportista Balikobot con el texto del plazo de entrega Delivery by Balikobot. El transportista se asigna a las zonas de Chequia, Eslovaquia y Hungría 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 viene del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Balikobot > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Después de guardar verás Settings saved. Cached rates and pickup points were cleared. En la parte superior de la página se muestran advertencias sobre los ajustes que ocultarían el transportista, las tarifas en tiempo real o los puntos de recogida: tarifas en tiempo real o puntos de recogida sin usuario o clave de la API, una moneda de la tienda distinta de CZK sin Exchange rate, Country prices vacío con precios fijos o con el modo de respaldo, una unidad de peso de la tienda que el módulo no reconoce (los pesos se leen entonces como kg; usa kg, g, lb u oz) y un transportista eliminado. Un valor que no es un número no se guarda, y verás una advertencia con el nombre del campo.
General
Enable/Disable: activa o desactiva el envío de Balikobot. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del método de envío que ve el cliente (el nombre del transportista). Por defecto: Balikobot. Obligatorio, máximo 64 caracteres.
Tax status: None, o Taxable con una de tus reglas de impuesto. Con una regla de impuesto, su impuesto se suma al precio del envío. La elección se guarda en el transportista. Los precios de Balikobot suelen ser sin IVA. Por defecto: None.
Cuenta de la API de Balikobot (necesaria para tarifas en tiempo real y puntos de recogida)
API user: tu usuario de la API de Balikobot de la zona de cliente.
API key: tu clave de la API de Balikobot de la zona de cliente. Después de guardar, el campo queda vacío y muestra Saved - leave empty to keep it. Clear the API user to remove the saved key. Escribe un valor nuevo solo para cambiarla.
Carrier: el transportista de Balikobot que se usa para tarifas y puntos de recogida: Česká pošta (por defecto), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) o Magyar Posta. Debe estar activado en tu cuenta de Balikobot.
Service type: el código de servicio de Balikobot del transportista. Por defecto: NP. Para Česká pošta: NP = paquete a una oficina de correos, NB = paquete a Balíkovna, DR = entrega a domicilio. Los códigos de otros transportistas aparecen en la zona de cliente de Balikobot y en la documentación de la API.
Precio (todos los precios están en la moneda predeterminada de tu tienda)
Price source: cómo se calcula el precio.
Country prices: una tabla de códigos de país de 2 letras (por ejemplo, CZ, SK) y precios. Haz clic en Add row para añadir un país y en el icono de papelera para eliminarlo. Usa * como código de país para todos los demás países. Decimales con punto o coma. Se usa en el modo fijo y como respaldo de la API. Un país sin precio (y sin una fila *) no tiene tarifa fija. Las filas no válidas se eliminan al guardar, y una advertencia las enumera.
Fixed price per: Order cobra el precio una vez. Item (price x quantity) lo multiplica por el número de artículos del carrito. Esto solo se aplica a los precios fijos. Una tarifa en tiempo real de Balikobot siempre es para todo el paquete.
Exchange rate: el valor de 1 unidad de la moneda del precio de Balikobot (normalmente CZK) en la moneda predeterminada de tu tienda, por ejemplo 0.04. Solo se usa cuando Balikobot devuelve un precio en otra moneda. Déjalo vacío para rechazar esos precios, de modo que el cliente nunca pague un precio incorrecto.
Condiciones
Min weight (kg): oculta el transportista cuando el carrito pesa menos. 0 significa sin límite. Los pesos de los productos se convierten desde la unidad de peso de tu tienda.
Max weight (kg): oculta el transportista cuando el carrito pesa más. Por defecto: 100. 0 significa sin límite. Un campo vacío significa 100 kg. Si Min weight (kg) es mayor que el máximo, verás una advertencia y se mantienen los pesos anteriores.
Minimum order amount: muestra el transportista solo a partir de este subtotal del carrito (después de descuentos, sin impuestos). Déjalo vacío para mostrarlo siempre.
Free shipping: activa el envío gratuito a partir del importe indicado abajo.
Free shipping from: el subtotal del carrito (después de descuentos, sin impuestos) a partir del cual el envío es gratuito. En ese caso no se hace ninguna petición a la API.
Disponibilidad sin zonas de envío
Normalmente el transportista se ofrece en sus zonas en Shipping > Carriers.
Ignore shipping zones: ofrece el transportista en los países indicados abajo aunque no esté vinculado a su zona. El módulo vincula el transportista a todas las zonas, también a las que crees más adelante. Al desactivar la opción, las zonas añadidas de este modo se eliminan de nuevo. Tus propias zonas se mantienen.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías. Se usa solo con Ignore shipping zones.
Puntos de recogida
Pickup point selection: el cliente debe elegir un punto de recogida. Úsalo para servicios de recogida, por ejemplo Česká pošta NP o NB, o Zásilkovna. Necesita el usuario y la clave de la API.
Selector width: el ancho CSS de la lista de puntos de recogida, por ejemplo 100% o 400px. Por defecto: 100%.
Avanzado
Debug log: registra las peticiones a la API y los cálculos de tarifas en logs/vfd_blkb_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran. Las credenciales y las direcciones de los clientes nunca se registran. Desactiva el registro cuando termines.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar el módulo se eliminan sus ajustes y el transportista. Desinstalar sin esta opción nunca elimina datos. Los puntos de recogida guardados en los pedidos se conservan.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de Balikobot. 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 los países (con Ignore shipping zones), el peso del carrito y Minimum order amount. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna petición a Balikobot.
En el modo fijo, el precio se toma de Country prices. En los modos en tiempo real, el módulo envía a Balikobot el transportista, el tipo de servicio, el país y el código postal de destino, y el peso del carrito en kg. Una tarifa en tiempo real solo se pide cuando la dirección de entrega tiene código postal. Un precio en otra moneda se convierte con Exchange rate, o se rechaza si no hay tipo de cambio. El precio se calcula en tu moneda predeterminada y después se muestra en la moneda del carrito del cliente.
Los precios en tiempo real se guardan en caché durante 1 hora, así que el mismo carrito no genera una nueva petición. Una petición fallida se guarda en caché durante 5 minutos, y el tiempo de espera de la API es de 12 segundos, para que la finalización de compra no espere a Balikobot en cada actualización. 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. Los detalles se envían al registro de depuración.
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 no crea envíos en Balikobot, no imprime etiquetas ni solicita recogidas: pide el envío en la zona de cliente de Balikobot. No hace seguimiento de paquetes ni actualiza los estados de los pedidos. Se usa un transportista y un tipo de servicio para todas las zonas. Los puntos de recogida se muestran como una lista desplegable, sin mapa.
Puntos de recogida
Con Pickup point selection activado, aparece una lista de puntos de recogida debajo del transportista de Balikobot en el paso de envío. La lista se carga desde el "branchlocator" de Balikobot para el país, la ciudad y el código postal de la dirección de entrega. Mientras la dirección no tenga ciudad, el cliente ve Enter your city to see the pickup points. La lista se guarda en caché durante 12 horas.
La elección se guarda en el carrito en cuanto el cliente selecciona un punto. Es obligatoria: Continue en el paso de envío y Place order se bloquean con Please select a pickup point. El servidor también comprueba que el punto elegido pertenezca a la dirección de entrega. Si no, el cliente ve The selected pickup point is not available for your shipping address. Please choose a pickup point again. Si no se encuentra ningún punto, se pide al cliente que revise la ciudad y el código postal o que elija otro método de envío. Si los puntos no se pueden cargar, se pide al cliente que lo intente más tarde o que elija otro método de envío.
El punto de recogida elegido se guarda en el pedido. En la página del pedido del back office se muestra en el bloque Balikobot pickup point, con el ID de sucursal de Balikobot y el transportista, que necesitas al crear el envío en Balikobot. Haz clic en Change para elegir otro punto cerca de la dirección del pedido y haz clic en Save. Cambiar el punto solo requiere el permiso para editar pedidos, no el acceso a las páginas de Módulos. Si un pedido no tiene punto, el bloque muestra No pickup point was selected for this order.
El cliente ve el punto como Pickup point: en la página de confirmación del pedido y en los detalles del pedido. En el correo de confirmación del pedido y en el correo de nuevo pedido para la tienda (módulo Mail alerts) aparece después del nombre del transportista. Los pedidos existentes conservan sus datos de punto de recogida.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Balikobot es el primer bloque de Modules > Module Manager > VibeFox Balikobot > Configure, 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-balikobot y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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 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 de liberar un dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, 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 dominio. Libera el dominio en tu cuenta de vibefox.net.
Sin una clave activa, el transportista de Balikobot no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda 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 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 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 después de 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
Balikobot no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. Lee las advertencias de la parte superior de la página del módulo. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y Minimum order amount. En el modo fijo, comprueba que el país o * tenga un precio. Los productos también 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 credenciales de la API, aún no hay código postal, el error de Balikobot para el transportista y el servicio (por ejemplo, authorization failed, comprueba el usuario y la clave de la API), o un precio en otra moneda sin Exchange rate. Con Live Balikobot rate, fixed price if the API fails, los clientes siguen viendo el precio fijo mientras corriges el problema.
Los precios están en la moneda equivocada: los precios fijos están en la moneda predeterminada de tu tienda. Balikobot devuelve las tarifas en tiempo real en la moneda de tu contrato con Balikobot (normalmente CZK). Si es distinta de la moneda predeterminada, configura Exchange rate.
¿Está incluido el IVA?: los precios de Balikobot suelen ser sin IVA. Con Tax status configurado con una regla de impuesto, PrestaShop añade el impuesto del envío.
No hay puntos de recogida en la lista: comprueba que el usuario y la clave de la API estén configurados, que el transportista admita "branchlocator" y que la dirección de entrega tenga ciudad y código postal. Revisa el registro para ver el error de Balikobot.
Las tarifas o los puntos de recogida parecen desactualizados después de un cambio: haz clic en Save en la página del módulo. Esto borra las tarifas y los puntos de recogida guardados en caché.
La página indica que no se encontró el transportista de Balikobot: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Para desarrolladores: el módulo tiene sus propios hooks para cambiar la dirección de la API (actionVfdBlkbApiUrl), el paquete "transportcosts" (actionVfdBlkbTransportcostsPackage) y el número de puntos de recogida (actionVfdBlkbPickupMaxResults, por defecto 30).
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Balikobot y elige Uninstall. La clave de licencia, el estado de la licencia, las tarifas y los puntos de recogida guardados en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial), y los ajustes, el registro y los puntos de recogida de los carritos sin pedido se eliminan. Si está desactivado, el transportista solo se desactiva y se mantienen todos los ajustes. Al instalar el módulo de nuevo (o al restablecerlo), el transportista guardado recupera el estado que tenía antes de la desinstalación: activado sigue activado, desactivado sigue desactivado. Los datos de punto de recogida guardados en los pedidos nunca se eliminan.
Balikobot es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Balikobot ni cuenta con su respaldo.