VibeFox bpost Cubee for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Cuenta de bpost Shipping Platform (solo para el selector de puntos de recogida): la extensión 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; pide información al soporte de comercio electrónico de bpost (eol@bpost.be). También necesitas el ID de transportista de tu contrato (68 = bpost). Sin claves completas, el método sigue funcionando con precios fijos, pero no se pide al cliente que elija un punto de recogida.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.
Instalación
El paquete de 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_bpost_cubee-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_bpost_cubee.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_bpost_cubee-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, también puedes copiar el contenido de la carpeta upload del paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox bpost Cubee 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 configuración.
4. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Edit y haz clic en Activate (ver Clave de licencia).
5. Introduce tus precios, por ejemplo BE=4.95 y *=9.95, y, para el selector de puntos de recogida, las claves de API de bpost (ver Configuración). Activa Enable/Disable y haz clic en Save.
OpenCart 4
1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_bpost_cubee.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 Shipping. Busca VibeFox bpost Cubee, 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 configuración y sus campos son los mismos en ambas versiones.
Después de la instalación, el método está desactivado hasta que lo actives y guardes. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra el token de API almacenado y las listas de puntos de recogida en caché. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar la configuración.
Algunos errores detienen el guardado y no se guarda nada: un Name de más de 64 caracteres, un Sort Order que no es un número entero, o una clase de impuesto o zona geográfica desconocida. Otros problemas se notifican como advertencias y el resto se guarda: un peso o importe que no es un número o es negativo no se guarda y se mantiene el valor anterior; si Min weight (kg) es mayor que Max weight (kg), los pesos no se guardan; las líneas de Country prices que no se pudieron leer se listan y se ignoran; un valor de Size prices en el que no se reconoció ningún tamaño se notifica.
La parte superior de la página avisa cuando algo oculta silenciosamente el método o el selector: el selector de puntos de recogida está activado pero las claves de API están incompletas, no hay precio para Bélgica (BE) ni precio predeterminado (*=PRECIO), la última conexión con la API de bpost falló, o la tienda no tiene una clase de peso con la unidad "kg" (System > Localisation > Weight Classes). En este último caso, los pesos de los productos se leen según el nombre de su unidad (kg, g, lb u oz).
General
Enable/Disable: activa o desactiva el envío a taquillas de bpost en la finalización de compra. Predeterminado: desactivado.
Name: el nombre del método de envío que ve el cliente en la finalización de compra. Predeterminado: bpost parcel locker. Si lo dejas vacío, se usa el predeterminado. Como máximo 64 caracteres.
Tax Class: el impuesto de esta clase se suma a tus precios. --- None --- (predeterminado) significa que los precios son definitivos.
Sort Order: la posición del método en la lista de métodos de envío.
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. Al borrar este campo también se 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. Predeterminado: 68 (bpost). Otros transportistas habilitados 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 es obligatorio elegir un punto, solo cuando Account ID, Passphrase y App ID están todos rellenados.
Search field width: el ancho CSS del campo de código postal / ciudad, por ejemplo 100% o 300px. Predeterminado: 100%.
Pickup point list width: el ancho CSS de la lista de puntos de recogida, por ejemplo 100% o 400px. Predeterminado: 100%.
Precios (en la moneda predeterminada de tu tienda, sin impuestos; bpost no devuelve precios 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 en la forma CC=PRECIO, por ejemplo BE=4.95. La línea *=PRECIO establece 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 reciben el método.
Size prices: se usa cuando Price by es tamaño de paquete, en la forma S=3.50, M=4.50, L=6.00, XL=8.00. El tamaño se calcula según el peso del carrito: S hasta 2 kg, M hasta 5 kg, L hasta 10 kg, XL por encima.
Calculation: Per order (predeterminado) 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 la moneda predeterminada de tu tienda y luego se muestran en la moneda del cliente.
Condiciones
Min weight (kg): el peso mínimo del carrito para que aparezca el método. Los pesos de los productos se convierten a kg. 0 significa sin límite (predeterminado).
Max weight (kg): el método se oculta por encima de este peso del carrito. Predeterminado: 30, porque las taquillas de bpost aceptan paquetes de hasta 30 kg. 0 significa sin límite.
Minimum order amount: muestra el método solo cuando el subtotal del carrito alcanza este importe. El subtotal cuenta los productos que necesitan envío, después de cupones y sin impuestos. Déjalo vacío para mostrar siempre el método.
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 cupones 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, el método no se ofrece.
Disponibilidad
Normalmente el método se ofrece en la zona geográfica seleccionada abajo. Con Ignore geo zone se ofrece en los países de la lista.
Geo Zone: ofrece el método solo para direcciones de esta zona geográfica. All Zones (predeterminado) significa en todas partes. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore geo zone: ofrece el método en los países de la lista, sea cual sea la zona geográfica.
Countries: los países de destino para ese modo. Predeterminado: Belgium. Déjalo vacío para permitir todos los países. Solo se usa cuando Ignore geo zone está activado.
Avanzado
Debug log: escribe las solicitudes a la API y los cálculos de precios en storage/logs/vfd_bpst_debug.log.php. El archivo no se puede leer 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 entradas más recientes del registro de depuración. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: cuando está activado, al desinstalar la extensión se borran la configuración, el registro y las elecciones de puntos de recogida de los pedidos no finalizados. Los puntos de recogida guardados en los pedidos siempre se conservan. Predeterminado: desactivado.
Importar / Exportar
Export: haz clic en Download JSON para guardar la configuración como archivo JSON. La passphrase no se exporta.
Import: pega un JSON exportado anteriormente y haz clic en Import para restaurar la configuración, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. La passphrase guardada se conserva.
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 bpost. Si hay una Geo Zone definida (y Ignore geo zone está desactivado) y la dirección queda fuera, el método no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no suman peso ni se incluyen en el importe del pedido. La extensión comprueba las condiciones: los países de Ignore geo zone (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 se aplica el envío gratuito. No se envía ninguna solicitud a bpost para calcular el precio.
Bajo la opción 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 bpost y la lista aún no está cargada, se busca automáticamente el código postal de la dirección de entrega (o la última búsqueda del cliente). El cliente puede introducir 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 pide 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 uno, Continue en el paso del método de envío muestra Please select a bpost pickup point. Solo se acepta un punto de la lista de bpost para la búsqueda. Si no, 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 para la finalización de compra, así que recargar la página no las pierde. Una nueva búsqueda borra la elección anterior.
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 bpost en la ventana Shipping method options. La búsqueda y la lista de puntos de recogida aparecen en esa ventana, bajo la opción de bpost. Continue en la ventana sin punto de recogida muestra Please select a bpost pickup point. El resto funciona igual que en OpenCart 3.
Para listar los puntos de recogida, la extensión envía a bpost solo el código postal o la ciudad buscados, el país y el ID de transportista, firmados con tus claves. El token de 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 hasta 6 horas, pero no más que la vida útil de la caché de OpenCart (1 hora por defecto). 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 la extensión vuelve a intentarlo tras 5 minutos. El tiempo de espera de la API es de 15 segundos.
La extensión 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 la página de pedido del administrador.
Puntos de recogida
Cuando se realiza el pedido, el punto de recogida elegido se añade al método de envío del pedido como bpost pickup point: con el nombre y la dirección del punto, por ejemplo "bpost parcel locker - bpost pickup point: …". Por tanto, el cliente lo ve en la confirmación del pedido, en el historial de pedidos de su cuenta, en los correos electrónicos del pedido y en la factura. El punto completo, con su ID, también se guarda en una tabla aparte de la extensión. En OpenCart 4 la finalización de compra mantiene un solo pedido: si el cliente vuelve a confirmar el pedido, por ejemplo tras elegir otro punto de recogida, se actualiza el punto del pedido.
En el administrador, la página del pedido en Sales > Orders muestra el panel bpost pickup point con 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 y el texto de su método de envío se actualizan al momento y la página muestra Pickup point updated. Si el punto no está en la lista de bpost para la búsqueda, la página muestra Pickup point not found in the bpost list of this search. El cambio se escribe en el registro de depuración cuando Debug log está activado. Change solo está disponible cuando las claves de API están rellenadas y el usuario del administrador puede modificar pedidos; no hace falta acceso a la configuración de la extensión.
Para ofrecer entrega en taquilla y a domicilio juntas, usa otro método de envío para la entrega a domicilio. El selector de puntos de recogida aparece solo bajo la opción de bpost.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox bpost Cubee es el primer bloque de Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit, encima de la configuración. 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-bpost-cubee 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 de 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 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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, bpost 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 administrador 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 está oculto para todos. Tras abrir la página Edit una vez, aparece un recordatorio en el Dashboard del administrador. 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 al abrir el Dashboard del administrador o la página Edit: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. No hace falta 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
bpost no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable/Disable está activado. Revisa Geo Zone, o que Ignore geo zone está activado y el país está en Countries. Comprueba que el país tiene un precio o que existe una línea *=PRECIO, y revisa los límites de peso y el Minimum order amount. Comprueba que los productos tienen Requires Shipping en Yes. La página de configuración muestra una advertencia 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 todos rellenados. La página de configuración muestra una advertencia 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 aparece en la parte superior de la página de configuración y en el registro de depuración (campo Log de la página de la extensión). La extensión vuelve a intentarlo automáticamente tras 5 minutos. Guardar la configuración vuelve a intentarlo de inmediato.
No se encuentran 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 el formato CC=PRECIO se ignoran; la advertencia tras guardar las enumera.
¿Los precios incluyen impuestos? Con Tax Class en --- None --- los precios son definitivos. Con una clase de impuesto, OpenCart añade ese impuesto sobre tus precios.
La página dice "Warning: You do not have permission to modify VibeFox bpost Cubee!": tu grupo de usuarios del administrador solo puede ver la configuración. Da al grupo el permiso de modificación para extension/shipping/vfd_bpost_cubee (OpenCart 3) o extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de bpost puede sustituirse con el ajuste vfd_bpst_api_url (para pruebas); no tiene campo en la página de configuración.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox bpost Cubee. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable/Disable, Sort Order, Tax Class y Geo Zone. El token de API guardado y las listas de puntos de recogida en caché siempre se eliminan. Si Remove data on uninstall está activado, la configuración, el registro y los puntos de recogida de los pedidos no finalizados 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 puntos de recogida guardados en pedidos forman parte del historial de pedidos y nunca se eliminan. 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 y haz clic en Uninstall (el botón naranja −) junto a VibeFox bpost Cubee en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
bpost es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por bpost.