VibeFox Balikobot 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 Balikobot (para tarifas en tiempo real y puntos de recogida): necesitas una cuenta de Balikobot con acceso a la API. El usuario 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 necesitan un transportista y un servicio para los que Balikobot admita "transportcosts". Los puntos de recogida necesitan un transportista con soporte de "branchlocator" (por ejemplo Česká pošta, Zásilkovna, PPL, DPD, GLS). Si no estás seguro, consulta con el 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
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_balikobot-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_balikobot.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 panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_balikobot-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 Balikobot 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 del bloque de licencia, en la parte superior de la página Edit, y haz clic en Activate (consulta Clave de licencia).
5. Introduce el usuario y la clave de la API, elige el transportista, el tipo de servicio, la fuente del precio y los precios por país (consulta la sección Configuración). Para los servicios con recogida, activa Pickup point selection. Activa Enable/Disable y haz clic en Save.
OpenCart 4
1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_balikobot.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 Balikobot, 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 iguales en ambas versiones.
Al instalar, la extensión crea una tabla para los puntos de recogida de las finalizaciones de compra y de los pedidos. El método está desactivado hasta que actives Enable/Disable y guardes. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes de Balikobot que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Balikobot > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Tras guardar verás Settings saved. Cached rates and pickup points were cleared. Solo los usuarios administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
Algunos errores detienen el guardado y no se guarda nada: un Name vacío o demasiado largo, un Sort Order que no es un número entero, o una clase de impuesto o zona geográfica desconocida. Otros problemas se muestran como avisos y el resto de ajustes se guarda: un valor que no es un número (o es negativo) no se guarda y el aviso indica el campo; las filas no válidas de Country prices se eliminan y se enumeran.
Los avisos sobre ajustes que ocultarían el método, las tarifas en tiempo real o los puntos de recogida aparecen en la parte superior de la página: 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, y una tienda sin clase de peso con la unidad kg (los pesos de los productos se leen entonces por el nombre de su unidad: kg, g, lb u oz).
General
Enable/Disable: activa o desactiva el envío con Balikobot en la finalización de compra. Por defecto: desactivado.
Name: el nombre del método de envío que ven los clientes. Por defecto: Balikobot. Obligatorio, máximo 64 caracteres.
Sort Order: la posición del método en la lista de métodos de envío. Un número entero.
Cuenta de API de Balikobot (necesaria para tarifas en tiempo real y puntos de recogida)
API user: tu usuario de la API de Balikobot, desde la zona de cliente.
API key: tu clave de la API de Balikobot, desde la zona de cliente. Tras 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 si quieres 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.
Price (todos los precios están en la moneda predeterminada de tu tienda)
Price source: cómo se calcula el precio.
Country prices: una lista de países y precios. Haz clic en Add row para añadir una fila y en el botón de eliminar para borrar una. Elige * All other countries para todos los países sin fila propia. Decimales con punto o coma. Se usa en el modo fijo y como respaldo de la API. Un país sin precio (y sin fila *) no tiene tarifa fija, así que el método queda oculto para él.
Fixed price per: Order (por defecto) cobra el precio una sola vez. Item (price x quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo a los precios fijos. Una tarifa en tiempo real de Balikobot siempre es para el paquete completo.
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. Se usa solo 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 método cuando el carrito pesa menos. 0 significa sin límite (por defecto). Los pesos de los productos se convierten desde su clase de peso de OpenCart.
Max weight (kg): oculta el método cuando el carrito pesa más. Por defecto: 100. 0 significa sin límite. Un campo vacío equivale a 100 kg. Si Min weight (kg) es mayor que el máximo, verás un aviso y se mantienen los pesos anteriores.
Minimum order amount: muestra el método solo a partir de este subtotal del carrito (después de cupones, 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 cupones, sin impuestos) a partir del cual el envío es gratuito. En ese caso no se hace ninguna solicitud a la API. Solo se usa cuando Free shipping está activado.
Tax Class: el impuesto de esta clase se añade al precio del envío. Los precios de Balikobot suelen ser sin IVA. Por defecto: --- None ---.
Disponibilidad
Normalmente el método se ofrece en la zona geográfica seleccionada aquí (All Zones significa en todas partes). Ignore geo zone lo ofrece, en cambio, en los países de la lista.
Geo Zone: ofrece el método solo para direcciones de esta zona geográfica. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore geo zone: ofrece el método en los países indicados abajo, sea cual sea la zona geográfica.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países. Se usa solo con Ignore geo zone.
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 solicitudes a la API y los cálculos de tarifas en storage/logs/vfd_blkb_debug.log.php. El archivo no se puede leer 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. Cuando el archivo llega a 5 MB, se mueve a vfd_blkb_debug.old.log.php y se inicia un registro nuevo.
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 la extensión se borran los ajustes, el registro y los puntos de recogida de las finalizaciones de compra sin pedido. Si está desactivado (por defecto), los ajustes se conservan. Los puntos de recogida guardados en los pedidos siempre se conservan.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La clave de la API no se exporta.
Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban como en un guardado normal. La clave de la API 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 Balikobot. Si hay una Geo Zone definida (y Ignore geo zone está desactivado) y la dirección está fuera de ella, Balikobot no se ofrece. Con Ignore geo zone decide la lista de Countries. Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso y no entran en el importe del pedido. La extensión comprueba entonces el peso del carrito y el Minimum order amount. El importe del pedido es el precio de los productos que requieren envío, después del descuento del cupón y antes de impuestos. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Balikobot.
En el modo fijo, el precio se toma de Country prices. En los modos en tiempo real, la extensión 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 se solicita solo 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 la moneda predeterminada de la tienda, se redondea a sus decimales y se muestra al cliente en su moneda, con el impuesto de la Tax Class seleccionada.
Las tarifas en tiempo real se guardan en caché durante 1 hora, de modo que el mismo carrito no provoca una nueva solicitud. Una solicitud 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 método queda oculto, o se usa el precio fijo en el modo de respaldo. Los detalles van al registro de depuración.
La extensión 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 cambia los estados de los pedidos. Se usa un transportista y un tipo de servicio para todos los destinos. Los puntos de recogida se muestran como lista desplegable, sin mapa.
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 Balikobot en la ventana Shipping method options. El método funciona igual que en OpenCart 3; la lista de puntos de recogida se describe en Puntos de recogida.
Puntos de recogida
Con Pickup point selection activado, aparece una lista de puntos de recogida bajo el método de Balikobot en el paso Delivery Method de la finalización de compra de OpenCart. 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. Mientras se carga la lista, ve Loading pickup points.... La lista se guarda en caché hasta 12 horas.
La elección se guarda en cuanto el cliente selecciona un punto. Es obligatoria: Continue en el paso de envío se rechaza con Please select a pickup point. El servidor también comprueba que el punto elegido pertenece a la dirección de entrega. En caso contrario, el cliente ve The selected pickup point is not available for your shipping address. Please choose a pickup point again. Si en ese momento no se puede contactar con Balikobot, se acepta un punto ya elegido. 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.
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. La ventana Shipping method options muestra la lista de puntos de recogida bajo el método de Balikobot, con los mismos textos y comprobaciones. La lista se carga cada vez que se abre la ventana, porque la dirección puede cambiar en la misma página de finalización de compra, y procede de la caché cuando es posible. Si el cliente hace clic en Continue en la ventana sin un punto válido, el mensaje aparece en la parte superior de la página de finalización de compra y la ventana sigue abierta. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza en cada confirmación; el punto de recogida del pedido se actualiza con él.
El punto elegido se añade al método de envío del pedido como - Pickup point: seguido de su nombre y dirección. El cliente lo ve en las páginas de pedidos de su cuenta y en los correos de pedido, y se imprime en la factura.
En la página de pedido del administrador (Sales > Orders, View), el panel Balikobot pickup point muestra el punto, su ID de Balikobot y el transportista, que necesitas al crear el envío en Balikobot. Haz clic en Change, elige otro punto cerca de la dirección del pedido y haz clic en Save. El texto del método de envío del pedido también se actualiza, y verás Pickup point updated. Cambiar el punto solo requiere el permiso de modificación de pedidos, no el acceso a los ajustes de la extensión. Si un pedido no tiene punto, el panel muestra No pickup point was selected for this order. El panel también funciona con Balikobot desactivado: los pedidos existentes conservan los datos de su punto de recogida, y aún puedes cambiar el punto.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Balikobot es el primer bloque de Extensions > Extensions > Shipping > VibeFox Balikobot > Edit, por encima de los ajustes. Introduce 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-balikobot 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 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, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un 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, Balikobot 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 panel 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 queda oculto para todos. Una vez que hayas abierto 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 requieren 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 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
Balikobot no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable/Disable está activado. Lee los avisos de la parte superior de la página de la extensión. Revisa Geo Zone (o Ignore geo zone y Countries), los límites de peso y el Minimum order amount. En el modo fijo, comprueba que el país o * All other countries tiene un precio. Comprueba que los productos tienen Requires Shipping en Yes.
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 de la extensión. Muestra el motivo: faltan las credenciales de la API, todavía no hay código postal, el error de Balikobot para el transportista y el servicio (por ejemplo, "authorization failed: check the API user and API key"), 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 solucionas 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, define Exchange rate.
¿Incluye IVA? Los precios de Balikobot suelen ser sin IVA. Si seleccionas una Tax Class, OpenCart 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 definidos, que el transportista admite "branchlocator" y que la dirección de entrega tiene ciudad y código postal. Revisa el registro por si hay un error de Balikobot.
Las tarifas o los puntos de recogida parecen desactualizados tras un cambio: haz clic en Save en la página de la extensión. Esto borra las tarifas y los puntos de recogida guardados en caché.
La página dice "Warning: You do not have permission to modify VibeFox Balikobot!": tu grupo de usuarios de administración solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_balikobot (OpenCart 3) o extension/vfd_balikobot/shipping/vfd_balikobot (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de Balikobot se puede cambiar con el ajuste vfd_blkb_api_url (para pruebas); no tiene campo en la página de ajustes.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Balikobot. 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. Las tarifas y los puntos de recogida guardados en caché se eliminan siempre, y el panel de puntos de recogida y la lista de la finalización de compra dejan de funcionar. Si Remove data on uninstall está activado, también se borran los ajustes, el registro y los puntos de recogida de las finalizaciones de compra sin pedido. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensión. Los datos de puntos de recogida guardados en los pedidos nunca se borran, y el texto del método de envío de los pedidos existentes conserva el punto de recogida.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Balikobot en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
Balikobot es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Balikobot ni cuenta con su respaldo.