In breve
API USPS per spedizionieri: valida indirizzi statunitensi e cerca codici ZIP, confronta prezzi nazionali e internazionali, ottieni giorni di consegna e opzioni di spedizione, traccia pacchi e trova Uffici Postali, punti di consegna e Parcel Lockers. Etichette, rimborsi, ritiri e SCAN Forms sono inclusi ma disattivati. Chiave e Segreto del consumatore di un'app nel Portale di Onboarding Clienti USPS.
Configurazione guidata
Collega USPS a Claude, ChatGPT o Copilot in 2 minuti
Avvia la prova gratuita su AnythingMCP Cloud, collega USPS con la configurazione guidata e aggiungi il tuo URL MCP al tuo assistente AI. Senza codice e senza server da gestire.
Nessuna carta di credito · 7 giorni di prova · Alternativa self-host disponibile
Prova a chiedere
Prompt di esempio per USPS
Clicca su un prompt per copiarlo. Incollalo in Claude, ChatGPT, Cursor, Gemini, Copilot o OpenClaw per eseguirlo contro questo connettore.
Claude è un'AI e può sbagliare. Verifica sempre le risposte.
💡 Nessuna installazione? Usa direttamente cloud.anythingmcp.com. Accedi, clicca su Connettori → USPS, incolla le tue credenziali, crea una chiave API MCP e hai finito. Niente Docker, niente
git clone, niente server locale.
USPS
API USPS per spedizionieri: valida indirizzi statunitensi e cerca codici ZIP, confronta prezzi nazionali e internazionali, ottieni giorni di consegna e opzioni di spedizione, traccia pacchi e trova Uffici Postali, punti di consegna e Parcel Lockers. Etichette, rimborsi, ritiri e SCAN Forms sono inclusi ma disattivati. Chiave e Segreto del consumatore di un'app nel Portale di Onboarding Clienti USPS.
Configurazione
La configurazione richiede circa 15 minuti.
- Apri il Portale di Onboarding Clienti USPS su https://cop.usps.com/cop-navigator?wf=API e accedi con il tuo Account Business USPS, oppure creane uno lì. Il portale prepara l'account per le API USPS.
- Seleziona Le mie app in cima al portale e aggiungi un'app.
- Apri l'app. In Credenziali copia la Chiave del Consumatore in
USPS_CLIENT_IDe il Segreto del Consumatore inUSPS_CLIENT_SECRET. - Scegli l'indirizzo API in
USPS_API_HOST: produzionehttps://apis.usps.com, oppure l'Ambiente di Test per Speditorihttps://apis-tem.usps.com. Entrambi utilizzano le stesse credenziali di produzione. Le etichette create sull'host di test sono contrassegnate e non vengono mai addebitate. USPS pubblica l'host di test per ogni API tranne Tracciamento, quindi mantieni la produzione quando tracci principalmente. - Facoltativo, per etichette e prezzi contrattuali: il tuo CRID, ID Speditore e numero dell'Account di Pagamento Aziendale in
USPS_CRID,USPS_MIDeUSPS_EPS_ACCOUNT_NUMBER. L'Amministratore del Servizio Aziendale del tuo account Gateway Clienti Aziendali li ha.
Il connettore invia la Chiave e il Segreto del Consumatore a /oauth2/v3/token sull'host scelto (credenziali client) e ottiene un token bearer valido per circa 8 ore, che riutilizza e rinnova autonomamente.
Cosa può utilizzare una nuova app: ogni app inizia con il prodotto predefinito USPS: OAuth, Indirizzi, Prezzi Nazionali, Prezzi Internazionali, Località, Standard di Servizio, Opzioni di Spedizione e Tracciamento. Indirizzi, prezzi, giorni di consegna, opzioni di spedizione, tracciamento, Uffici Postali e località di consegna funzionano quindi immediatamente. Ritiro del Corriere, Pagamenti, Etichette, Etichette Internazionali e SCAN Forms necessitano dell'approvazione USPS: richiedili con una richiesta di servizio API USPS nella pagina Contattaci (https://emailus.usps.com/s/usps-APIs). Le API delle Etichette necessitano anche dell'iscrizione a USPS Ship (etichette di spedizione e di ritorno) e di un Account di Pagamento Aziendale (EPS) che paga il porto. I locker per pacchi (usps_find_parcel_lockers) e lo standard di servizio internazionale (usps_get_international_service_standard) hanno ambiti propri; se rispondono 403, chiedi a USPS per loro nello stesso modo.
Da dove iniziare: usps_get_city_state con un codice ZIP prova la connessione. Per un preventivo, usps_search_shipping_options restituisce prezzi e date di consegna per ogni servizio in una sola chiamata; usps_search_domestic_prices e usps_search_international_prices forniscono il dettaglio dei prezzi con servizi extra.
Indirizzi: usps_validate_address standardizza un indirizzo statunitense e restituisce il ZIP+4, DPVConfirmation (Y confermato, D numero secondario mancante, S numero secondario non confermato, N non confermato), business (Y o N) e vacant. usps_get_zip_code trova il codice ZIP di una strada in una città e stato, usps_get_city_state la città e lo stato di un codice ZIP. Gli stati sono codici di due lettere; solo gli indirizzi statunitensi (inclusi territori e indirizzi militari) sono coperti.
Prezzi: i pacchi sono pesati in libbre e misurati in pollici; lettere, plichi e cartoline sono pesati in once. price_type COMMERCIALE è ciò che paghi per le etichette acquistate online, RETAIL è il prezzo al banco dell'Ufficio Postale, CONTRATTO necessita di account_type e account_number. usps_search_domestic_prices restituisce rateOptions con totalBasePrice, totalPrice e i servizi extra; usps_list_domestic_prices elenca ogni prodotto idoneo con il suo SKU, rateIndicator e processingCategory, i valori necessari per una richiesta di etichetta. usps_search_letter_prices prezza le lettere di First-Class Mail, plichi e cartoline. All'estero: usps_search_international_prices (opzionalmente con dazi e tasse per articolo), usps_list_international_prices e usps_search_international_letter_prices. Le date di invio possono essere oggi fino a 7 giorni avanti. Gli importi sono in dollari statunitensi. USPS_GROUND_ADVANTAGE ha sostituito il servizio di pacchetti di First-Class e Retail Ground.
Giorni di consegna: usps_get_delivery_estimates fornisce la data di consegna programmata per un giorno di invio, con l'orario di scadenza per l'accettazione (cutOffTime, HHMM locale); usps_get_service_standards il numero standard di giorni per classe di posta; usps_get_international_service_standard una frase come "Consegna stimata in 5-9 giorni lavorativi". Uno standard di servizio è un obiettivo, non una garanzia.
Tracciamento: usps_track_package per un numero, usps_track_packages per un massimo di 35 alla volta. Entrambi utilizzano il Tracciamento 3.2; l'API di Tracciamento 3.0 legacy andrà in pensione il 31 luglio 2027. La risposta ha statusCategory, statusSummary, trackingEvents (eventTimestamp nell'ora locale dell'evento, GMTTimestamp in UTC), deliveryDateExpectation e uniqueTrackingID. Un batch risponde HTTP 207 quando alcuni numeri falliscono, e ogni numero fallito porta il proprio error. usps_register_tracking_notifications iscrive fino a 3 indirizzi email per le email di tracciamento e usps_request_proof_of_delivery ha una lettera di prova di consegna inviata via email; entrambi necessitano del uniqueTrackingID di una risposta di tracciamento, inviano email da USPS e non costano nulla.
Località: usps_find_post_offices cerca per codice ZIP, città e stato, indirizzo o coordinate (raggio in miglia, 20 di default) e elenca gli orari di ciascun servizio; usps_find_dropoff_locations elenca le strutture di ingresso di destinazione per Parcel Select, USPS Connect e servizi di pacchetti per un codice ZIP di destinazione; usps_find_parcel_lockers trova i Parcel Lockers.
Ritiri: usps_check_pickup_eligibility e usps_get_pickup leggono solo. usps_schedule_pickup prenota il ritiro gratuito del Corriere (da lunedì a sabato) e usps_cancel_pickup annulla uno; entrambi sono disattivati. Un ritiro non può essere modificato qui: annullalo e prenota uno nuovo.
Etichette (disattivate): ogni chiamata di etichetta necessita di un token di autorizzazione al pagamento. usps_create_payment_authorization con il tuo CRID, ID Speditore e account EPS restituisce paymentAuthorizationToken; passalo a usps_create_label, usps_create_return_label, usps_create_international_label, usps_cancel_label o usps_cancel_international_label. Le etichette tornano come JSON: labelMetadata con il numero di tracciamento e il porto, e labelImage in base64 (un PDF 4x6 di default). Creare un'etichetta acquista il porto dall'account EPS. Un annullamento risponde CANCELED, o DISPUTED con un disputeId quando USPS ha aperto una richiesta di rimborso. usps_get_payment_account legge l'account e, con amount, indica se i fondi sono sufficienti. usps_create_scan_form mette molte etichette su un unico PS Form 5630 per una singola scansione di accettazione. Attiva questi strumenti solo dopo che USPS ha approvato le API delle Etichette e prova prima su l'host di test.
Errori: i fallimenti arrivano come error con code, message e un elenco errors (title, detail, source.parameter). 400 indica il campo errato; 401 significa credenziali errate o token scaduto; 403 significa che l'app non ha quell'API (è al di fuori del prodotto predefinito); 404 significa che USPS non ha trovato nulla, ad esempio un numero di tracciamento sconosciuto.
Limiti: ogni app ha una quota di chiamate per ora; un 429 significa che è esaurita fino alla prossima ora. USPS aumenta la quota su richiesta tramite la pagina Contattaci. Le date sono nel formato YYYY-MM-DD.
Prerequisiti: USPS_CLIENT_ID, USPS_CLIENT_SECRET, USPS_API_HOST
Installa il connettore 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
Apri http://localhost:3000/connectors/store, scegli USPS e incolla le variabili d'ambiente elencate sotto Prerequisiti.
Strumenti disponibili
| Strumento | Cosa fa |
|---|---|
usps_validate_address | Valida e standardizza un indirizzo statunitense. Restituisce address in formato standard USPS (streetAddress, city, state, ZIPCode, ZIPPlus4)… |
usps_get_city_state | Cerca la città e lo stato di un codice ZIP a 5 cifre. Restituisce city (in maiuscolo), state (due lettere) e ZIPCode. Chiamata economica, usata come… |
usps_get_zip_code | Trova il codice ZIP e il ZIP+4 di un indirizzo stradale in una città e stato. Restituisce address con la strada standardizzata, city, state… |
usps_search_domestic_prices | Prezzo di un pacco nazionale attraverso le classi di posta, servizi extra inclusi. Restituisce rateOptions, uno per prodotto idoneo, ciascuno con… |
usps_list_domestic_prices | Elenca ogni prodotto per cui un pacco nazionale è idoneo, con il suo prezzo base e senza servizi extra. Restituisce rateOptions con… |
usps_search_letter_prices | Prezzo di una lettera di First-Class Mail, plico (busta grande) o cartolina inviata all'interno degli Stati Uniti. Restituisce totalBasePrice e rates (SKU… |
usps_search_international_prices | Prezzo di un pacco internazionale in uscita, servizi extra inclusi e, su richiesta, dazi e tasse per articolo. Restituisce rateOptions, uno per… |
usps_list_international_prices | Elenca ogni prodotto internazionale per cui un pacco in uscita è idoneo, con prezzi base e senza servizi extra. Restituisce rateOptions con… |
usps_search_international_letter_prices | Prezzo di una lettera internazionale di First-Class Mail, plico o cartolina. Restituisce totalBasePrice, rates (SKU, description, price, fees)… |
usps_get_delivery_estimates | Stima la data di consegna della posta accettata in un dato giorno. Restituisce un elenco, un'entrata per classe di posta, con serviceStandard (giorni)… |
usps_get_service_standards | Ottieni il numero standard di giorni di consegna tra due codici ZIP per classe di posta. Restituisce un elenco con mailClass, days… |
usps_get_international_service_standard | Ottieni il tempo di consegna previsto di una classe di posta internazionale verso un paese. Restituisce countryCode, mailClass e… |
usps_search_shipping_options | Confronta ogni modo di spedire un pacco in una sola chiamata: prezzi e impegni di consegna insieme, nazionali o internazionali. Restituisce… |
usps_track_package | Traccia un pacco USPS con Tracciamento 3.2. Restituisce trackingNumber, uniqueTrackingID, mailClass, status, statusCategory (ad es.… |
usps_track_packages | Traccia fino a 35 pacchi USPS in una chiamata con Tracciamento 3.2. Restituisce un risultato per numero con trackingNumber, uniqueTrackingID… |
usps_register_tracking_notifications | Iscriviti a 3 indirizzi email per le email di tracciamento USPS riguardanti un pacco: aggiornamenti sulla consegna prevista, attività di consegna o tutti gli aggiornamenti. Necessita… |
usps_request_proof_of_delivery | Fai inviare da USPS una lettera di prova di consegna (o una ricevuta elettronica di ritorno) per un pacco consegnato a un massimo di 3 destinatari. Necessita il… |
usps_find_post_offices | Trova Uffici Postali e altre località di vendita al dettaglio vicino a un codice ZIP, un indirizzo o coordinate, le più vicine per prime. Restituisce locations con… |
usps_find_dropoff_locations | Trova le strutture di ingresso di destinazione dove puoi consegnare la posta per Parcel Select, USPS Connect e servizi di pacchetti per un codice ZIP di destinazione… |
usps_find_parcel_lockers | Trova i Parcel Lockers USPS per codice ZIP o per città e stato. Restituisce un elenco di locker con facilityID, locationName, locationAddress… |
usps_check_pickup_eligibility | Controlla se USPS offre il ritiro gratuito del Corriere a un indirizzo. Risponde 200 con pickupAddress in formato standardizzato quando l'indirizzo è… |
usps_get_pickup | Ottieni un ritiro programmato del Corriere tramite numero di conferma. Restituisce confirmationNumber, pickupDate e carrierPickupRequest (indirizzo… |
usps_get_payment_account | Controlla un Account di Pagamento Aziendale o permesso. Restituisce i dettagli dell'account e, quando amount è fornito, sufficientFunds (true o false)… |
usps_create_payment_authorization | Ottieni il token di autorizzazione al pagamento di cui ogni chiamata di etichetta ha bisogno: nomina la tua azienda come PAYER e LABEL_OWNER con il suo CRID, ID Speditore e… |
usps_create_label | Acquista il porto e crea un'etichetta di spedizione nazionale, pagata dall'Account di Pagamento Aziendale nel token di autorizzazione al pagamento. Restituisce… |
usps_create_return_label | Crea un'etichetta di ritorno nazionale per un cliente per restituire un pacco (to_address è il tuo indirizzo di ritorno, from_address il cliente).… |
usps_cancel_label | Annulla un'etichetta nazionale non utilizzata o richiedi un rimborso del porto. Restituisce trackingNumber, status (CANCELED, o DISPUTED quando una richiesta di rimborso… |
usps_create_international_label | Acquista il porto e crea un'etichetta internazionale con il suo modulo doganale (First-Class Package International Service, Priority Mail International… |
usps_cancel_international_label | Annulla un'etichetta internazionale non utilizzata o richiedi un rimborso del porto. Restituisce il numero di tracciamento, status (CANCELED o DISPUTED) e il… |
usps_schedule_pickup | Prenota un ritiro gratuito del Corriere USPS per pacchi al tuo indirizzo (da lunedì a sabato; solo per lo stesso giorno fino alle 2 del mattino ora centrale). Restituisce… |
usps_cancel_pickup | Annulla un ritiro programmato del Corriere tramite numero di conferma. Restituisce 200 quando annullato. Installato disattivato: le cancellazioni rimangono con un… |
usps_create_scan_form | Crea un modulo SCAN (PS Form 5630) che collega le etichette a un codice a barre, così una singola scansione all'accettazione registra ogni pacco. Restituisce… |
Esempi di richieste
- "Dove si trova il pacco USPS 9400111899223197428490?"
- "1600 Pennsylvania Ave NW, Washington DC 20500 è un indirizzo valido, e qual è il suo ZIP+4?"
- "Confronta i prezzi USPS e le date di consegna per una scatola da 3 lb da 10001 a 94105 spedita domani."
- "Quanto costa un pacco da 2 lb per Toronto con USPS Priority Mail International?"
- "Trova Uffici Postali aperti sabato vicino al codice ZIP 60614."
Prossimi passi
Questa guida ti è stata utile?