VibeFox UPS for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Aplicación del 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. El plugin usa OAuth 2.0. No se necesita 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
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta vfd_ups a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Shipping > VibeFox UPS, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
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 de la tienda, introduce UPS account currency y Exchange rate.
7. Añade VibeFox UPS a una zona de envío en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones y elige los países.
8. Opcionalmente, introduce precios fijos como alternativa.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox UPS. Se aplican a todas las zonas de envío. Cuando añades el método a una zona, la ventana de la zona solo tiene un campo:
Title (zone): el nombre de esta opción en la finalización de compra. Déjalo vacío para usar el Name global.
Cada vez que guardes los ajustes se borran el token de UPS y las tarifas en caché. También puedes hacer clic en Clear cached UPS token and rates en la sección UPS API. Las advertencias sobre los ajustes te avisan cuando solo hay uno de Client ID y Client Secret, cuando no hay credenciales ni precios fijos, cuando falta el código postal o el estado del origen del envío, cuando se eligen tarifas de cuenta sin número de cuenta o cuando falta el tipo de cambio.
General
Enable/Disable: activa o desactiva el método en todas las zonas a la vez.
Name: el nombre del método de envío que se muestra en la finalización de compra. Predeterminado: UPS.
Tax status: Taxable hace que WooCommerce añada su impuesto de envío encima, None no lo añade. Las tarifas de UPS se cotizan sin impuestos, así que el impuesto no se cobra dos veces.
API de UPS (tarifas en tiempo real)
Test mode: usa el entorno de prueba de UPS. Las tarifas de prueba no son precios reales. Desactívalo para tarifas en tiempo real. Predeterminado: desactivado.
Client ID: el Client ID de tu aplicación en el UPS Developer Portal.
Client Secret: el Client Secret de la misma aplicación.
UPS account number: tu número de remitente de UPS de 6 caracteres, por ejemplo A1B2C3. Es necesario para las tarifas de cuenta (negociadas) y opcional para las tarifas públicas.
Rates: qué precios de UPS se usan.
Measurement units: las unidades que se envían a UPS. Los pesos y tamaños 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. Predeterminado: activado.
Box size: dimensiones opcionales de la caja en la unidad de dimensiones de tu tienda, 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 remitente, por ejemplo USD para EE. UU., CAD para Canadá o EUR para la eurozona. Predeterminado: USD.
Exchange rate: solo es necesario si la moneda de la cuenta de UPS es distinta de la moneda de la tienda. Introduce el precio de 1 unidad de la moneda de la cuenta en la moneda de tu tienda, 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.
Dirección de origen (la dirección desde la que UPS recoge los paquetes o donde los entregas; 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.
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.
Precios fijos (se usan cuando no hay credenciales de API y como alternativa cuando UPS no devuelve ninguna tarifa; deja ambos vacíos para ocultar el método en ese caso)
Country prices: precios en la moneda de tu tienda por país de destino. Haz clic en + Add country para añadir una fila y en la X para quitar una. La fila * Default se aplica a cualquier otro país. Una columna de peso (XS hasta 1 kg, S 1–2 kg, M 2–3 kg, L 3–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. Las filas sin ningún precio se eliminan al guardar, y los valores que no son números se rechazan con un mensaje.
Fallback cost: un precio fijo en la moneda de tu tienda cuando ningún precio por país coincide. Déjalo vacío para ocultar el método en ese caso.
Fixed price is: Per order cobra el precio una sola vez. Per item (each item priced by its own weight x quantity) calcula cada artículo 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 para el peso total del carrito.
Condiciones
Free shipping from: el subtotal del carrito a partir del cual este método es gratuito. El cliente ve el nombre del método con "(Free)" y no se envía ninguna petición a UPS. 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.
Max weight (kg): el método se oculta por encima de este peso del carrito. Predeterminado: 70, el límite de UPS por paquete (70 kg / 150 lbs). 0 significa sin límite.
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. Predeterminado: 0.5.
Excluded shipping classes: oculta el método si el carrito contiene un producto de alguna de estas clases de envío de WooCommerce.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece el método para los países indicados abajo, aunque no esté añadido a una zona de envío.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países de envío de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra las peticiones a la API y el cálculo de tarifas en WooCommerce > Status > Logs, origen vfd-ups. 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.
Remove data on uninstall: si está activado, al eliminar el plugin se borran todos sus ajustes y los métodos de zona. Desactivar el plugin nunca borra los ajustes.
Cómo funciona en la finalización de compra
Cuando el cliente introduce una dirección de entrega, WooCommerce pide una tarifa al plugin. El plugin comprueba primero las condiciones: peso del carrito, subtotal mínimo y clases de envío excluidas. Si se aplica el envío gratuito, el método se muestra como gratuito y no se envía ninguna petición a UPS.
El plugin obtiene un token OAuth de UPS y lo conserva hasta que caduca. Un token que UPS rechaza se renueva automáticamente. Después pide a la API Rating de UPS todos los servicios desde tu dirección de origen hasta la del cliente, para el carrito como un único paquete. En los países con códigos postales, la petición espera hasta que el cliente haya introducido uno. En los 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 de UPS más barato, convertida a la moneda de tu tienda. UPS Access Point Economy no se cotiza, porque el plugin no recoge una dirección de Access Point.
Cada tarifa se guarda en caché durante 1 hora. Una petición fallida se recuerda durante 10 minutos, y una petición 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. Desactivar el plugin borra el token y las tarifas en caché.
Si UPS no devuelve ninguna tarifa (API caída, credenciales incorrectas o ningún servicio), el precio se toma de Country prices y, después, de Fallback cost. Si ninguno se aplica, el método se oculta. El cliente nunca ve los mensajes de error de UPS.
El método funciona en la finalización de compra clásica y en los bloques Carrito y Finalizar compra. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin solo calcula tarifas. No ofrece la selección de UPS Access Point, no crea etiquetas 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 único paquete. Los tipos de cambio no son automáticos.
Pedidos
En una tarifa en tiempo real, la línea de envío del pedido guarda el UPS service, por ejemplo UPS Ground. El gestor de la tienda lo ve en la pantalla de pedido del administrador.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Shipping > VibeFox UPS. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Quitar la clave de un sitio no libera su cupo de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, UPS no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión lo siguen viendo, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
UPS no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el método está añadido a la zona del país del cliente (o que Ignore shipping zones está activado y el país está permitido). Revisa los límites de peso, el Minimum subtotal y las Excluded shipping classes. Sin credenciales de UPS válidas, el método necesita un precio fijo (Country prices o Fallback cost).
Las tarifas en tiempo real no aparecen: revisa las advertencias de la parte superior de la página de ajustes. Activa el Debug log y abre WooCommerce > Status > Logs, origen vfd-ups. Ahí verás los errores de OAuth (revisa el Client ID, el Client Secret y el Test mode), los mensajes de error de UPS y los problemas de moneda.
La tarifa está en USD pero la tienda no: UPS devuelve las tarifas en la moneda de la cuenta del remitente. Define UPS account currency y 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, o elige las unidades que UPS espera para tu país de origen.
Las tarifas parecen desactualizadas tras un cambio: guarda la página de ajustes o haz clic en Clear cached UPS token and rates.
Para desarrolladores: los filtros vfd_upsx_allowed_services y vfd_upsx_excluded_services limitan los servicios de UPS que se pueden mostrar. vfd_upsx_rate_request modifica la petición de tarifa, vfd_upsx_api_base_url la dirección de la API y vfd_upsx_currency_codes asigna los códigos de moneda que devuelve UPS.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera un cupo en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva los ajustes y solo borra el token y las tarifas en caché. Para eliminarlo, desactívalo y bórralo en la página de Plugins. La clave de licencia y el estado de la licencia de este plugin, así como el token y las tarifas en caché, siempre se eliminan. Los ajustes y los métodos de zona se eliminan solo si Remove data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus líneas de envío.
UPS es una marca comercial de su respectivo propietario. Este plugin no está afiliado a UPS ni cuenta con su respaldo.