Manual de la extensión USPS para OpenCart 4.1.0.4
Calcula tarifas de envío en tiempo real con USPS durante el checkout, utilizando la plataforma actual de USPS (OAuth 2.0 + Domestic/International Prices 3.0, apis.usps.com).
Qué hace automáticamente
Agrupa productos en cajas según peso y volumen
Solicita precios de cada servicio habilitado
Solo muestra servicios que transportan todas las cajas
Aplica ajustes de tarifa, impuestos y moneda
Tarifa de respaldo si USPS no responde
1. Requisitos del sistema
Antes de empezar, verifica que tu tienda cumple estos requisitos mínimos.
OpenCart 4.1.0.4
Versión específica compatible con esta extensión.
PHP + curl + openssl
Vienen activadas por defecto en la mayoría de hostings.
Cuenta de negocio USPS
Con acceso a la API de desarrolladores.
ZIP de origen 5 dígitos
Código postal desde donde realizas los envíos.
2. Instalación paso a paso
Sigue estos pasos exactamente en el orden indicado. No se utiliza FTP para esta instalación.
1Subir el archivo .ocmod.zip
En el panel de administración, ve a Extensiones → Instalador. Haz clic en el botón de subir y selecciona el archivo usps.ocmod.zip.
El archivo debe llamarse exactamente así (terminado en .ocmod.zip). Si tu navegador le añadió algo como (1) al descargarlo, renómbralo antes de subirlo.
2Instalar la extensión
Ve a Extensiones → Extensiones, filtra por tipo Envíos (Shipping), busca USPS y haz clic en el botón verde de instalar.
3Entrar a configuración
Pulsa el icono de editar (lápiz) para entrar a configurar la extensión.
3. Obtener credenciales USPS (OAuth 2.0)
USPS ya no usa el antiguo USERID. Ahora necesitas un Consumer Key y un Consumer Secret.
1Inicia sesión en developers.usps.com
Entra con tu cuenta de negocio USPS. Si no tienes una, créala desde allí.
Ir al portal de desarrolladores2Crea una nueva aplicación
Ve a Apps → Add App. Ponle un nombre, acepta los términos, y en Select API Product confirma que incluya Domestic Prices e International Prices.
Crear nueva App3Copia las credenciales
Abre la App creada → pestaña Credentials → copia el Consumer Key y el Consumer Secret.
Ver mis credencialesEl Secret normalmente solo se muestra una vez. Guárdalo en un lugar seguro inmediatamente.
4. Guía completa de configuración
Todos los campos están en Extensiones → Envíos → USPS → Editar.
General
USPS Account
Parcel & Rates
Services
Marca qué servicios de USPS quieres ofrecer. Si USPS no puede transportar una caja con un servicio concreto, ese servicio simplemente no aparece para ese pedido.
Recomendación: Marca solo 2–3 servicios habituales (p. ej. USPS Ground Advantage y Priority Mail) en vez de todos. Cuantos más servicios marques, más llamadas a la API se hacen por cotización.
5. Caché y límites de la API
Las APIs de USPS limitan por defecto a 60 peticiones por hora por aplicación. Por eso cada combinación de caja + servicio + destino se guarda en caché (duración configurable en Advanced).
Sin caché, una tienda con tráfico normal agotaría el límite en minutos y empezaría a fallar en pleno checkout.
Esto implica:
Los primeros minutos tras cambiar algo (precio, caja, destino) pueden tardar un poco más mientras se piden tarifas nuevas.
Si bajas la duración del caché a 0 para probar algo, hazlo solo temporalmente.
Si tienes mucho tráfico internacional o muchos servicios marcados, puede que necesites pedir a USPS un límite más alto para tu aplicación.
6. Solución de problemas
Problemas comunes y cómo resolverlos rápidamente.
Si activas Debug Log, los errores de USPS quedan en el log del sistema (System → Maintenance → Error Log). Nunca se registran credenciales ni tokens.
¿Necesitas ayuda con tu tienda OpenCart?
Si tienes dudas específicas sobre esta extensión o necesitas configurar tu tienda, escríbenos. Te ayudamos a tener todo funcionando correctamente.