VibeFox bpost Cubee 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 bpost Shipping Platform (solo para el selector de puntos de recogida): el módulo busca puntos de recogida a través de la API de bpost Shipping Platform. Inicia sesión en tu cuenta de bpost Shipping Platform en plugins.bpost.be y crea las claves en Settings > Key management. Necesitas tres valores: Account ID (clave pública), Passphrase (clave privada) y un App ID (X-APPID). El App ID lo emite bpost para tu integración; pídelo al soporte de comercio electrónico de bpost (eol@bpost.be). También necesitas el ID del transportista de tu contrato (68 = bpost). Sin claves completas, el transportista sigue funcionando con precios fijos, pero no se pide a los clientes que elijan un punto de recogida.
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 carga, haz clic en Configure, o busca VibeFox bpost Cubee más tarde en la lista de módulos 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 (ver Clave de licencia).
4. Introduce tus precios y, para el selector de puntos de recogida, las claves API de bpost (véase Configuración). Haz clic en Save.
Al instalar, el módulo crea el transportista bpost parcel locker con el texto del tiempo de entrega Pickup point or parcel locker. El transportista se vincula a la zona de Bélgica y a todos los grupos de clientes, sin regla de impuesto. Puedes cambiar las zonas, los grupos de clientes, el tiempo de entrega y el logotipo 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 bpost Cubee > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra el token de API almacenado y las listas de puntos de recogida en caché.
La página muestra avisos cuando algo oculta en silencio el transportista o el selector: el selector de puntos de recogida está activado pero las claves API están incompletas, no hay precio para Bélgica (BE) ni precio por defecto, la última conexión con la API de bpost falló, el módulo no reconoce la unidad de peso de la tienda (configúrala en International > Localization, Local units), o no se encontró el transportista de bpost. Al guardar, se enumeran en un aviso las líneas de Country prices que no se pudieron leer, y también un valor de Size prices en el que no se reconoció ningún tamaño. Un peso o un importe que no sea un número o sea negativo no se guarda: un aviso indica el campo y se mantiene el valor anterior. Si Min weight (kg) es mayor que Max weight (kg), tampoco se guardan los pesos.
General
Enable/Disable: activa o desactiva el envío con bpost parcel locker. 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 en la finalización de compra (el nombre del transportista). Por defecto: bpost parcel locker. Si lo dejas vacío, se usa el valor por defecto. Máximo 64 caracteres; un nombre más largo se rechaza y no se guarda nada.
Tax status: None significa que los precios son definitivos. Taxable con una regla de impuesto añade el impuesto de esa regla sobre tus precios. La elección se guarda en el transportista.
API de bpost (búsqueda de puntos de recogida) (necesaria solo para el selector de puntos de recogida)
Account ID (public key): la clave pública de tu cuenta de bpost Shipping Platform, desde Key management en plugins.bpost.be. Vaciar este campo también elimina la Passphrase guardada.
Passphrase (private key): la clave privada que se usa para firmar cada solicitud (HMAC-SHA256). Nunca se envía a bpost ni se escribe en el registro. Tras guardar, el campo queda vacío y muestra Saved - leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.
App ID (X-APPID): el identificador de aplicación que bpost emitió para tu integración. Se envía en la cabecera X-APPID.
Carrier ID: el transportista de tu contrato de bpost Shipping Platform cuyos puntos de recogida y taquillas se listan. Por defecto: 68 (bpost). Los demás transportistas activados en tu contrato tienen sus propios ID.
Selector de punto de recogida
Pickup points: muestra el selector de puntos de recogida y taquillas en la finalización de compra. Activado por defecto. El selector aparece, y se exige un punto de recogida, solo cuando las tres claves API están completas.
Search field width: el ancho CSS del campo de código postal / ciudad, por ejemplo 100% o 300px. Por defecto: 100%.
Pickup point list width: el ancho CSS de la lista de puntos de recogida, por ejemplo 100% o 400px. Por defecto: 100%.
Precios (en la moneda predeterminada de tu tienda, sin impuestos; bpost no devuelve tarifas de envío a través de esta API)
Price by: cómo se elige el precio.
Country prices: una línea por país con la forma CC=PRECIO, por ejemplo BE=4.95. La línea *=PRECIO fija el precio para todos los demás países, por ejemplo *=9.95. Se aceptan tanto el punto como la coma como separador decimal. Las líneas no válidas se ignoran. Los países sin precio (cuando no hay línea *) no ofrecen el transportista.
Size prices: se usa cuando Price by es tamaño del paquete, con la forma S=3.50, M=4.50, L=6.00, XL=8.00. El tamaño se determina por el peso del carrito: S hasta 2 kg, M hasta 5 kg, L hasta 10 kg, XL por encima.
Calculation: Per order cobra el precio una vez. Per item (price x number of items) lo multiplica por el número de artículos del carrito.
Los precios se redondean a los decimales de tu moneda predeterminada y luego se muestran en la moneda del carrito del cliente.
Condiciones
Min weight (kg): el peso mínimo del carrito para que aparezca el transportista. Los pesos de los productos se convierten desde la unidad de peso de tu tienda. 0 significa sin límite.
Max weight (kg): el transportista se oculta por encima de este peso del carrito. Por defecto: 30, porque las taquillas de bpost aceptan paquetes de hasta 30 kg. 0 significa sin límite.
Minimum order amount: muestra el transportista solo cuando el subtotal del carrito alcanza este importe. El subtotal cuenta los productos que necesitan envío, después de descuentos y sin impuestos. Déjalo vacío para mostrar siempre el transportista.
Envío gratuito
Free shipping: activa la entrega gratuita a partir del importe indicado abajo.
Free shipping from: el subtotal del carrito (productos que necesitan envío, después de descuentos y sin impuestos) a partir del cual el envío es gratuito. Solo se usa cuando Free shipping está activado. El país sigue necesitando un precio; si no, no se ofrece el transportista.
Disponibilidad sin zonas de envío
Normalmente el transportista se ofrece en sus zonas de envío en Shipping > Carriers. Al instalar, esa es la zona de Bélgica.
Ignore shipping zones: ofrece el transportista en los países indicados abajo sin añadirlo a una zona. El transportista se vincula entonces a todas las zonas activas, también a las zonas que crees más adelante. Cuando desactivas la opción de nuevo, el transportista recupera sus zonas anteriores.
Countries: los países de destino para ese modo. Por defecto: Bélgica. Déjalo vacío para usar todos los países a los que envías. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra las solicitudes a la API y los cálculos de precios en logs/vfd_bpst_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, incluso con esta opción desactivada. Las claves y los tokens nunca se registran.
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 el módulo se borran sus ajustes y el transportista. Los puntos de recogida guardados en los pedidos siempre 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 bpost. Solo cuentan los productos que necesitan envío: los productos virtuales no suman peso y no se incluyen en el importe del pedido. El módulo comprueba las condiciones: los países de Ignore shipping zones (si está activado), el peso del carrito y el importe mínimo del pedido. Después toma el precio de la lista de países o por tamaño de paquete, lo multiplica por el número de artículos en el modo por artículo y lo pone a cero cuando aplica el envío gratuito. No se envía ninguna solicitud a bpost para calcular el precio.
Debajo del transportista de bpost, el cliente ve un campo Postal code or city, un botón Search y una lista de puntos de recogida. Cuando el cliente elige el transportista y todavía no ha buscado, el código postal de la dirección de entrega se busca automáticamente. El cliente puede escribir otro código postal o el nombre de una ciudad. Cada punto se muestra con su nombre y dirección. Se listan hasta 50 puntos. La lista se solicita en neerlandés cuando el idioma de la tienda es neerlandés, y en francés en los demás casos.
El cliente debe elegir un punto de recogida. Sin él, Continue en el paso de entrega muestra Please select a bpost pickup point., y el botón Place order se bloquea en la página con el mismo mensaje. Solo se acepta un punto de la lista de bpost para la búsqueda. En otro caso, el cliente ve The selected bpost pickup point is not in the list of your search. Please choose another one. La búsqueda y la elección se guardan con el carrito, de modo que recargar la página no las pierde. Una nueva búsqueda borra la elección anterior.
Para listar los puntos de recogida, el módulo envía a bpost solo el código postal o la ciudad buscados, el país y el ID del transportista, firmados con tus claves. El token de la API se solicita y se renueva automáticamente. Si bpost rechaza un token, se solicita uno nuevo una vez y se repite la búsqueda. Los resultados de búsqueda se guardan en caché durante 6 horas. Si bpost no responde, el cliente ve Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. y el módulo vuelve a intentarlo tras 5 minutos. El tiempo de espera de la API es de 15 segundos.
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 usa solo precios fijos. No obtiene tarifas en tiempo real de bpost, no crea envíos, no imprime etiquetas ni hace seguimiento de paquetes. Los puntos de recogida se muestran como una lista, no en un mapa. Crea los envíos en tu cuenta de bpost Shipping Platform o Shipping Manager; el ID del punto de recogida está en el pedido.
Puntos de recogida
Cuando se realiza el pedido, el punto de recogida elegido (nombre y dirección) y su ID se guardan con el pedido. En la página del pedido del back office, el bloque bpost pickup point muestra el punto y su ID, o No pickup point was selected for this order. Haz clic en Change, busca un código postal o una ciudad, elige otro punto de la lista y haz clic en Save. El pedido se actualiza al momento y la página muestra Pickup point updated. El cambio se escribe en el registro de depuración cuando Debug log está activado. El enlace Change solo está disponible cuando las claves API están completas. Guardar un punto nuevo requiere el permiso para editar pedidos; si no, la página muestra Permission denied. No hace falta acceso a las páginas de Módulos.
Si PrestaShop divide un carrito en varios pedidos, el punto de recogida se queda con el primer pedido. Los demás pedidos no tienen punto de recogida, y el registro de depuración muestra un error con el nombre del primer pedido; asigna el punto de esos paquetes a mano en bpost.
Los clientes ven el punto de recogida como bpost pickup point: en la página de confirmación del pedido y en los detalles del pedido de su cuenta. También se añade al nombre del transportista en el correo electrónico de confirmación del pedido. El correo de nuevo pedido a la tienda (si usas el módulo de alertas por correo electrónico) también contiene el ID del punto.
Para ofrecer taquillas y entrega a domicilio juntas, usa otro transportista para la entrega a domicilio en la misma zona. El selector de puntos de recogida aparece solo con el transportista de bpost.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox bpost Cubee es el primer bloque de Modules > Module Manager > VibeFox bpost Cubee > Configure, por encima de los ajustes. Introduce 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-bpost-cubee 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 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 con 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, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo 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, el transportista de bpost no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La parte pública de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también queda oculto 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 por 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
bpost no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. En Shipping > Carriers comprueba que el transportista cubre la zona del país del cliente y el grupo del cliente, o que Ignore shipping zones está activado y el país está en Countries. Comprueba que el país tenga un precio o que exista una línea *=PRECIO, y revisa los límites de peso y el Minimum order amount. Los productos también pueden estar limitados a ciertos transportistas en la página del producto. La página de ajustes muestra un aviso cuando Bélgica no tiene precio.
No aparece el selector de puntos de recogida en la finalización de compra: comprueba que Pickup points esté activado y que Account ID (public key), Passphrase (private key) y App ID (X-APPID) estén rellenados. La página de ajustes muestra un aviso cuando las claves están incompletas.
Los clientes ven "Pickup points cannot be loaded right now": bpost no respondió o rechazó las claves. El motivo se muestra en la página de ajustes y en el registro de depuración (campo Log en la página del módulo). El módulo reintenta automáticamente tras 5 minutos. Guardar los ajustes reintenta de inmediato.
No se encontraron puntos de recogida para este código postal o ciudad: bpost no devolvió puntos para esa búsqueda. Pide al cliente que pruebe un código postal cercano o el nombre de una ciudad, y comprueba el Carrier ID.
Los precios con coma no se usan: se aceptan tanto 5,50 como 5.50. Las líneas de Country prices que no siguen la forma CC=PRECIO se ignoran; el aviso tras guardar las enumera.
¿Los precios incluyen impuestos? Con Tax status en None, los precios son definitivos. Con una regla de impuesto Taxable, PrestaShop añade ese impuesto sobre tus precios.
La página indica que no se encontró el transportista de bpost: el transportista se borró en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Para desarrolladores, los hooks actionVfdBpstApiUrl y actionVfdBpstApiLanguage cambian la dirección de la API de bpost y el idioma de la lista de puntos de recogida.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox bpost Cubee y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. El token de API almacenado y las listas de puntos de recogida en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se borra (los pedidos conservan su historial), y se eliminan los ajustes, el registro y los puntos de recogida de los carritos sin terminar. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Volver a instalar el módulo devuelve al transportista el estado que tenía antes de la desinstalación. Reset en Modules > Module Manager funciona igual, así que un transportista desactivado sigue desactivado. Los puntos de recogida guardados en los pedidos forman parte del historial de pedidos y nunca se borran.
bpost es una marca comercial de su respectivo titular. Este módulo no está afiliado a bpost ni cuenta con su respaldo.