VibeFox USPS for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala con versiones anteriores de PHP.
Aplicación en el USPS Developer Portal (solo para tarifas en tiempo real): inicia sesión en el USPS Developer Portal (developers.usps.com) con una cuenta de empresa gratuita de USPS, crea una aplicación y copia su Consumer Key y su Consumer Secret. El módulo usa las API actuales de USPS con OAuth 2.0. USPS desactivó la antigua API Web Tools (User ID y XML) el 25 de enero de 2026, por lo que un Web Tools User ID ya no funciona. Sin claves, solo se usan los precios fijos.
Ship-from ZIP code: las tarifas en tiempo real necesitan el código ZIP de 5 dígitos de EE. UU. desde el que se envían los paquetes.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 más tarde VibeFox USPS en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).
4. Introduce el Consumer Key y el Consumer Secret, el Ship from ZIP code de 5 dígitos y elige los servicios. Si la moneda predeterminada de tu tienda no es USD, introduce el USD exchange rate. Opcionalmente, introduce precios fijos como alternativa. Haz clic en Save.
Al instalar, el módulo crea el transportista USPS con el texto del plazo de entrega Delivery by USPS. El transportista se asigna a todas las zonas y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No definas 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 USPS > 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 también borra el token de USPS y las tarifas en caché.
Un valor no válido no se guarda: se mantiene el valor anterior y un mensaje de error indica el campo, mientras que los demás campos sí se guardan. Las advertencias en la parte superior de la página te indican cuando solo está configurada una de las claves, cuando no hay claves ni precios fijos (entonces el transportista nunca se muestra), cuando falta el código ZIP de origen, cuando no hay ningún servicio seleccionado, cuando falta el tipo de cambio USD, cuando el entorno de pruebas está activado, cuando la unidad de peso o de dimensiones de la tienda es desconocida (configúrala en International > Localization, Local units) o cuando se ha eliminado el transportista de USPS.
General
Enable USPS 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 compra. Predeterminado: USPS. Obligatorio, hasta 64 caracteres.
Tax status: la regla de impuestos del transportista. Los precios de USPS no incluyen impuestos. Elige una regla de impuestos para añadir el impuesto del envío, o None si el envío no tiene impuestos.
API de USPS (tarifas en tiempo real)
Consumer Key: el Consumer Key (client_id) de tu aplicación de desarrollador de USPS.
Consumer Secret: el Consumer Secret (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. Borrar el Consumer Key también elimina el secreto guardado.
Test environment: usa el USPS Testing Environment for Mailers (apis-tem.usps.com). Solo para aplicaciones que tengan acceso a él. Déjalo desactivado para tarifas reales (apis.usps.com). Predeterminado: desactivado.
Prices: qué tarifas de USPS se usan.
Services: los servicios de USPS que pueden ofrecerse. Se muestra el servicio seleccionado más barato que USPS ofrece para el paquete. Las tarifas Flat Rate, Cubic, Hold for Pickup y Sunday nunca se usan. Predeterminado: USPS Ground Advantage, Priority Mail y First-Class Package International Service. Si no se selecciona ningún servicio, no se usan las tarifas en tiempo real.
USD exchange rate: las tarifas de USPS están en USD. Si la moneda predeterminada de tu tienda no es USD, introduce el precio de 1 USD en esa moneda, por ejemplo 0.92. Sin él, no se usan las tarifas en tiempo real y se aplican los precios fijos. No hace falta si la moneda predeterminada es USD. Debe ser mayor que 0.
Cache: el botón Clear cached USPS token and rates vacía la caché de inmediato. Las tarifas se guardan en caché durante 1 hora y una tarifa fallida, durante 10 minutos. Tras un timeout, un error del servidor, un límite de peticiones o claves rechazadas, no se llama a USPS durante 5 minutos.
Origen y paquete (las tarifas de USPS dependen del código ZIP de origen, del peso y del tamaño del paquete; el carrito se cotiza como un único paquete, y los paquetes de más de 70 lb usan los precios fijos)
Ship from ZIP code: el código ZIP de 5 dígitos de EE. UU. desde el que se envían los paquetes. Un código ZIP+4 se recorta a 5 dígitos. Otros valores se rechazan con un mensaje.
Box size: dimensiones opcionales de la caja en la unidad de dimensiones de tu tienda, por ejemplo 30x20x15. Déjalo vacío para calcular el tamaño a partir de las dimensiones de los productos: la longitud mayor, la anchura mayor y las alturas apiladas. Si un producto no tiene dimensiones, se usa una caja de 10 x 8 x 4 pulgadas.
Default product weight: el peso en kg que se usa para los productos sin peso, en las tarifas de USPS, en los límites de peso y en los tramos de peso. Predeterminado: 0.5.
Precios fijos (precios en la moneda predeterminada de tu tienda, sin impuestos; se usan cuando no se introducen claves de API y como alternativa cuando USPS no devuelve ninguna tarifa: API caída, claves incorrectas, ningún servicio o un destino sin código ZIP de EE. UU.; deja ambos campos vacíos para ocultar el transportista en ese caso)
Country prices: precios por país de destino y peso del carrito. Haz clic en Add country para añadir una fila y en el icono de papelera para eliminarla. Las columnas son Price y los tramos de peso XS (hasta 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) y XL (más de 5 kg). Un tramo vacío o 0 usa Price. La fila * Default (any other country) se aplica a cualquier otro país. Una fila de país sin ningún precio envía ese país a Fallback cost. Los valores que no son números se borran con un mensaje.
Fallback cost: un precio fijo cuando no coincide ningún precio por país. Déjalo vacío para ocultar el transportista en ese caso.
Fixed price is: Per order cobra el precio una 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 el peso de una unidad (el peso predeterminado si no tiene) y lo multiplica por su cantidad. Las tarifas en tiempo real de USPS siempre se cotizan para todo el paquete.
Condiciones
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual este transportista es gratuito. En ese caso no se envía ninguna petición a USPS. Déjalo vacío para no ofrecer nunca envío gratuito.
Minimum subtotal: muestra el transportista solo si el subtotal del carrito es al menos este importe. 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: 30. USPS acepta hasta 70 lb (31,7 kg). 0 significa sin límite. Si Min weight es mayor que Max weight, se muestra un error y se mantienen los límites anteriores.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece el transportista en todas las zonas para los países indicados abajo. Al guardar, el transportista se vincula a todas las zonas de la tienda, también a las que se creen después. Al desactivarlo, el transportista recupera sus zonas anteriores.
Countries: los países de destino para ese modo. Déjalo vacío para permitir todos los países a los que la tienda envía. Este campo se usa solo cuando Ignore shipping zones está activado.
Avanzado
Debug log: registra las peticiones a la API y el cálculo de tarifas en logs/vfd_usps_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, incluso con esta opción desactivada. Las claves, 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 de USPS, el transportista, los servicios guardados de los pedidos, las tarifas en caché y los registros. Si está desactivado, se conserva todo para una reinstalación.
Cómo funciona al finalizar la compra
En el paso de envío, PrestaShop pide al módulo el precio de USPS. Solo cuentan los productos físicos: los productos virtuales no añaden peso ni se incluyen en el subtotal. El módulo primero comprueba las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna petición a USPS.
El módulo obtiene de USPS un token OAuth y lo conserva hasta poco antes de que caduque. Un token que USPS rechaza se renueva y la cotización se repite. Para destinos en EE. UU. y sus territorios (Puerto Rico, las Islas Vírgenes de EE. UU., Guam, Samoa Americana, las Islas Marianas del Norte, Micronesia, las Islas Marshall y Palaos) consulta la API de Domestic Prices y necesita el código ZIP de 5 dígitos del cliente. Para otros países consulta la API de International Prices con el país y el código postal.
La petición incluye el código ZIP de origen, el peso del carrito en libras, el tamaño del paquete en pulgadas y el tipo de precio. Los paquetes de más de 70 lb reciben los precios fijos. El cliente ve una única opción con el servicio seleccionado más barato, convertida de USD a la moneda predeterminada de tu tienda y mostrada después en la moneda del carrito del cliente.
Cada cotización se guarda en caché durante 1 hora. Una cotización fallida se recuerda durante 10 minutos. Tras un timeout, un error del servidor, un límite de peticiones o claves rechazadas, no se llama a USPS durante 5 minutos. El timeout HTTP es de 10 segundos.
Si USPS no devuelve ninguna tarifa, el precio sale de Country prices y, después, de Fallback cost. Si ninguno se aplica, el transportista se oculta. El cliente nunca ve los textos de error de USPS. El motivo se escribe en el registro.
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 compra franqueo ni etiquetas de envío, no reserva recogidas, no hace seguimiento de paquetes ni permite al cliente elegir una oficina de Correos o un punto de recogida. Muestra una única opción, no varios servicios de USPS. No hay empaquetado en cajas: el carrito se cotiza como un único paquete. No se incluyen seguros ni otros servicios adicionales.
Pedidos
Cuando se realiza un pedido con el transportista de USPS, el módulo guarda cómo se obtuvo el precio del envío. La página del pedido en el back office muestra un bloque USPS con el USPS service (para una tarifa en tiempo real, por ejemplo USPS Ground Advantage) y el Price source: USPS live rate, Fixed price o Free shipping.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox USPS es el primero de la página Modules > Module Manager > VibeFox USPS > 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-usps 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 un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, el transportista de USPS no se muestra a los clientes en la compra y no se calcula ninguna tarifa. PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la 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 requieren 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 tras introducir la clave y, después, una vez a la semana. No hace falta 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
USPS no aparece en la compra: comprueba que la licencia esté activa y que Enable USPS shipping esté activado. En Shipping > Carriers comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y el Minimum subtotal. Sin claves de USPS en funcionamiento, el transportista necesita un precio fijo (Country prices o Fallback cost). Los productos también pueden limitarse a ciertos transportistas en la página del producto.
Las tarifas en tiempo real no aparecen: revisa las advertencias en la parte superior de la página del módulo. Activa Debug log, recarga la compra y mira el campo Log. Allí se registran las claves incorrectas, el entorno incorrecto y los mensajes de error de USPS. Las tarifas nacionales necesitan el código ZIP de 5 dígitos del cliente.
Mi tienda no está en USD: USPS cotiza solo en USD. Introduce el USD exchange rate. Sin él, no se usa la tarifa en tiempo real y se muestra el precio fijo.
Un Web Tools User ID no funciona: la antigua API Web Tools está desactivada. Crea una aplicación en el USPS Developer Portal y usa su Consumer Key y su Consumer Secret.
Las tarifas parecen desactualizadas tras un cambio: la caché se borra al guardar los ajustes. También puedes hacer clic en Clear cached USPS token and rates.
La página indica que no se encontró el transportista de USPS: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox USPS y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. El token y las tarifas en caché también se eliminan siempre. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes, los servicios guardados de los pedidos y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo, o con Reset, el transportista guardado recupera su estado anterior: un transportista que estaba activo vuelve a estarlo, y uno desactivado sigue desactivado.
USPS es una marca comercial de su respectivo titular. Este módulo no está afiliado a USPS ni cuenta con su respaldo.