VibeFox The Courier Guy 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.

Clave de API de ShipLogic (para tarifas en tiempo real y lockers): The Courier Guy funciona con la plataforma ShipLogic. Crea una clave de API en tu portal de mensajería de The Courier Guy, en Settings > API Keys (cuenta comercial). Sin la clave solo se usa la tabla de precios y no se ofrece la opción de locker.

Envío a Sudáfrica: las tarifas en tiempo real y los lockers son solo para direcciones sudafricanas. Sudáfrica debe ser un país habilitado en la tienda (System > Localisation > Countries), y la tarifa de mensajería en tiempo real necesita las provincias sudafricanas (zonas), que OpenCart 3 ya incluye.

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_the_courier_guy-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_the_courier_guy.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_the_courier_guy-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, 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 The Courier Guy 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 el campo 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. Activa Courier to the door y/o TCG locker e introduce la API key de ShipLogic. Para las tarifas en tiempo real, rellena la dirección del remitente (calle, ciudad, provincia, código postal) y, si la moneda de tu tienda no es ZAR, la ZAR conversion rate.

6. Rellena la tabla de precios y/o un coste de reserva 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_the_courier_guy.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 The Courier Guy, 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 6 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones.

Tras la instalación, ambas opciones están desactivadas hasta que activas una y guardas. La extensión está habilitada mientras al menos una de las dos opciones esté activa. 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 The Courier Guy > Edit. Las secciones aparecen a la izquierda. Un botón Save en la parte inferior guarda toda la página sin recargarla. Cada guardado borra las tarifas y los lockers en caché y el último error de ShipLogic. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.

Si el nombre de una opción, la clase de impuesto, el orden de clasificación o la zona geográfica no son válidos, no se guarda nada y la página muestra el motivo, por ejemplo Enter a valid option name (1-64 characters, without < > ; = # { }). Un número no válido (por ejemplo, negativo) no se guarda: la página indica el campo y mantiene el valor anterior, y el resto se guarda. Mientras al menos una opción esté activa, las advertencias de la parte superior de la página indican si Sudáfrica no es un país habilitado, si falta la clave de API, la tasa de conversión a ZAR o la dirección del remitente, si no hay tabla de precios ni coste de reserva, si Sudáfrica no tiene zonas (provincias) o si la última solicitud a ShipLogic falló (con su fecha y error). También aparece una advertencia si la tienda no tiene una clase de peso con la unidad kg ni una clase de longitud con la unidad cm.

General

Cada tipo de entrega es una opción independiente en la finalización de compra.

Courier to the door: ofrece la entrega por mensajero de The Courier Guy a la dirección del cliente. Por defecto: desactivado.

Courier option name: el nombre de la opción de mensajería en la finalización de compra. Por defecto: The Courier Guy. Obligatorio, máximo 64 caracteres, sin < > ; = # { }.

TCG locker: el cliente elige un locker en la finalización de compra. Solo se ofrece para direcciones sudafricanas y solo con la clave de API de ShipLogic. Por defecto: desactivado.

Locker option name: el nombre de la opción de locker en la finalización de compra. Por defecto: The Courier Guy locker. Mismas reglas que el nombre de la mensajería.

Tax status: la clase de impuesto de ambas opciones. Con una clase de impuesto, las tarifas en tiempo real se toman sin IVA y OpenCart añade el impuesto de la clase. None (live rates including VAT) (por defecto): las tarifas en tiempo real se toman con IVA incluido.

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

API de ShipLogic

API key: tu clave de API de ShipLogic del portal de The Courier Guy. Nunca se muestra a los clientes 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 si quieres cambiarla. Marca Remove the saved API key y guarda para eliminarla.

Account ID: opcional. El ID numérico de la cuenta de ShipLogic, solo si tu clave tiene acceso a varias cuentas. Un valor que no sea un número no se guarda.

Tarifas en tiempo real (para direcciones sudafricanas; si no hay tarifa en tiempo real disponible, se usa la tabla de precios)

La tarifa en tiempo real es el servicio de ShipLogic más barato desde tu dirección de remitente hasta la dirección del cliente (mensajería) o hasta el locker más cercano a la ciudad del cliente (locker). Necesita la clave de API, la dirección del remitente y, en las tiendas que no usan rand, una tasa de conversión.

Price source: de dónde procede el precio.

ZAR conversion rate: ShipLogic cotiza en rands sudafricanos (ZAR). Si la moneda predeterminada de tu tienda no es ZAR, introduce cuánto vale 1 ZAR en tu moneda, por ejemplo 0.05. Debe ser mayor que 0. Sin ella, no se usan las tarifas en tiempo real y se aplica la tabla de precios. Si la moneda de tu tienda es ZAR, déjalo vacío. La tasa no se actualiza automáticamente.

Dirección del remitente (donde The Courier Guy recoge los paquetes, en Sudáfrica)

La dirección de la tienda en OpenCart es texto libre, por eso la dirección del remitente se introduce aquí. La calle, la ciudad, la provincia y el código postal son necesarios para las tarifas en tiempo real.

Sender company: el nombre de tu empresa.

Sender street address: por ejemplo 12 My Road.

Sender suburb: el barrio de la dirección del remitente.

Sender city: la ciudad de la dirección del remitente.

Sender province: elige una de las 9 provincias sudafricanas de la lista.

Sender postal code: el código postal de la dirección del remitente.

Tabla de precios (tus propios precios en la moneda predeterminada de la tienda, sin impuestos: se usa con Price table only, fuera de Sudáfrica y siempre que no haya tarifa en tiempo real; se acepta coma o punto decimal)

Calculation type: se aplica solo a la tabla de precios. Una tarifa en tiempo real siempre es para todo el pedido.

Prices by weight: una tabla de países con una columna Price y los tramos de peso XS (hasta 1 kg), S (hasta 2 kg), M (hasta 3 kg), L (hasta 5 kg) y XL (más de 5 kg). Haz clic en Add row para añadir una fila (una nueva fila empieza con Sudáfrica) y en el botón de eliminar para borrar una. Un tramo vacío o 0 usa la columna Price. Un precio de 0 significa envío gratis. La fila * Any country se aplica a los países sin fila propia y a una fila de país sin ningún precio. Un precio que no es un número se borra y la página lo indica.

Fallback cost: se usa cuando no hay ni tarifa en tiempo real ni precio en la tabla. Déjalo vacío para ocultar las opciones en ese caso.

Condiciones (ambas opciones)

Min weight (kg): oculta las opciones por debajo de este peso del carrito. 0 significa sin límite (por defecto).

Max weight (kg): oculta las opciones por encima de este peso del carrito. Por defecto: 30. 0 significa sin límite, vacío significa 30 kg. Si Min weight (kg) es mayor que Max weight (kg), la página muestra una advertencia y ambos límites mantienen sus valores anteriores.

Minimum order amount: muestra las opciones solo a partir de este subtotal del carrito (productos que requieren envío, sin impuestos, tras descuentos). Déjalo vacío para mostrarlas siempre.

Free shipping from: el subtotal del carrito a partir del cual la entrega es gratuita. Déjalo vacío para no ofrecer nunca envío gratis. Cuando el subtotal lo alcanza, las opciones se muestran con un precio de 0 y no se envía ninguna solicitud a ShipLogic para la tarifa.

Disponibilidad

Geo zone: ofrece las opciones solo para direcciones de esta zona geográfica. All zones (por defecto) significa cualquier dirección. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.

Ignore shipping zones: para el tipo de entrega siguiente no se comprueba la zona geográfica. En su lugar, la opción se ofrece en los países indicados abajo.

Delivery type without zones: Courier to the door (por defecto) o TCG locker (customer chooses a locker). Se usa solo con Ignore shipping zones. El otro tipo sigue sujeto a Geo zone.

Countries: los países de destino para ese modo. Se usa solo con Ignore shipping zones. Déjalo vacío para permitir todos los países. Los lockers se ofrecen solo en Sudáfrica.

Avanzado

Debug log: escribe mensajes de depuración en storage/logs/vfd_tcgr_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. La clave de API y los datos del cliente nunca se registran. Cuando el archivo llega a 5 MB, se inicia un nuevo registro.

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 las elecciones de locker de las finalizaciones de compra sin pedido. Las tarifas y los lockers en caché siempre se eliminan. Los lockers y las referencias de seguimiento 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 API no se exporta.

Import: pega el JSON exportado previamente 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 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 cada opción. La opción debe cumplir la Geo zone (o, con Ignore shipping zones, la lista de países). Solo cuentan los productos con Requires Shipping en Yes: los demás no suman peso ni se incluyen en el importe del pedido. Después, la extensión comprueba las condiciones: peso del carrito e importe mínimo del pedido. El importe del pedido es el precio de los productos que requieren envío, antes de impuestos y tras el descuento del cupón. Si se aplica envío gratuito, el precio es 0.

Courier to the door: la extensión pide a ShipLogic el servicio más barato desde tu dirección de remitente hasta la del cliente. La dirección debe tener calle, ciudad, provincia y código postal. Hasta entonces se usa la tabla de precios.

TCG locker: la tarifa en tiempo real es el servicio puerta a locker más barato hasta el locker más cercano a la ciudad del cliente. No se recalcula para el locker que elige el cliente. La opción de locker aparece solo para direcciones sudafricanas y solo con la clave de API.

El pedido completo se cotiza como un único paquete: el peso total, la mayor longitud y anchura, y las alturas apiladas. Los productos sin dimensiones cuentan como cubos de 10 cm. Los pesos y las dimensiones se convierten a partir de las clases de peso y longitud de los productos. El importe en rands se convierte a tu moneda predeterminada, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la clase de impuesto seleccionada.

Las solicitudes a ShipLogic caducan a los 12 segundos. Las tarifas se guardan en caché durante 1 hora, los lockers durante 6 horas y los fallos durante 10 minutos, para que una API lenta no ralentice cada actualización de la finalización de compra. Si no hay tarifa en tiempo real, el precio procede de la tabla y, después, de Fallback cost. Si ninguno se aplica, la opción se oculta. Los errores de la API nunca se muestran al cliente.

La extensión no registra envíos, no crea guías ni etiquetas, y no actualiza el seguimiento automáticamente. No hay mapa de lockers: se eligen de una lista. Las tarifas en tiempo real y los lockers son solo para Sudáfrica. Otros países usan la tabla de precios. Solo se muestra una tarifa por opción (el nivel de servicio más barato), sin elección de niveles de servicio, seguros ni extras en la finalización de compra.

Con OpenCart 4, el cliente hace clic en Choose en el bloque del método de envío de la finalización de compra y elige la opción de mensajería o de locker en la ventana Shipping method options. El método funciona igual que en OpenCart 3.

Puntos de recogida

Cuando el cliente elige la opción de locker en el paso del método de envío, debajo aparece un selector de lockers: un campo de búsqueda (por defecto, la ciudad de la dirección de entrega) y una lista de lockers con nombre, dirección y horario. El cliente puede escribir otra ciudad, barrio o código postal y hacer clic en Search. Debe elegir un locker antes de continuar; si no, el paso muestra Please choose a The Courier Guy locker.

El locker se verifica en el servidor con la lista de ShipLogic cuando el cliente continúa y de nuevo al realizar el pedido. Su nombre y su proveedor se toman de ShipLogic, nunca del navegador. La elección depende del país y de la ciudad o código postal de la dirección: si cambia la dirección de entrega, el cliente debe elegir de nuevo.

Si no se puede contactar con ShipLogic, el selector muestra Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. El pedido puede realizarse entonces sin locker. Se marca en la página de pedido del administrador: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

Con OpenCart 4, el selector de lockers aparece en la ventana Shipping method options, debajo de la opción de locker, y 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 avanza sin un locker de la lista, con el mismo mensaje, y un ShipLogic no disponible tampoco bloquea el pedido. OpenCart 4 mantiene un 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.

Pedidos

El locker elegido se añade al método de envío del pedido, por ejemplo "The Courier Guy locker: nombre — dirección". Este texto aparece en Sales > Orders, en la página de pedido del cliente, en la factura y en los correos de pedido.

La página del pedido en Sales > Orders tiene un panel The Courier Guy encima del historial para cada pedido enviado con The Courier Guy. En un pedido con locker muestra el nombre, el ID y el proveedor del locker, con not verified (ShipLogic was unavailable at checkout) si no se pudo comprobar el locker, o el mensaje Not chosen si ShipLogic no estuvo disponible. El panel se muestra aunque la extensión esté desactivada.

The Courier Guy tracking reference: registra el paquete en tu portal de The Courier Guy, introduce su referencia en este campo del panel y haz clic en Save. Borra el campo y guarda para eliminarla. Los usuarios administradores sin permiso para modificar pedidos ven la referencia en solo lectura. El cliente ve la referencia en la página de pedido de su cuenta (clientes registrados) y en los correos de estado del pedido cuando le notificas. El correo de nuevo pedido no tiene referencia, porque se introduce más tarde.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox The Courier Guy es el primer bloque de Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit, 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 quitar la clave de esta tienda. Debajo están la línea Product: opencart-shipping-the-courier-guy 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 panel de administración (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 y una fecha. Después de cambiar la dirección de la tienda, o después de liberar un hueco 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. Quitar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.

Sin una clave activa, no se muestra a los clientes en la finalización de compra ninguna de las dos opciones de The Courier Guy (courier a domicilio o TCG locker), y no se calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el panel en el mismo navegador sigue viendo las opciones en la tienda, marcadas con (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 panel, así que sin una clave activa las opciones se ocultan para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel. 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 panel 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 ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

The Courier Guy does not appear at checkout: comprueba que la licencia esté activa y que la opción esté activada (Courier to the door o TCG locker). Revisa Geo zone (o Ignore shipping zones y Countries), los límites de peso y Minimum order amount. Comprueba que la tabla o Fallback cost tengan un precio. Comprueba que los productos tengan Requires Shipping en Yes. La opción de locker aparece solo para direcciones sudafricanas y con la clave de API.

Customers see no locker list: los lockers necesitan la clave de API, TCG locker activado y una dirección de entrega sudafricana. La página de ajustes muestra el último error de ShipLogic, si lo hay, por ejemplo una clave rechazada.

The price is always the table price: revisa las advertencias de la página de ajustes. Una tarifa en tiempo real necesita la clave de API, la dirección completa del remitente y, en tiendas que no usan rand, la tasa de conversión a ZAR. Para la entrega a domicilio, la dirección del cliente necesita calle, ciudad, provincia (zona) y código postal. Para los lockers, ShipLogic debe encontrar un locker cerca de la ciudad del cliente. Activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión.

ShipLogic is down: se muestra el precio de la tabla o el de reserva. Los pedidos con locker pueden realizarse sin locker y se marcan en el pedido.

Rates look outdated after a change: haz clic en Save en la página de la extensión. Esto borra las tarifas y los lockers en caché.

The page says "Warning: You do not have permission to modify VibeFox The Courier Guy!": tu grupo de usuarios administradores solo puede ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_the_courier_guy (OpenCart 3) o extension/vfd_the_courier_guy/shipping/vfd_the_courier_guy (OpenCart 4) en System > Users > User Groups.

For developers: la dirección de la API de ShipLogic puede sustituirse con el ajuste vfd_tcgr_api_url (para pruebas); no tiene campo en la página de ajustes.

Desinstalar

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox The Courier Guy. La clave de licencia y el estado de la licencia de esta extensión se eliminan siempre. OpenCart siempre restablece el estado de la extensión, Sort order, Tax status y Geo zone. Las tarifas y los lockers en caché y el último error de ShipLogic siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes, el registro y las elecciones de locker de las finalizaciones de compra sin pedido. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Los lockers y las referencias de seguimiento guardados en los pedidos nunca se eliminan, y los pedidos existentes conservan su método de envío y su coste.

Para eliminar también los archivos de la extensión en OpenCart 4, ve a Extensions > Installer después de la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox The Courier Guy en la lista de extensiones instaladas y, después, en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

The Courier Guy y ShipLogic son marcas comerciales de sus respectivos propietarios. Esta extensión no está afiliada ni respaldada por The Courier Guy ni por ShipLogic.