VibeFox Instabee 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.

Credenciales de la API de Budbee (solo para la selección de caja de paquetes): una clave de API y un secreto de API. Instabee los entrega a los comerciantes con un acuerdo de entrega. Pregunta a tu contacto de Instabee o usa el portal de comerciantes de Instabee. La documentación de la API está en developer.budbee.com. Sin credenciales, el método sigue funcionando con precios fijos, pero los clientes no pueden elegir una caja de paquetes.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_instabee-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_instabee.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_instabee-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, 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 Instabee 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 License key, en el bloque de licencia de la parte superior de la página Edit, y haz clic en Activate (consulta Clave de licencia).

5. Completa la sección Prices y, para el selector de caja de paquetes, tu API key y tu API secret de Budbee (consulta 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_instabee.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 de extensión Shipping. Busca VibeFox Instabee, 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, el método está desactivado hasta que actives Enable/Disable y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usarán de nuevo los ajustes de Instabee que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Instabee > Edit. Las secciones aparecen a la izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra las listas de cajas de paquetes en caché y el último error de la API. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

Los avisos sobre los ajustes te indican cuando solo se ha introducido una de las credenciales de la API, cuando no hay credenciales de la API, cuando no hay precios por país ni coste de reserva, cuando la última solicitud a la API de Budbee falló (con fecha, hora y motivo) y cuando la tienda no tiene una clase de peso con la unidad kg y la unidad de la clase de peso predeterminada no se reconoce (en ese caso, los pesos se tratan como kg; añade una clase de peso kg en System > Localisation > Weight Classes).

Si Method name está vacío o es demasiado largo, Min weight (kg) es mayor que Max weight (kg), Sort order no es un número entero, o la clase de impuesto o la zona geográfica no existen, no se guarda nada y se muestra un error.

General

Enable/Disable: muestra u oculta Instabee en la finalización de compra. Predeterminado: off.

Method name: el nombre del método de envío que se muestra al cliente en la finalización de compra. Predeterminado: Instabee parcel box. Obligatorio, máximo 64 caracteres.

Tax class: None (the prices are final) (predeterminado) significa que los precios de abajo son finales. Una clase de impuesto añade el impuesto de envío de esa clase sobre los precios de abajo.

Sort order: la posición de Instabee entre los métodos de envío de la finalización de compra. Un número entero.

Selector de caja de paquetes (API de Budbee)

Con credenciales de la API, el cliente elige en la finalización de compra una caja de paquetes cerca de su código postal, y la caja se guarda en el pedido. Se necesitan ambos campos. El selector permanece desactivado hasta que se rellenen los dos.

API key: tu clave de API de Budbee (el nombre de usuario HTTP Basic).

API secret: tu secreto de API de Budbee (la contraseña HTTP Basic). Nunca se escribe en el registro.

Después de guardar, ambos campos quedan vacíos y muestran Saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Para borrar las credenciales guardadas, marca Remove the saved API key and secret y guarda. Cuando no hay nada guardado, la página muestra No credentials saved.

Test environment: usa la API de pruebas de Budbee (api.staging.budbee.com). Actívalo solo con credenciales de pruebas de Instabee. Las tiendas en producción lo dejan desactivado (api.budbee.com). Predeterminado: off.

Precios (el título de la sección muestra la moneda predeterminada de tu tienda)

Todos los precios están en la moneda predeterminada de la tienda, sin impuestos. Se aceptan tanto la coma como el punto decimal (49,90 = 49.90). El precio se muestra al cliente en su moneda.

Calculation type: cómo se aplica el precio.

Country prices: una tabla con las columnas Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg y XL >5 kg. Haz clic en Add country para añadir una fila y en el botón × para eliminar una. Elige * Any other country para una fila que se aplique a todos los países sin fila propia. Un tramo vacío o 0 usa la columna Price. Un Price de 0 significa envío gratuito. Si la fila del país no tiene precio para el peso del carrito, se usa la fila * y después el Fallback cost. Al guardar, un precio que no sea un número igual o mayor que 0 se borra y una fila con un país desconocido se elimina; un aviso las enumera. Los pesos de los productos se convierten de su clase de peso de OpenCart a kg.

Fallback cost: se usa cuando ni la fila del país de destino ni la fila * dan un precio. Déjalo vacío para ocultar el método en esos países.

Condiciones

Min weight (kg): oculta el método por debajo de este peso del carrito. Predeterminado: 0 (sin límite).

Max weight (kg): oculta el método por encima de este peso del carrito. Las cajas de paquetes admiten hasta unos 20 kg. Predeterminado: 20. 0 significa sin límite. No puede ser menor que Min weight (kg).

Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.

Free shipping from: el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual el método es gratuito. Déjalo vacío para que nunca sea gratuito.

Si un valor de estos campos o de Fallback cost no es un número igual o mayor que 0, no se guarda, se mantiene el valor anterior y un aviso indica el campo.

Disponibilidad

Geo zone: ofrece Instabee solo para direcciones de esta zona geográfica. All zones (predeterminado) significa en todas partes. La zona geográfica no se comprueba cuando Ignore shipping zones está activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.

Ignore shipping zones: cuando está activado, no se comprueba la Geo zone y el método se ofrece para los países de abajo. Cuando está desactivado (predeterminado), solo se aplica la Geo zone.

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

Avanzado

Debug log: escribe mensajes de depuración en storage/logs/vfd_ibee_debug.log.php (en OpenCart 4, system/storage/logs/vfd_ibee_debug.log.php). El archivo no se puede leer desde la web. Los errores de la API y los pedidos realizados sin caja mientras la API funcionaba siempre se registran, incluso cuando está desactivado. Las claves de API y los datos de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se traslada a vfd_ibee_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: cuando está activado, al desinstalar la extensión se eliminan los ajustes, las listas de cajas en caché, el registro y las cajas de finalizaciones de compra sin terminar. Cuando está desactivado (predeterminado), los ajustes se conservan para una reinstalación. Las cajas de paquetes guardadas en los pedidos siempre se conservan.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave y el secreto de la API no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. La clave y el secreto de la API guardados se conservan.

Funcionamiento en la finalización de compra

Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de Instabee. Con Ignore shipping zones activado, Instabee se ofrece solo cuando el país está permitido (no se comprueba la zona geográfica). En caso contrario, si hay una Geo zone definida y la dirección está fuera de ella, Instabee no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no añaden peso y no se incluyen en el importe del pedido. El importe del pedido es el precio de los productos que necesitan envío, después del descuento del cupón y antes de impuestos. La extensión comprueba el peso del carrito y el importe mínimo del pedido. Si el subtotal alcanza Free shipping from, el precio es 0. En otro caso, el precio se toma de la fila de Country prices del país de destino, de la fila * o del Fallback cost. Si no hay precio, el método se oculta. El precio se calcula en tu moneda predeterminada, se redondea a sus decimales y se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada.

Cuando el cliente selecciona Instabee en el paso de método de entrega y las credenciales de la API están configuradas, aparece un bloque Parcel box bajo el método para Suecia, Finlandia, Dinamarca, los Países Bajos y Bélgica. Muestra las cajas cercanas al código postal de la dirección de entrega, ordenadas por distancia, con el nombre, la dirección y la distancia. El cliente puede escribir otro código postal y hacer clic en Search (o pulsar Intro). Hasta que se introduzca un código postal, el bloque lo pide. Si no se encuentran cajas, se pide al cliente que pruebe con otro código postal o que elija otro método de envío. Para otros países, el método se ofrece sin caja.

La caja de paquetes es obligatoria. La caja elegida se guarda para la finalización de compra solo si está en la lista de Budbee para ese código postal. Un código postal escrito sin hacer clic en Search no se usa. Cuando el cliente hace clic en Continue en el paso de método de entrega, la extensión vuelve a comprobar la caja en el servidor. Si no, el cliente ve Please choose an Instabee parcel box. El nombre de la caja se toma de la lista de Budbee, no del navegador. Si el cliente cambia el país de entrega o el código postal de la dirección, se descarta la elección anterior.

En OpenCart 4, el cliente hace clic en Choose en el bloque de método de envío de la página de finalización de compra y elige Instabee en la ventana Shipping method options. El bloque Parcel box aparece en esa ventana, debajo de la opción de Instabee, y funciona del mismo modo. El botón Continue de la ventana no avanza sin una caja de la lista, con los mismos mensajes.

La extensión envía a Budbee solo el país de destino y el código postal, nunca nombres, direcciones, correos electrónicos ni datos de pedidos. Las listas de cajas se guardan en caché durante 12 horas por código postal, un código postal sin cajas durante 1 hora y una solicitud fallida durante 5 minutos, para que una API lenta o averiada no ralentice cada actualización de la finalización de compra. La página de finalización de compra nunca espera a Budbee: la lista se carga en segundo plano en cuanto se selecciona el método. El tiempo de espera de la API es de 10 segundos.

Si no se puede acceder a la API de Budbee, el cliente ve Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. El pedido queda marcado y eliges la caja cuando reservas el envío. Una caja elegida antes que no pueda comprobarse en ese momento se conserva y se marca como no verificada.

La extensión no calcula tarifas en tiempo real, no reserva envíos, no imprime etiquetas, no proporciona números de seguimiento ni correos de seguimiento, no ofrece franjas horarias de entrega Budbee Home ni muestra un mapa. Reserva el paquete para la caja elegida en tus herramientas de comerciante de Instabee / Budbee.

Puntos de recogida

Cuando se crea el pedido, la caja se vuelve a comprobar y se guarda en el pedido. A partir de ese momento, la tienda no puede cambiarla. En OpenCart 4, se mantiene un solo pedido para la finalización de compra y se actualiza cada vez que el cliente vuelve a confirmarlo, y la caja del pedido se actualiza con él. Si el cliente cambia ese pedido a otro método de envío, su caja se elimina. La caja se muestra en estos lugares:

Método de envío del pedido: la caja se añade al nombre del método, por ejemplo Instabee parcel box: (el nombre del método) seguido del nombre y la dirección de la caja. Este texto aparece en las páginas de pedidos del administrador y en la cuenta del cliente, en los correos de pedido y en la factura.

Página de pedido del administrador (Sales > Orders): un panel Instabee parcel box con el nombre de la caja, la dirección y el Box ID. Si la caja no pudo comprobarse en la finalización de compra, aparece marcada como not verified (Budbee API was unavailable at checkout). Si no se eligió caja porque la API no estaba disponible, el panel dice Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. El panel es solo de lectura y se muestra aunque el método esté desactivado. En OpenCart 4 se muestra encima de History.

Correo de nuevo pedido a la tienda: el nombre de la caja con su ID, o Instabee parcel box: not chosen (Budbee API unavailable at checkout).

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Instabee es el primero de la página Extensions > Extensions > Shipping > VibeFox Instabee > Edit, 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: opencart-shipping-instabee 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 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 una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, 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. 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, el método de envío de Instabee 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 se oculta para todo el mundo. Después de abrir una vez la página Edit, 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 necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del administrador 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 por semana. No se necesita ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Instabee no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable esté activado. Revisa Geo zone o, si Ignore shipping zones está activado, que el país esté permitido en Countries. Comprueba que el país tenga un precio, o que haya una fila * o un Fallback cost. Revisa los límites de peso y Minimum order amount, y que los productos tengan Requires Shipping en Yes. Un aviso sobre los ajustes te indica cuando no hay ningún precio configurado. Activa Debug log para ver el motivo en el campo Log.

Los clientes no ven la lista de cajas de paquetes: la lista aparece solo cuando API key y API secret están configurados, para Suecia, Finlandia, Dinamarca, los Países Bajos y Bélgica, y una vez introducido un código postal. El último error de la API se muestra sobre los ajustes. Los detalles están en el campo Log de la página de la extensión. Activa Debug log para más detalle.

HTTP 401 o 403 en el registro: Budbee rechazó la clave o el secreto de la API. Compruébalos y verifica que Test environment coincide con tus credenciales (las credenciales de pruebas solo con el entorno de pruebas activado).

No hay cajas para un código postal: Budbee no da servicio a ese código postal. El cliente puede buscar otro código postal o elegir otro método de envío.

El cliente no puede continuar desde el paso de método de entrega: hay que elegir una caja de la lista, salvo que no se pueda acceder a la API de Budbee. Una caja que no está en la lista del código postal buscado no se guarda, y el cliente ve This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Listas de cajas antiguas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las listas de cajas en caché.

La página muestra «Warning: You do not have permission to modify VibeFox Instabee!»: tu grupo de usuarios administradores puede tener solo permiso para ver los ajustes. Concede al grupo el permiso de modificación para extension/shipping/vfd_instabee (OpenCart 3) o extension/vfd_instabee/shipping/vfd_instabee (OpenCart 4) en System > Users > User Groups.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Instabee. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable/Disable, Sort order, Tax class y Geo zone. Las listas de cajas en caché siempre se eliminan. Si Remove data on uninstall está activado, también se eliminan los ajustes, el registro y las cajas elegidas en finalizaciones de compra que nunca se convirtieron en pedidos. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Las cajas de paquetes guardadas en los pedidos siempre se conservan, y los pedidos existentes mantienen su método y coste de envío.

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 Instabee en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Instabee y Budbee son marcas comerciales de sus respectivos propietarios. Esta extensión no está afiliada ni respaldada por Instabee ni por Budbee.