VibeFox Sameday Easybox for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con 3.0.5.0) o 4.0.2 y posteriores (probado con 4.1.0.3).

PHP: 8.0 o posterior.

Nombre de usuario y contraseña de la API de Sameday: el acceso a la API forma parte de una cuenta de empresa de Sameday en Rumanía, Hungría o Bulgaria. Consulta a tu gestor de cuenta de Sameday o al equipo de integración de Sameday. Las credenciales suelen ser las mismas que las del portal eAWB (eawb.sameday.ro, .hu o .bg). Para la API de demostración, Sameday proporciona credenciales de prueba independientes. Sin nombre de usuario y contraseña de la API el método no se ofrece, porque el cliente no podría elegir un locker.

País y condados: el país de tu cuenta de Sameday debe estar activado en System > Localisation > Countries. La estimación de Sameday necesita el condado de la dirección de entrega (el campo Region / State). OpenCart tiene los condados de Rumanía y Bulgaria, pero OpenCart 3 no tiene ninguno de Hungría (OpenCart 4.1 sí los tiene). La extensión puede añadirlos por ti (véase más abajo, en Lockers easybox). Sin ellos, los precios proceden de tu tabla o del coste alternativo.

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 de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_sameday_easybox-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_sameday_easybox.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_sameday_easybox-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions, elige el tipo de extensión Shipping, busca VibeFox Sameday Easybox 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. Pega 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 (ver Clave de licencia).

5. Introduce tu API username y tu API password de Sameday, elige el Sameday country, activa Enable/Disable y haz clic en Save. La página debería mostrar "Connected to Sameday ... easybox lockers". Pickup point y Easybox service se rellenan con los datos de tu cuenta.

6. Define tus precios: Exchange rate of the estimate si la moneda de tu tienda es distinta de la de Sameday, y una fila de Country prices (por ejemplo, * Default) o un Fallback cost.

7. Si la página indica que OpenCart no tiene condados para tu país de Sameday, haz clic en Add counties en la sección easybox lockers.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_sameday_easybox.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 Sameday Easybox, 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 a 7 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de cron es distinta (ver Lockers easybox).

Tras la instalación, el método queda desactivado hasta que actives Enable/Disable y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes que conservaste, pero el método empieza desactivado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit. Las secciones aparecen a la izquierda. Un botón Save en la parte inferior guarda toda la página sin recargarla. Solo los administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

Encima de los ajustes, la página muestra el estado de la conexión: el host de Sameday, el número de lockers easybox y la fecha de la última actualización de la lista, o que Sameday rechazó el nombre de usuario o la contraseña. También muestra los problemas de configuración, por ejemplo la falta de credenciales, de precio, de tipo de cambio para la estimación, de condados o de una clase de peso en kilogramos, o países seleccionados fuera de tu país de Sameday.

Algunos errores impiden el guardado y no se guarda nada: Enter a valid name (1-64 characters, without < > ; = # { })., Sort order must be a whole number., una clase de impuesto o una zona geográfica no válidas. Otros problemas solo afectan a un valor: todos los precios y límites aceptan una coma o un punto como separador decimal (4,99 o 4.99), y un número no válido o negativo no se guarda. Una advertencia indica el campo y se conserva el valor anterior.

General

Enable/Disable: muestra u oculta el método en la finalización de compra. Es el estado de la extensión en Extensions > Extensions > Shipping. Por defecto: desactivado.

Name: nombre del método de envío que ve el cliente. Por defecto: Sameday easybox. Hasta 64 caracteres.

Tax class: --- None --- (por defecto) significa que el precio es final. Con una clase de impuesto, OpenCart añade el impuesto de esa clase al precio.

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

Cuenta de Sameday (API)

Al guardar, la extensión inicia sesión en Sameday y carga tus servicios, tus puntos de recogida y la lista de lockers easybox. La lista se actualiza a diario.

API username: tu nombre de usuario de la API de Sameday.

API password: tu contraseña de la API de Sameday. Nunca se vuelve a mostrar: deja el campo vacío para conservar la guardada. Vaciar el nombre de usuario elimina también la contraseña. Si Sameday la rechaza, no se vuelve a probar durante 10 minutos.

Sameday country: el país de tu cuenta de Sameday: Romania (api.sameday.ro) (por defecto), Hungary (api.sameday.hu) o Bulgaria (api.sameday.bg). Se ofrecen sus lockers y el método se muestra solo para este país de destino.

Test mode: usa la API de demostración de Sameday (sameday-api.demo.zitec.com) con credenciales de demostración.

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

El orden de uso es: la estimación de Sameday (cuando Pickup point y Easybox service están definidos), después la tabla de precios por país y, por último, el coste alternativo. Los precios de la tabla se introducen en la moneda predeterminada de la tienda. Los clientes que paguen en otra moneda ven el precio convertido.

Pickup point: tu punto de recogida de Sameday, donde Sameday recoge los paquetes. Tras iniciar sesión correctamente se convierte en una lista con los puntos de recogida de tu cuenta, y se elige automáticamente el predeterminado. Antes de eso es un campo para el ID. Es necesario para la estimación de Sameday. Elige - not set (price table only) - para usar solo la tabla de precios.

Easybox service: el servicio de Sameday para la entrega en easybox, normalmente "Locker NextDay" (código LN), que se elige automáticamente. Es necesario para la estimación de Sameday.

Exchange rate of the estimate: Sameday calcula la estimación en la moneda de tu país de Sameday: RON, HUF o BGN (EUR para las tiendas búlgaras que venden en euros). Si tu tienda vende en otra moneda, introduce el valor de 1 unidad de la moneda de Sameday en la moneda de tu tienda, por ejemplo 0.20. El tipo debe ser superior a 0. Sin él no se usa la estimación y se aplica la tabla de precios. El leva y el euro se convierten automáticamente al tipo fijo.

Table price: Per order cobra el precio una sola vez. Per item (price x quantity) lo multiplica por el número de artículos. Se aplica a la tabla de precios y al coste alternativo. La estimación de Sameday siempre es para el paquete completo.

Country prices: un precio por país de destino y peso del paquete. Haz clic en Add country para añadir una fila y en el botón de eliminar para borrar una. Cada fila tiene una columna de Price y columnas de peso: XS hasta 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg y XL más de 5 kg. Una columna de peso que queda en 0 o vacía usa la columna Price. La fila * Default se usa para los países que no tienen fila propia. Una fila nueva empieza como * Default con todos los precios en 0, lo que significa envío gratuito. Elige el país e introduce los precios antes de guardar, o elimina la fila. Si el mismo país aparece en dos filas, al guardar solo se conserva la primera y una advertencia lo indica. Si una celda no es un número igual o mayor que 0, la tabla no se guarda.

Fallback cost: se usa cuando no hay estimación de Sameday y la tabla del país no tiene fila para el destino. Déjalo vacío para no ofrecer el método en ese caso.

Free shipping from: subtotal del carrito (productos que requieren envío, después de descuentos y sin impuestos) a partir del cual la entrega en easybox es gratuita. Cuando el subtotal lo alcanza, el método se ofrece sin coste y no se consulta ningún precio. Déjalo vacío para no ofrecer nunca envío gratuito.

Disponibilidad

Minimum weight (kg): oculta el método cuando el carrito pesa menos. El peso se convierte desde la clase de peso de los productos. Vacío o 0 significa sin límite.

Maximum weight (kg): los paquetes más pesados que este no se ofrecen para la entrega en easybox. Por defecto: 30. Revisa el límite de tu contrato de Sameday y los tamaños de caja de easybox. Vacío o 0 significa sin límite. Un peso mínimo superior al máximo no se guarda: una advertencia lo indica y se mantienen los valores anteriores.

Minimum cart subtotal: ofrece el método solo cuando el subtotal del carrito (productos que requieren envío, después de descuentos y sin impuestos) alcanza este importe. Vacío significa sin mínimo.

Geo zone: ofrece el método solo para direcciones de esta zona geográfica. All Zones (por defecto) significa sin límite. Las zonas geográficas se gestionan en System > Localisation > Geo Zones. No se comprueba cuando Ignore shipping zones está activado.

Ignore shipping zones: si está activado, no se comprueba la zona geográfica y el método se ofrece para los países seleccionados abajo (el país de Sameday si la lista está vacía). Si está desactivado, solo se aplica la zona geográfica de arriba.

Countries (ignore zones mode): los países de destino para ese modo. Los países distintos del país de Sameday se omiten, y la página avisa de ellos. Este campo solo se usa cuando Ignore shipping zones está activado.

Lockers easybox

Locker list: muestra cuántos lockers easybox en cuántas ciudades están cargados y cuándo. Refresh the locker list now vuelve a cargarla. La lista se actualiza al guardar los ajustes y, cuando tiene más de un día, después de una petición de finalización de compra (como máximo una vez por hora). Para una actualización diaria fija, llama una vez al día a la URL que aparece aquí desde una tarea cron de tu servidor. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/shipping/vfd_sameday_easybox/cron&token=(token), y en OpenCart 4: https://your-store/index.php?route=extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox.cron&token=(token). Copia la URL exactamente como la muestran los ajustes. La URL contiene un token secreto. Sin el token correcto responde con un error y no contacta con Sameday. Tampoco hace nada mientras el método está desactivado.

Counties: muestra cuántos condados tiene OpenCart para tu país de Sameday. Si no tiene ninguno, haz clic en Add counties. La extensión añade los condados de ese país a System > Localisation > Zones, y el campo Region / State del formulario de dirección los mostrará. Los condados que ya existen no se añaden de nuevo. OpenCart 4.1 ya tiene los condados de los tres países, así que ahí no hace falta el botón.

Avanzado

Debug log: escribe los cálculos de tarifas, las llamadas a la API y las elecciones de locker en storage/logs/vfd_sdeb_debug.log.php, archivo que no puede leerse desde la web. Los errores de la API siempre se registran. No se registran contraseñas, tokens ni datos personales de clientes. Cuando el archivo llega a 5 MB, se inicia un nuevo registro. Desactiva el registro cuando termines.

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 la extensión se eliminan los ajustes, los datos de Sameday en caché y el registro. Si está desactivado (por defecto), los ajustes se conservan. La lista de lockers y las cachés siempre se eliminan. El locker guardado en los pedidos siempre se conserva.

Importación / Exportación

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. La contraseña de la API no se exporta.

Import: pega el JSON exportado previamente y haz clic en Import. Los valores pasan las mismas comprobaciones que el formulario. Se conserva la contraseña guardada.

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 la entrega en easybox de Sameday. La extensión comprueba la zona geográfica (o los países de Ignore shipping zones), el país de destino de tu cuenta de Sameday, las credenciales de la API y una lista de lockers utilizable, el peso del carrito y el subtotal mínimo. Solo cuentan los productos con Requires Shipping en Yes. El subtotal es el precio de estos productos sin impuestos, después del descuento del cupón. Si se aplica envío gratuito, el cliente ve el método sin coste.

En caso contrario, la extensión pide a Sameday una estimación, una vez que el cliente ha introducido una ciudad y un condado. Envía tu punto de recogida y servicio, el peso del paquete y la dirección del cliente (calle, ciudad, condado y código postal). No se envían nombre, correo electrónico ni teléfono. Bucarest se envía como "Sector 1", igual que el plugin oficial de Sameday. La estimación se convierte a la moneda de tu tienda. Si no hay estimación (no configurada, sin ciudad o condado todavía, error, sin tipo de cambio), el precio procede de la tabla del país y, después, del coste alternativo. Si no hay precio, el método se oculta. El precio se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada.

Los problemas de Sameday nunca interrumpen la finalización de compra. La estimación se guarda en caché durante 1 hora. Un error se guarda en caché durante 10 minutos. Tras un timeout o un error del servidor, no se pide ninguna estimación durante 5 minutos. Las peticiones caducan a los 15 segundos. Durante la finalización de compra, la lista de lockers se lee de tu servidor, no de Sameday.

La extensión no crea AWB (envíos), no imprime etiquetas, no hace seguimiento de paquetes ni gestiona el pago contra reembolso. No ofrece entrega a domicilio por mensajería ni el widget de mapa de Sameday. Crea el AWB en el portal eAWB de Sameday o en tu herramienta habitual con el ID del locker que aparece en el pedido.

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 Sameday easybox en la ventana Shipping method options. Los precios son los mismos que en OpenCart 3.

Puntos de recogida

Cuando el cliente selecciona el método, aparece debajo de él un bloque easybox locker con dos listas: - Select city - y - Select easybox locker -. La ciudad de la dirección de entrega se preselecciona si tiene lockers. Cada locker muestra su nombre y su dirección. La elección se guarda al instante para la finalización de compra, así que se conserva si se vuelve a abrir el paso de entrega.

El locker es obligatorio. Sin uno, el cliente no puede continuar y ve "Please choose a Sameday easybox locker.". Cuando el cliente hace clic en Continue, el servidor comprueba que el locker elegido está en la lista. Un ID de locker falsificado o eliminado se rechaza con "The selected easybox locker is not available any more. Please choose another easybox locker.". Si la lista no se puede cargar, el cliente ve "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method.". El nombre y la dirección guardados con el pedido proceden de la lista, no del navegador.

Páginas de pedido, correos electrónicos y factura: el locker se añade al método de envío del pedido, por ejemplo "Sameday easybox: nombre - dirección" (primero el nombre del método y después el locker). El cliente lo ve en la confirmación del pedido, en el historial de pedidos y en los correos electrónicos del pedido, y tú lo ves en la factura.

Página de pedido del administrador: en Sales > Orders, la página del pedido tiene un panel Sameday easybox locker con el nombre, la dirección y el Locker ID para el AWB de Sameday. Si un pedido de easybox no tiene locker, el panel dice "No easybox locker was selected for this order.". El panel también se muestra mientras el método está desactivado.

En OpenCart 4 el bloque easybox locker aparece en la ventana Shipping method options, debajo de la opción de Sameday easybox, y la lista de ciudades se vuelve a cargar cada vez que se abre la ventana, porque la dirección puede cambiar en la finalización de compra de una sola página. El botón Continue de la ventana no continúa sin un locker válido, con los mismos mensajes. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar, y el locker del pedido se actualiza con él. El panel de la página del pedido del administrador se muestra encima de la sección History.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Sameday Easybox es el primer bloque de Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit, por encima de los ajustes. 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 eliminar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-sameday-easybox y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los 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 no se acepta la clave, 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. Tras 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. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, el método de envío Sameday easybox no se muestra a los clientes en la finalización de compra y no se pide ni calcula ningún precio. 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 a todos. Tras 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 tras introducir la clave, y después una vez por semana. No hace falta ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Sameday easybox no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el nombre de usuario y la contraseña de la API están introducidos y que la página de ajustes dice "Connected to Sameday", y que el país de destino es el país de tu cuenta de Sameday. Comprueba que hay un precio disponible (estimación de Sameday, fila del país, fila * Default o Fallback cost), los límites de peso y subtotal, Geo zone y los países de Ignore shipping zones. Comprueba que los productos tienen Requires Shipping en Yes. Activa Debug log para ver el motivo en el campo Log.

Sameday rechazó el nombre de usuario o la contraseña de la API: compruébalos y guarda de nuevo. Las credenciales de demostración solo funcionan con Test mode activado; las de producción, solo con él desactivado. Mientras tanto, se ofrece la lista de lockers guardada, si existe, y no se usa la estimación de Sameday.

El precio procede de mi tabla, no de Sameday: la estimación necesita un Pickup point, el Easybox service, condados para tu país de Sameday y, si la moneda de tu tienda difiere de la de Sameday, el Exchange rate of the estimate. Solo se pide después de que el cliente haya introducido una ciudad y un condado. Cuando Sameday no está disponible o devuelve un error, se usa la tabla o el coste alternativo; el motivo está en el registro.

La lista de lockers está obsoleta o falta: haz clic en Refresh the locker list now o guarda los ajustes. Si una actualización falla, se usa la lista anterior y el estado lo indica.

El envío es gratuito por error: comprueba Free shipping from y las filas de Country prices con un Price de 0, especialmente una fila * Default añadida con Add country y dejada sin rellenar.

Los límites de peso o las columnas de peso no coinciden: si la página avisa de que no hay ninguna clase de peso con la unidad "kg", añade una clase de peso en kilogramos en System > Localisation > Weight Classes.

La página dice "Warning: You do not have permission to modify VibeFox Sameday Easybox!": tu grupo de usuarios de administración solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_sameday_easybox (OpenCart 3) o extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox (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 Sameday Easybox. 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. La lista de lockers guardada, el resultado de la comprobación de la cuenta y todas las cachés siempre se eliminan. Si Remove data on uninstall está activado, también se borran el resto de ajustes, el token de cron y el registro. Si está desactivado, se conservan y se usan de nuevo al volver a instalar la extensión. Los pedidos existentes conservan el locker guardado.

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

Sameday y easybox son marcas comerciales de sus respectivos titulares. Esta extensión no está afiliada a Sameday ni cuenta con su respaldo.