VibeFox UPS 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, con la extensión cURL.

Aplicación en el UPS Developer Portal (solo para tarifas en tiempo real): inicia sesión en el UPS Developer Portal (developer.ups.com), crea una aplicación con el producto «Rating», vincula tu cuenta de UPS y copia el Client ID y el Client Secret. La extensión usa OAuth 2.0. No se necesitan Access Key, nombre de usuario ni contraseña. Para las tarifas negociadas también necesitas tu número de cuenta de UPS de 6 caracteres. Sin credenciales, solo se usan los precios fijos.

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_ups-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_ups.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_ups-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 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 UPS 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, en el bloque de licencia de la parte superior de la página Edit, y haz clic en Activate (véase License key).

5. Introduce el Client ID y el Client Secret, tu número de cuenta de UPS (para tarifas negociadas) y la dirección Ship from: el código postal y, para EE. UU. y Canadá, el código de estado de 2 letras.

6. Si la moneda de tu cuenta de UPS es distinta de la moneda predeterminada de tu tienda, introduce la UPS account currency y el Exchange rate.

7. Opcionalmente, introduce precios fijos como alternativa, activa Enable UPS shipping 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_ups.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, elige el tipo de extensión Shipping. Busca VibeFox UPS, 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.

Tras la instalación, el método queda desactivado hasta que actives Enable UPS shipping y guardes. El país de Ship from empieza como el país de tu tienda. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes de UPS que conservaste.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox UPS > 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 el token de UPS y las tarifas en caché. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes, vaciar la caché o borrar el registro.

Si el nombre, 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 name (64 characters max, without < > ; = # { }). Nothing was saved. Los números no válidos (por ejemplo, negativos), un tamaño de caja incorrecto, un Min weight (kg) superior a Max weight (kg) y las celdas de precio que no son números se indican al guardar: ese campo conserva su valor anterior y el resto se guarda. Las advertencias sobre los ajustes indican cuando solo está definido uno de Client ID y Client Secret, cuando no hay credenciales ni precios fijos (entonces el método nunca se muestra), cuando falta el código postal o el estado de origen, cuando se eligen tarifas de cuenta sin número de cuenta, cuando falta el tipo de cambio, o cuando la unidad de peso o de longitud de la tienda no es reconocida por la extensión.

General

Los ajustes se aplican a todas las zonas geográficas. UPS se ofrece como una sola opción de envío en la finalización de compra.

Enable UPS shipping: muestra u oculta UPS en la finalización de compra. Por defecto: desactivado.

Name: el nombre del método de envío que ve el cliente en la finalización de compra. Por defecto: UPS. Obligatorio, máximo 64 caracteres, sin < > ; = # { }.

Tax class: la clase de impuesto del coste de envío, o None (por defecto). Las tarifas de UPS se cotizan sin impuestos. Con una clase de impuesto, OpenCart añade su impuesto de envío encima.

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

UPS API (tarifas en tiempo real)

Test mode: usa el entorno de pruebas de UPS. Las tarifas de prueba no son precios reales. Desactívalo para tarifas en tiempo real. Por defecto: desactivado.

Client ID: el Client ID de tu aplicación en el UPS Developer Portal. Al borrarlo también se elimina el Client Secret guardado.

Client Secret: el Client Secret de la misma aplicación. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.

UPS account number: tu número de expedidor de UPS de 6 caracteres, por ejemplo A1B2C3. Necesario para las tarifas de cuenta (negociadas); opcional para las tarifas publicadas.

Rates: qué precios de UPS se usan.

Measurement units: las unidades que se envían a UPS. Los pesos y las medidas de la tienda se convierten.

Residential delivery: cotiza las direcciones de los clientes como residenciales, con el recargo residencial de UPS. Desactívalo si envías sobre todo a empresas. Por defecto: activado.

Box size (L x W x H): medidas opcionales de la caja en la unidad de longitud de tu tienda (que aparece en el nombre del campo), por ejemplo 30x20x15. UPS aplica entonces el peso dimensional. Déjalo vacío para cotizar solo por peso.

UPS account currency: UPS cotiza en la moneda del país de la cuenta del expedidor, por ejemplo USD para EE. UU., CAD para Canadá o EUR para la zona del euro. Por defecto: USD.

Exchange rate: solo es necesario cuando la moneda de la cuenta de UPS es distinta de la moneda predeterminada de tu tienda. Introduce el precio de 1 unidad de la moneda de la cuenta en tu moneda predeterminada, por ejemplo 0.92. Sin él, esas tarifas no se usan y se aplican los precios fijos. Los tipos de cambio no se actualizan automáticamente.

Cache: los tokens de UPS se guardan en caché hasta que caducan (como máximo, el tiempo de vida de la caché de OpenCart), las tarifas durante 1 hora y las solicitudes fallidas durante 5 a 10 minutos. Haz clic en Clear cached UPS token and rates para vaciar la caché de inmediato.

Ship from (la dirección donde UPS recoge o donde tú entregas los paquetes; se usa para las tarifas en tiempo real)

Country: el país desde el que envías. Por defecto es el país de tu tienda.

State / province code: el código de 2 letras, obligatorio para EE. UU. y Canadá, por ejemplo NY, CA u ON. Solo se envía a UPS para estos dos países.

City: la ciudad desde la que envías.

ZIP / postal code: el código postal desde el que envías. UPS lo necesita para cotizar las tarifas. OpenCart no tiene código postal de tienda, así que introdúcelo aquí.

Precios fijos (se usan cuando no se introducen credenciales de API y como alternativa cuando UPS no devuelve tarifa; deja ambos vacíos para ocultar el método en ese caso)

Country prices: precios en la moneda predeterminada de tu tienda, sin impuestos, por país de destino. Haz clic en Add country para añadir una fila y en el botón de eliminar para borrar una. * Default (all other countries) se aplica a cualquier otro país. Una columna de peso (XS hasta 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg, XL más de 5 kg) sustituye a Price para ese peso del carrito. Las celdas vacías usan Price. 0 significa envío gratuito. Una fila de país sin valor para el peso pasa a la fila *. Las filas sin ningún precio no se guardan.

Fallback cost: un precio fijo en la moneda predeterminada de tu tienda cuando no coincide ningún precio por país. Déjalo vacío para ocultar el método en ese caso.

Fixed price is: Per order (por defecto) cobra el precio una vez, según el peso de todo el carrito. Per item (each item priced by its own weight x quantity) tarifica cada producto según su propio peso (el peso predeterminado si no tiene) y lo multiplica por su cantidad. Las tarifas en tiempo real de UPS siempre se cotizan según el peso de todo el carrito.

Condiciones

Free shipping from: el subtotal del carrito (productos que requieren envío, después del cupón, antes de impuestos) a partir del cual este método es gratuito. No se envía ninguna solicitud a UPS en ese caso. Déjalo vacío para no ofrecer nunca envío gratuito.

Minimum subtotal: muestra el método solo cuando el subtotal del carrito es al menos este importe. Déjalo vacío para mostrarlo siempre.

Min weight (kg): el peso mínimo del carrito para que aparezca este método. 0 significa sin límite (por defecto).

Max weight (kg): el método se oculta por encima de este peso del carrito. Por defecto: 70, el límite de UPS por paquete (70 kg / 150 lbs). 0 significa sin límite, vacío significa 70.

Default product weight (kg): el peso que se usa para los productos sin peso, en las tarifas de UPS, las columnas de peso y los límites de peso. Por defecto: 0.5. Vacío también significa 0.5.

Geo zone: ofrece UPS solo para direcciones en 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 usa con Ignore shipping zones.

Disponibilidad sin zonas de envío

Ignore shipping zones: no comprueba la zona geográfica. El método se ofrece en los países indicados abajo.

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

Avanzado

Debug log: registra las solicitudes a la API y el cálculo de tarifas en storage/logs/vfd_upsx_debug.log.php (en OpenCart 4, system/storage/logs/vfd_upsx_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 credenciales, los tokens y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se mueve a vfd_upsx_debug.old.log.php y 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 de UPS, los tokens y tarifas en caché, y el registro. Los servicios de UPS guardados con los pedidos siempre se conservan. Si está desactivado, todo se conserva para una reinstalación.

Importar / Exportar

Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El Client Secret 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. El Client Secret guardado 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 UPS. Si hay una Geo zone definida y la dirección está fuera de ella, UPS no se ofrece (con Ignore shipping zones, decide en su lugar 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 subtotal. El subtotal es el precio de estos productos después del descuento del cupón y antes de impuestos. Las tarjetas de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. Después, la extensión comprueba las condiciones: peso del carrito y subtotal mínimo. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a UPS.

La extensión obtiene un token OAuth de UPS y lo conserva hasta que caduca. Un token rechazado por UPS se renueva automáticamente y la solicitud se repite una vez. Después pide a la UPS Rating API todos los servicios desde tu dirección de origen hasta la dirección del cliente, para el carrito como un solo paquete. En los países donde OpenCart exige código postal, la solicitud espera a que el cliente lo introduzca. Para envíos desde EE. UU. a Canadá o Puerto Rico se envía el valor de las mercancías, como exige UPS.

El cliente ve una sola opción con el servicio UPS más barato. El precio se calcula en la moneda predeterminada de tu tienda, se redondea a sus decimales y se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada. UPS Access Point Economy no se cotiza, porque la extensión no recoge una dirección de Access Point.

Cada tarifa se guarda en caché durante 1 hora. Una solicitud fallida se recuerda durante 10 minutos, y una solicitud de token fallida durante 5 minutos, para que una caída no ralentice cada actualización de la finalización de compra. El tiempo de espera HTTP es de 15 segundos.

Si UPS no devuelve tarifa (API caída, credenciales incorrectas, ningún servicio, otra moneda sin tipo de cambio), el precio procede de Country prices y, después, de Fallback cost. Si ninguno se aplica, el método se oculta. El cliente nunca ve los textos de error de UPS. El motivo se escribe en el registro de depuración.

La extensión solo calcula tarifas. No ofrece la selección de UPS Access Point, no crea etiquetas de envío ni envíos de UPS, no reserva recogidas ni hace seguimiento de paquetes. Muestra una sola opción, no varios servicios de UPS. No hay empaquetado en cajas: el carrito se cotiza como un solo paquete. Los tipos de cambio no son automáticos.

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 UPS en la ventana Shipping method options. El método funciona igual que en OpenCart 3.

Pedidos

Cuando se realiza un pedido con una tarifa en tiempo real de UPS, el servicio de UPS se guarda con el pedido. La página del pedido en Sales > Orders muestra un panel UPS con el UPS service, por ejemplo UPS Ground, y la Live rate (excl. tax). Estos valores se guardan cuando se realiza el pedido. Los pedidos con precio fijo o envío gratuito no tienen ese panel.

OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar. El servicio de UPS guardado se actualiza con él. Si el cliente cambia a otro método de envío, o el precio pasa a ser un precio fijo o envío gratuito, el servicio guardado se elimina del pedido. En OpenCart 4, el panel UPS 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 UPS es el primer bloque de Extensions > Extensions > Shipping > VibeFox UPS > 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-ups 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 el inglés y el 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 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 solo dominio. Gestionas tus licencias y dominios en tu cuenta de vibefox.net.

Sin una clave activa, UPS no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un 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. Después de abrir una vez la página Edit, 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 necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard o la página Edit del panel: 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 ningún cron job. Al desinstalar la extensión siempre se elimina la clave de licencia y el estado de la licencia.

Solución de problemas

UPS does not appear at checkout: comprueba que la licencia esté activa y que Enable UPS shipping esté activado. Revisa Geo zone, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y Minimum subtotal. Sin credenciales de UPS válidas, el método necesita un precio fijo (Country prices o Fallback cost). Comprueba que los productos tengan Requires Shipping en Yes.

Live rates do not appear: revisa las advertencias en la parte superior de la página Edit. Activa Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. Muestra errores de OAuth (revisa el Client ID, el Client Secret y el Test mode), mensajes de error de UPS y problemas de moneda.

The rate is in USD but the store is not: UPS devuelve las tarifas en la moneda de la cuenta del expedidor. Define UPS account currency y el Exchange rate. Sin tipo de cambio, esas tarifas se ignoran y se usa el precio fijo.

"This measurement system is not valid for the selected country": deja Measurement units en Automatic (by ship-from country), o elige las unidades que UPS espera para el país de origen.

The page warns about the weight or length unit: sin una clase de peso en kg, las unidades de peso desconocidas se leen como kg. Añade una clase de peso en kg en System > Localisation > Weight Classes. Una unidad de longitud desconocida en la tienda hace que Box size se lea como cm. Usa cm, mm, m o in como clase de longitud de la tienda (System > Settings, pestaña Option).

Rates look outdated after a change: haz clic en Save en la página de la extensión o en Clear cached UPS token and rates.

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

For developers: la extensión dispara eventos de OpenCart a los que otras extensiones pueden suscribirse: vfd_ups/allowed_services y vfd_ups/excluded_services restringen los servicios de UPS que pueden mostrarse, vfd_ups/rate_request modifica la solicitud de tarifa, vfd_ups/api_base_url cambia la dirección de la API y vfd_ups/currency_codes asigna los códigos de moneda que devuelve UPS.

Desinstalar

Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox UPS. OpenCart siempre restablece Enable UPS shipping, Sort order, Tax class y Geo zone. El token y las tarifas de UPS en caché siempre se eliminan. Si Remove data on uninstall está activado, también se borran los ajustes de UPS y el registro de depuración. Si está desactivado, los demás ajustes se conservan y se vuelven a usar al reinstalar la extensión. Los servicios de UPS guardados con los pedidos nunca se eliminan, y 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 UPS en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

UPS es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por UPS.