VibeFox UPS for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior, con la extensión cURL. El módulo no se instala en versiones anteriores de PHP ni sin 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. El módulo 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 el back office, ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure, o busca después VibeFox UPS en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).
4. Introduce el Client ID y el Client Secret, tu número de cuenta de UPS (para las tarifas negociadas) y la dirección Ship from: el código postal y, para EE. UU. y Canadá, el estado de 2 letras.
5. Si la moneda de tu cuenta de UPS es distinta de la moneda predeterminada de tu tienda, introduce UPS account currency y Exchange rate.
6. Opcionalmente, introduce precios fijos como alternativa y haz clic en Save.
Al instalar, el módulo crea el transportista UPS con el texto de tiempo de entrega UPS delivery. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar zonas, grupos de clientes, tiempo de entrega, logotipo y límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre procede del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox UPS > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado borra 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 indican cuando solo está definido uno de Client ID y Client Secret, cuando no hay credenciales ni precios fijos (entonces el transportista nunca se muestra), cuando falta el código postal o el estado de la dirección de origen, cuando se eligen tarifas de cuenta sin número de cuenta, cuando falta el tipo de cambio, o cuando el módulo no reconoce la unidad de peso o de dimensiones de la tienda. Los números no válidos, un tamaño de caja incorrecto y un Min weight superior a Max weight se notifican al guardar, y se conserva el valor anterior.
General
Enable UPS shipping: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del transportista que ve el cliente en la finalización de compra. Predeterminado: UPS. Obligatorio, 64 caracteres como máximo.
Tax status: la regla de impuestos del transportista, o None. Las tarifas de UPS se calculan sin impuestos. Con una regla de impuestos, la tienda añade encima su impuesto de envío.
API de UPS (tarifas en tiempo real)
Test mode: usa el entorno de pruebas de UPS. Las tarifas de prueba no son precios reales. Desactívalo para obtener tarifas reales. Predeterminado: off.
Client ID: el Client ID de tu aplicación en el UPS Developer Portal. Si lo borras, también se elimina el Client Secret guardado.
Client Secret: el Client Secret de la misma aplicación. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
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: calcula las direcciones de los clientes como residenciales, con el recargo residencial de UPS. Desactívalo si envías sobre todo a empresas. Predeterminado: on.
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 calcular solo por peso.
UPS account currency: UPS calcula en la moneda del país de la cuenta de remitente, por ejemplo USD para EE. UU., CAD para Canadá o EUR para la eurozona. Predeterminado: 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.
Origen del envío (la dirección desde la que UPS recoge o donde 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.
City: la ciudad desde la que envías.
ZIP / postal code: el código postal desde el que envías. UPS lo necesita para calcular las tarifas.
Precios fijos (se usan cuando no se introducen credenciales de API y como alternativa cuando UPS no devuelve ninguna tarifa; deja ambos campos vacíos para ocultar el transportista 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. El país * 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. 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 predeterminada de tu tienda cuando ningún precio por país coincide. Déjalo vacío para ocultar el transportista en ese caso.
Fixed price is: Per order cobra el precio una sola vez, según el peso de todo el carrito. Per item (each item priced by its own weight x quantity) calcula cada producto según su propio peso (el peso predeterminado si no tiene) y lo multiplica por su cantidad. Si un producto no tiene precio fijo, el transportista se oculta. Las tarifas en tiempo real de UPS siempre se calculan para el peso total del carrito.
Condiciones
Free shipping from: el subtotal del carrito (productos que requieren envío, después de descuentos y antes de impuestos) a partir del cual este transportista es gratuito. En ese caso no se envía ninguna petición a UPS. Déjalo vacío para no ofrecer nunca envío gratuito.
Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito sea al menos esta cantidad. Déjalo vacío para mostrarlo siempre.
Min weight: el peso mínimo del carrito en kg para que aparezca este transportista. 0 significa sin límite.
Max weight: el transportista se oculta por encima de este peso del carrito en kg. Predeterminado: 70, el límite de UPS por paquete (70 kg / 150 lbs). 0 significa sin límite; vacío equivale a 70. Min weight no puede ser superior a Max weight.
Default product weight: el peso en kg 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.
Disponibilidad sin zonas de envío
Normalmente el transportista se ofrece en las zonas que tiene asignadas en Shipping > Carriers.
Ignore shipping zones: ofrece el transportista para los países indicados abajo, sea cual sea la zona que corresponda. Al guardar, el transportista se añade a todas las zonas y también a las zonas que se creen después. Al desactivarlo, esas zonas se eliminan de nuevo.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos 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 logs/vfd_upsx_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran, aunque esta opción esté desactivada. Las credenciales, los tokens y las direcciones de los clientes nunca se registran.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes, el transportista, los tokens y tarifas en caché, el registro y los servicios de UPS guardados con los pedidos. Los pedidos en sí se conservan. Si está desactivado, todo se conserva para una reinstalación.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de UPS. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el subtotal. El módulo comprueba primero las condiciones: los países de Ignore shipping zones, el peso del carrito y el subtotal mínimo. Si se aplica envío gratuito, el precio es 0 y no se envía ninguna petición a UPS.
El módulo 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 dirección del cliente, para el carrito como un único paquete. En los países con código postal, la petición espera a que el cliente lo haya introducido. En los envíos desde EE. UU. a Canadá o Puerto Rico se envía el valor de la mercancía, como exige UPS.
El cliente ve una sola opción con el servicio de UPS más barato. El precio se calcula en la moneda predeterminada de tu tienda y después se muestra en la moneda del carrito del cliente. UPS Access Point Economy no se calcula, porque el módulo 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.
Si UPS no devuelve ninguna tarifa (API caída, credenciales incorrectas, ningún servicio, otra moneda sin tipo de cambio), el precio se toma de Country prices y, después, de Fallback cost. Si no se aplica ninguno de los dos, el transportista se oculta. El cliente nunca ve textos de error de UPS.
Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.
El módulo 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 opción, no varios servicios de UPS. No hay empaquetado en cajas: el carrito se calcula como un único paquete. Los tipos de cambio no son automáticos.
Pedidos
Cuando se realiza un pedido con una tarifa de UPS en tiempo real, el servicio de UPS se guarda con el pedido. La página del pedido en el back office muestra un bloque UPS con el UPS service, por ejemplo UPS Ground, y la Live rate (excl. tax). Los cambios posteriores en el carrito desde el back office no lo modifican. Los pedidos con precio fijo o envío gratuito no tienen este bloque.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox UPS es el primer bloque de Modules > Module Manager > VibeFox UPS > Configure, 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: presta-shipping-ups y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 con 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 acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar 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 transportista de UPS no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un aviso en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: 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 o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
UPS no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable UPS shipping esté activado. En Shipping > Carriers comprueba que el transportista cubra la zona del país del cliente y el grupo de clientes, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y el Minimum subtotal. Sin credenciales de UPS válidas, el transportista necesita un precio fijo (Country prices o Fallback cost). Además, en la página del producto se pueden limitar los productos a determinados transportistas.
Las tarifas en tiempo real no aparecen: revisa las advertencias de la parte superior de la página Configure. Activa Debug log, recarga la finalización de compra y mira el campo Log en la página del módulo. Muestra los errores de OAuth (revisa el Client ID, el Client Secret y 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 de 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.
La página advierte que la unidad de peso o de dimensiones de la tienda no es conocida: entonces los pesos se leen como kg y el tamaño de la caja como cm. Define una unidad estándar (kg, g, lb u oz; cm, mm, m o in) en International > Localization, sección Local units.
Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo o en Clear cached UPS token and rates.
La página indica que no se ha encontrado el transportista de UPS: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Para desarrolladores: los hooks actionVfdUpsxAllowedServices y actionVfdUpsxExcludedServices limitan los servicios de UPS que se pueden mostrar. actionVfdUpsxRateRequest modifica la petición de tarifas, actionVfdUpsxApiBaseUrl la dirección de la API y actionVfdUpsxCurrencyCodes asigna los códigos de moneda que devuelve UPS.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox UPS y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. El token de UPS y las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial), y se eliminan los ajustes, el registro y los servicios de UPS guardados con los pedidos. Si está desactivado, el transportista solo se desactiva y los ajustes se conservan. Al volver a instalar el módulo, o con un restablecimiento, el transportista recupera el estado que tenía antes.
UPS es una marca comercial de su respectivo titular. Este módulo no está afiliado ni avalado por UPS.