Resumen
APIs de USPS para transportistas: valida direcciones de EE. UU. y busca códigos ZIP, compara precios nacionales e internacionales, obtén días de entrega y opciones de envío, rastrea paquetes y encuentra Oficinas de Correos, sitios de entrega y Taquillas de Paquetes. Las etiquetas, reembolsos, recogidas y formularios SCAN están incluidos pero desactivados. Clave de Consumidor y Secreto de una aplicación en el Portal de Incorporación de Clientes de USPS.
Configuración guiada
Conecta USPS a Claude, ChatGPT o Copilot en 2 minutos
Empieza la prueba gratuita en AnythingMCP Cloud, conecta USPS con la configuración guiada y añade tu URL MCP a tu asistente de IA. Sin código y sin servidores que mantener.
Sin tarjeta de crédito · 7 días de prueba · Alternativa self-host disponible
Prueba a pedir
Prompts de ejemplo para USPS
Haz clic en un prompt para copiarlo. Pégalo en Claude, ChatGPT, Cursor, Gemini, Copilot u OpenClaw para ejecutarlo contra este conector.
Claude es IA y puede equivocarse. Verifica siempre las respuestas.
💡 ¿Sin instalación? Usa cloud.anythingmcp.com directamente. Inicia sesión, haz clic en Conectores → USPS, pega tus credenciales, genera una clave API de MCP y listo. Sin Docker, sin
git clone, sin servidor local.
USPS
APIs de USPS para transportistas: valida direcciones de EE. UU. y busca códigos ZIP, compara precios nacionales e internacionales, obtén días de entrega y opciones de envío, rastrea paquetes y encuentra Oficinas de Correos, sitios de entrega y Taquillas de Paquetes. Las etiquetas, reembolsos, recogidas y formularios SCAN están incluidos pero desactivados. Clave de Consumidor y Secreto de una aplicación en el Portal de Incorporación de Clientes de USPS.
Configuración
Configurar toma aproximadamente 15 minutos.
- Abre el Portal de Incorporación de Clientes de USPS en https://cop.usps.com/cop-navigator?wf=API e inicia sesión con tu Cuenta de Negocios de USPS, o crea una allí. El portal prepara la cuenta para las APIs de USPS.
- Selecciona Mis Aplicaciones en la parte superior del portal y añade una aplicación.
- Abre la aplicación. En Credenciales copia la Clave de Consumidor en
USPS_CLIENT_IDy el Secreto de Consumidor enUSPS_CLIENT_SECRET. - Elige la dirección de la API en
USPS_API_HOST: producciónhttps://apis.usps.com, o el Entorno de Pruebas para Mailershttps://apis-tem.usps.com. Ambos utilizan las mismas credenciales de producción. Las etiquetas generadas en el host de prueba están marcadas con una marca de agua y nunca se cobran. USPS publica el host de prueba para cada API excepto Seguimiento, así que mantén la producción cuando rastrees principalmente. - Opcional, para etiquetas y precios de contrato: tu CRID, ID de Mailer y número de Cuenta de Pago Empresarial en
USPS_CRID,USPS_MIDyUSPS_EPS_ACCOUNT_NUMBER. El Administrador de Servicios Empresariales de tu cuenta de Gateway de Clientes Empresariales los tiene.
El conector envía la Clave de Consumidor y el Secreto a /oauth2/v3/token en el host elegido (credenciales del cliente) y obtiene un token de portador válido por aproximadamente 8 horas, que reutiliza y renueva por sí mismo.
Lo que una nueva aplicación puede usar: cada aplicación comienza con el producto predeterminado de USPS: OAuth, Direcciones, Precios Nacionales, Precios Internacionales, Ubicaciones, Estándares de Servicio, Opciones de Envío y Seguimiento. Por lo tanto, las direcciones, precios, días de entrega, opciones de envío, seguimiento, Oficinas de Correos y ubicaciones de entrega funcionan de inmediato. Recogida de Transportista, Pagos, Etiquetas, Etiquetas Internacionales y Formularios SCAN necesitan aprobación de USPS: pídelo con una solicitud de servicio de API de USPS en la página Contáctanos (https://emailus.usps.com/s/usps-APIs). Las APIs de Etiquetas también necesitan inscripción en USPS Ship (etiquetas de envío y devolución) y una Cuenta de Pago Empresarial (EPS) que pague el franqueo. Las taquillas de paquetes (usps_find_parcel_lockers) y el estándar de servicio internacional (usps_get_international_service_standard) tienen sus propios alcances; si responden 403, pídelo a USPS de la misma manera.
Por dónde empezar: usps_get_city_state con un código ZIP prueba la conexión. Para una cotización, usps_search_shipping_options devuelve precios y fechas de entrega para cada servicio en una sola llamada; usps_search_domestic_prices y usps_search_international_prices dan el desglose de precios con servicios adicionales.
Direcciones: usps_validate_address estandariza una dirección de EE. UU. y devuelve el ZIP+4, DPVConfirmation (Y confirmado, D número secundario faltante, S número secundario no confirmado, N no confirmado), business (Y o N) y vacant. usps_get_zip_code encuentra el código ZIP de una calle en una ciudad y estado, usps_get_city_state la ciudad y estado de un código ZIP. Los estados son códigos de dos letras; solo se cubren direcciones de EE. UU. (incluyendo territorios y direcciones militares).
Precios: los paquetes se pesan en libras y se miden en pulgadas; las cartas, planos y tarjetas se pesan en onzas. price_type COMERCIAL es lo que pagas por etiquetas compradas en línea, RETAIL es el precio en el mostrador de la Oficina de Correos, CONTRATO necesita account_type y account_number. usps_search_domestic_prices devuelve rateOptions con totalBasePrice, totalPrice y los servicios adicionales; usps_list_domestic_prices lista cada producto elegible con su SKU, rateIndicator y processingCategory, los valores que necesita una solicitud de etiqueta. usps_search_letter_prices fija precios para cartas de Primera Clase, planos y postales. En el extranjero: usps_search_international_prices (opcionalmente con derechos e impuestos por artículo), usps_list_international_prices y usps_search_international_letter_prices. Las fechas de envío pueden ser hoy hasta 7 días adelante. Las cantidades son en dólares estadounidenses. USPS_GROUND_ADVANTAGE reemplazó el Servicio de Paquete de Primera Clase y Retail Ground.
Días de entrega: usps_get_delivery_estimates proporciona la fecha de entrega programada para un día de envío, con la hora límite de aceptación (cutOffTime, HHMM local); usps_get_service_standards el número estándar de días por clase de correo; usps_get_international_service_standard una frase como Entrega estimada en 5-9 días hábiles. Un estándar de servicio es un objetivo, no una garantía.
Seguimiento: usps_track_package para un número, usps_track_packages para hasta 35 a la vez. Ambos utilizan Seguimiento 3.2; la API de Seguimiento 3.0 heredada se retira el 31 de julio de 2027. La respuesta tiene statusCategory, statusSummary, trackingEvents (eventTimestamp en hora local del evento, GMTTimestamp en UTC), deliveryDateExpectation y uniqueTrackingID. Un lote responde HTTP 207 cuando algunos números fallan, y cada número fallido lleva su propio error. usps_register_tracking_notifications se inscribe hasta 3 direcciones de correo electrónico para correos electrónicos de seguimiento y usps_request_proof_of_delivery tiene una carta de prueba de entrega enviada por correo; ambos necesitan el uniqueTrackingID de una respuesta de seguimiento, envían correo desde USPS y no cuestan nada.
Ubicaciones: usps_find_post_offices busca por código ZIP, ciudad y estado, dirección o coordenadas (radio en millas, 20 por defecto) y lista los horarios de cada servicio; usps_find_dropoff_locations lista las instalaciones de entrada de destino para Parcel Select, USPS Connect y Servicios de Paquete por código ZIP de destino; usps_find_parcel_lockers encuentra Taquillas de Paquetes.
Recogidas: usps_check_pickup_eligibility y usps_get_pickup solo leen. usps_schedule_pickup reserva la recogida gratuita de Transportista (de lunes a sábado) y usps_cancel_pickup cancela una; ambos están desactivados. Una recogida no puede cambiarse aquí: cancélala y reserva una nueva.
Etiquetas (desactivadas): cada llamada de etiqueta necesita un token de autorización de pago. usps_create_payment_authorization con tu CRID, ID de Mailer y cuenta EPS devuelve paymentAuthorizationToken; pásalo a usps_create_label, usps_create_return_label, usps_create_international_label, usps_cancel_label o usps_cancel_international_label. Las etiquetas regresan como JSON: labelMetadata con el número de seguimiento y el franqueo, y labelImage en base64 (un PDF de 4x6 por defecto). Crear una etiqueta compra franqueo de la cuenta EPS. Una cancelación responde CANCELED, o DISPUTED con un disputeId cuando USPS abrió una solicitud de reembolso. usps_get_payment_account lee la cuenta y, con amount, indica si los fondos son suficientes. usps_create_scan_form coloca muchas etiquetas en un solo PS Form 5630 para un único escaneo de aceptación. Activa estas herramientas solo después de que USPS haya aprobado las APIs de Etiquetas, y pruébalas primero en el host de prueba.
Errores: los fallos vienen como error con code, message y una lista errors (title, detail, source.parameter). 400 indica el campo incorrecto; 401 significa credenciales incorrectas o un token expirado; 403 significa que la aplicación no tiene esa API (está fuera del producto predeterminado); 404 significa que USPS no encontró nada, por ejemplo, un número de seguimiento desconocido.
Límites: cada aplicación tiene una cuota de llamadas por hora; un 429 significa que se ha agotado hasta la próxima hora. USPS aumenta la cuota a solicitud a través de la página Contáctanos. Las fechas son YYYY-MM-DD.
Requisitos previos: USPS_CLIENT_ID, USPS_CLIENT_SECRET, USPS_API_HOST
Instalar el conector localmente
curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d
Abre http://localhost:3000/connectors/store, elige USPS y pega las variables de entorno listadas bajo Requisitos previos.
Herramientas disponibles
| Herramienta | Qué hace |
|---|---|
usps_validate_address | Valida y estandariza una dirección de EE. UU. Devuelve address en formato estándar de USPS (streetAddress, city, state, ZIPCode, ZIPPlus4)… |
usps_get_city_state | Busca la ciudad y el estado de un código ZIP de 5 dígitos. Devuelve city (en mayúsculas), state (dos letras) y ZIPCode. Llamada económica, utilizada como… |
usps_get_zip_code | Encuentra el código ZIP y ZIP+4 de una dirección en una ciudad y estado. Devuelve address con la calle estandarizada, city, state… |
usps_search_domestic_prices | Fija el precio de un paquete nacional a través de clases de correo, incluidos servicios adicionales. Devuelve rateOptions, uno por producto elegible, cada uno con… |
usps_list_domestic_prices | Lista cada producto para el que un paquete nacional es elegible, con su precio base y sin servicios adicionales. Devuelve rateOptions con… |
usps_search_letter_prices | Fija el precio de una carta de Primera Clase, plano (sobre grande) o postal enviada dentro de EE. UU. Devuelve totalBasePrice y rates (SKU… |
usps_search_international_prices | Fija el precio de un paquete internacional saliente, incluidos servicios adicionales y, a solicitud, derechos e impuestos por artículo. Devuelve rateOptions, uno por… |
usps_list_international_prices | Lista cada producto internacional para el que un paquete saliente es elegible, con precios base y sin servicios adicionales. Devuelve rateOptions con… |
usps_search_international_letter_prices | Fija el precio de una carta internacional de Primera Clase, plano o postal. Devuelve totalBasePrice, rates (SKU, description, price, fees)… |
usps_get_delivery_estimates | Estima la fecha de entrega del correo aceptado en un día dado. Devuelve una lista, una entrada por clase de correo, con serviceStandard (días)… |
usps_get_service_standards | Obtiene el número estándar de días de entrega entre dos códigos ZIP por clase de correo. Devuelve una lista con mailClass, days… |
usps_get_international_service_standard | Obtiene el tiempo de entrega esperado de una clase de correo internacional a un país. Devuelve countryCode, mailClass y… |
usps_search_shipping_options | Compara todas las formas de enviar un paquete en una sola llamada: precios y compromisos de entrega juntos, nacionales o internacionales. Devuelve… |
usps_track_package | Rastrea un paquete de USPS con Seguimiento 3.2. Devuelve trackingNumber, uniqueTrackingID, mailClass, status, statusCategory (por ejemplo.… |
usps_track_packages | Rastrea hasta 35 paquetes de USPS en una sola llamada con Seguimiento 3.2. Devuelve un resultado por número con trackingNumber, uniqueTrackingID… |
usps_register_tracking_notifications | Inscribe hasta 3 direcciones de correo electrónico para correos electrónicos de seguimiento de USPS sobre un paquete: actualizaciones de entrega esperadas, actividad de entrega o todas las actualizaciones. Necesita… |
usps_request_proof_of_delivery | Haz que USPS envíe por correo una carta de prueba de entrega (o un recibo electrónico de retorno) para un paquete entregado a hasta 3 destinatarios. Necesita el… |
usps_find_post_offices | Encuentra Oficinas de Correos y otros lugares de venta al por menor cerca de un código ZIP, una dirección o coordenadas, primero los más cercanos. Devuelve locations con… |
usps_find_dropoff_locations | Encuentra las instalaciones de entrada de destino donde puedes dejar el correo de Parcel Select, USPS Connect y Servicios de Paquete para un código ZIP de destino… |
usps_find_parcel_lockers | Encuentra Taquillas de Paquetes de USPS por código ZIP o por ciudad y estado. Devuelve una lista de taquillas con facilityID, locationName, locationAddress… |
usps_check_pickup_eligibility | Verifica si USPS ofrece recogida gratuita de Transportista en una dirección. Responde 200 con pickupAddress en formato estandarizado cuando la dirección es… |
usps_get_pickup | Obtiene una recogida programada de Transportista por número de confirmación. Devuelve confirmationNumber, pickupDate y carrierPickupRequest (dirección… |
usps_get_payment_account | Verifica una Cuenta de Pago Empresarial o permiso. Devuelve los detalles de la cuenta y, cuando se da amount, sufficientFunds (verdadero o falso)… |
usps_create_payment_authorization | Obtén el token de autorización de pago que necesita cada llamada de etiqueta: nombra tu negocio como PAYER y LABEL_OWNER con su CRID, ID de Mailer y… |
usps_create_label | Compra franqueo y crea una etiqueta de envío nacional, pagada desde la Cuenta de Pago Empresarial en el token de autorización de pago. Devuelve… |
usps_create_return_label | Crea una etiqueta de devolución nacional para que un cliente envíe un paquete de vuelta (to_address es tu dirección de devoluciones, from_address el del cliente).… |
usps_cancel_label | Cancela una etiqueta nacional no utilizada o solicita un reembolso de franqueo. Devuelve trackingNumber, status (CANCELED, o DISPUTED cuando se solicita un reembolso… |
usps_create_international_label | Compra franqueo y crea una etiqueta internacional con su formulario de aduanas (Servicio de Paquete Internacional de Primera Clase, Envío Prioritario Internacional… |
usps_cancel_international_label | Cancela una etiqueta internacional no utilizada o solicita un reembolso de franqueo. Devuelve el número de seguimiento, status (CANCELED o DISPUTED) y el… |
usps_schedule_pickup | Reserva una recogida gratuita de Transportista de USPS para paquetes en tu dirección (de lunes a sábado; solo el mismo día hasta las 2 a.m. hora central). Devuelve… |
usps_cancel_pickup | Cancela una recogida programada de Transportista por número de confirmación. Devuelve 200 cuando se cancela. Instalado desactivado: las cancelaciones permanecen con un… |
usps_create_scan_form | Crea un formulario SCAN (PS Form 5630) que vincula etiquetas a un código de barras, de modo que un solo escaneo en la aceptación registre cada paquete. Devuelve… |
Ejemplos de solicitudes
- "¿Dónde está el paquete de USPS 9400111899223197428490?"
- "¿Es 1600 Pennsylvania Ave NW, Washington DC 20500 una dirección válida, y cuál es su ZIP+4?"
- "Compara precios y fechas de entrega de USPS para una caja de 3 lb de 10001 a 94105 enviada mañana."
- "¿Cuánto cuesta un paquete de 2 lb a Toronto con USPS Priority Mail International?"
- "Encuentra Oficinas de Correos abiertas el sábado cerca del ZIP 60614."
Próximos pasos
¿Te ha sido útil esta guía?