VibeFox USPS 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 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 Consumer Secret. El plugin usa las API actuales de USPS con OAuth 2.0. USPS retiró la antigua API Web Tools (User ID y XML) el 25 de enero de 2026, así que un User ID de Web Tools 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.

VibeFox license key: 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_usps a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Shipping > VibeFox USPS, o haz clic en Settings bajo el nombre del plugin en la página 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 Consumer Key y el Consumer Secret, el Ship from ZIP code de 5 dígitos y elige los servicios. Si la moneda de tu tienda no es USD, introduce el USD exchange rate.

6. Añade VibeFox USPS a una zona de envío en WooCommerce > Settings > Shipping > Shipping zones, o activa Ignore shipping zones y elige los países.

7. Opcionalmente, introduce precios fijos como alternativa.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Shipping > VibeFox USPS. Se aplican a todas las zonas de envío. Al añadir 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 general.

Cada vez que guardes los ajustes, se borran el token de USPS y las tarifas en caché. También puedes hacer clic en Clear cached USPS token and rates en la sección USPS API. Las advertencias encima de los ajustes te avisan cuando solo está definida una de las claves, cuando no hay claves ni precios fijos, cuando falta el código ZIP de origen, cuando no hay ningún servicio seleccionado, cuando falta el tipo de cambio USD o cuando el entorno de prueba está activado.

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. Por defecto: USPS.

Tax status: las tarifas de USPS no incluyen impuestos. Taxable permite que WooCommerce añada su impuesto de envío al coste; None no lo añade.

USPS API (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.

Test environment: usa el USPS Testing Environment for Mailers. Solo para aplicaciones que tengan acceso a él. Déjalo desactivado para obtener precios reales. Por defecto: desactivado.

Prices: qué precios 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. Por defecto: USPS Ground Advantage, Priority Mail y First-Class Package International Service.

USD exchange rate: las tarifas de USPS están en USD. Si la moneda de tu tienda no es USD, introduce el precio de 1 USD en la moneda de tu tienda, por ejemplo 0.92. Sin él, no se usan las tarifas en tiempo real y se aplican los precios fijos. No es necesario si la moneda de la tienda es USD.

Origen del envío y paquete (las tarifas de USPS dependen del código ZIP de origen, del peso y del tamaño del paquete)

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: medidas 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 del producto: la longitud más larga, la anchura más ancha y las alturas apiladas. Si un producto no tiene dimensiones, se usa una caja de 10 x 8 x 4 pulgadas.

Default product weight (kg): el peso que se usa para los productos sin peso, en las tarifas de USPS, los límites de peso y los tramos de peso. Por defecto: 0.5.

Precios fijos (precios en la moneda de tu tienda; se usan cuando no se introduce ninguna clave de API y como alternativa cuando USPS no devuelve tarifa: API caída, claves incorrectas, ningún servicio o un destino sin código ZIP de EE. UU.; deja ambos vacíos para ocultar el método 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 cruz para eliminar una. 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 se aplica a cualquier otro país. 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 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 el precio de cada artículo según su propio peso (el peso por defecto si no tiene) y lo multiplica por su cantidad. Las tarifas en tiempo real de USPS siempre se calculan para el paquete completo.

Condiciones

Free shipping from: el subtotal del carrito a partir del cual este método es gratuito. Entonces no se envía ninguna solicitud a USPS. Déjalo vacío para no ofrecer nunca envío gratuito.

Minimum subtotal: muestra el método solo cuando el subtotal del carrito sea 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. Por defecto: 30. USPS acepta hasta 70 lb (31,7 kg). 0 significa sin límite.

Excluded shipping classes: oculta el método si el carrito contiene un producto de cualquiera 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 se haya 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 solicitudes a la API y el cálculo de tarifas en WooCommerce > Status > Logs, origen vfd-usps. 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.

Remove data on uninstall: si está activado, al eliminar el plugin se borran todos los ajustes del plugin y los métodos de las zonas. 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. Primero, el plugin comprueba 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 con un precio de 0 y no se envía ninguna solicitud a USPS.

El plugin obtiene un token OAuth de USPS y lo conserva hasta que caduque. Un token que USPS rechaza se renueva y la consulta se repite. Para destinos en EE. UU. y sus territorios (incluidos Puerto Rico, las Islas Vírgenes de EE. UU. y Guam) 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 solicitud contiene 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 opción con el servicio seleccionado más barato, convertido a la moneda de tu tienda.

Cada tarifa se guarda en caché durante 1 hora. Una tarifa fallida se recuerda durante 10 minutos. Tras un tiempo de espera, un error del servidor, un límite de solicitudes o unas claves rechazadas, no se llama a USPS durante 5 minutos. El tiempo de espera HTTP es de 10 segundos. Al desactivar el plugin se borran el token y las tarifas en caché.

Si USPS no devuelve tarifa, 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 textos de error de USPS.

El método funciona en la finalización de compra clásica y en los bloques de Carrito y Finalizar compra. Es compatible con WooCommerce High-Performance Order Storage (HPOS).

El plugin solo calcula tarifas. No compra franqueo ni etiquetas de envío, no reserva recogidas, no hace seguimiento de paquetes y no permite que el cliente elija una oficina de Correos o un punto de recogida. Muestra una sola opción, no varios servicios de USPS. No hay empaquetado en cajas: el carrito se cotiza como un único paquete. El seguro y otros servicios adicionales no están incluidos.

Pedidos

En una tarifa en tiempo real, la línea de envío del pedido guarda el USPS service, por ejemplo USPS Ground Advantage. El gestor de la tienda lo ve en la pantalla de pedidos 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 USPS. 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 plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, USPS no se muestra a los clientes en la finalización de compra. Los gestores de la tienda que han iniciado sesión siguen viéndolo, 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 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

USPS 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 claves de USPS 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 Debug log y abre WooCommerce > Status > Logs, origen vfd-usps. Allí se registran las claves incorrectas, el entorno equivocado 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 solo cotiza en USD. Introduce el USD exchange rate. Sin él, no se usa la tarifa en tiempo real y se muestra el precio fijo.

Un User ID de Web Tools no funciona: la antigua API Web Tools ha sido retirada. Crea una aplicación en el USPS Developer Portal y usa su Consumer Key y 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.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza 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 conectar con el 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 Plugins. La clave de licencia y el estado de licencia de este plugin, así como el token y las tarifas en caché, siempre se eliminan. Los ajustes y los métodos de zona solo se eliminan 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.

USPS es una marca comercial de su respectivo titular. Este plugin no está afiliado a USPS ni cuenta con su aprobación.