Кратко
API USPS для отправителей: проверяй адреса в США и ищи ZIP-коды, сравнивай внутренние и международные цены, получай дни доставки и варианты отправки, отслеживай посылки и находи почтовые отделения, пункты сдачи и почтовые шкафчики. Этикетки, возвраты, заборы и формы SCAN включены, но отключены. Ключ потребителя и секрет приложения в Портале по подключению клиентов USPS.
Пошаговая настройка
Подключи USPS к Claude, ChatGPT или Copilot за 2 минуты
Начни бесплатный пробный период в AnythingMCP Cloud, подключи USPS в пошаговой настройке и добавь свой MCP URL в своего ИИ-ассистента. Без кода и без собственного сервера.
Без банковской карты · 7 дней пробного периода · Есть вариант self-host
Попробуй спросить
Примеры промптов для USPS
Кликни по промпту — он скопируется. Вставь в Claude, ChatGPT, Cursor, Gemini, Copilot или OpenClaw и запусти через этот коннектор.
Claude — это AI, он может ошибаться. Проверяйте ответы.
💡 Нет установки? Используй cloud.anythingmcp.com напрямую. Войди в систему, нажми Connectors → USPS, вставь свои учетные данные, создай ключ API MCP, и все готово. Никакого Docker, никакого
git clone, никакого локального сервера.
USPS
API USPS для отправителей: проверяй адреса в США и ищи ZIP-коды, сравнивай внутренние и международные цены, получай дни доставки и варианты отправки, отслеживай посылки и находи почтовые отделения, пункты сдачи и почтовые шкафчики. Этикетки, возвраты, заборы и формы SCAN включены, но отключены. Ключ потребителя и секрет приложения в Портале по подключению клиентов USPS.
Настройка
Настройка занимает около 15 минут.
- Открой Портал по подключению клиентов USPS по адресу https://cop.usps.com/cop-navigator?wf=API и войди в свою учетную запись USPS Business Account или создай ее там. Портал подготавливает учетную запись для API USPS.
- Выбери My Apps в верхней части портала и добавь приложение.
- Открой приложение. В Credentials скопируй Consumer Key в
USPS_CLIENT_IDи Consumer Secret вUSPS_CLIENT_SECRET. - Выбери адрес API в
USPS_API_HOST: продакшнhttps://apis.usps.comили Тестовую среду для отправителейhttps://apis-tem.usps.com. Оба используют одни и те же продакшн учетные данные. Этикетки, созданные на тестовом хосте, имеют водяной знак и никогда не тарифицируются. USPS публикует тестовый хост для каждого API, кроме отслеживания, поэтому используй продакшн, когда в основном отслеживаешь. - По желанию, для этикеток и контрактных цен: твой CRID, Mailer ID и номер счета Enterprise Payment Account в
USPS_CRID,USPS_MIDиUSPS_EPS_ACCOUNT_NUMBER. Их можно найти у администратора бизнес-услуг твоей учетной записи Business Customer Gateway.
Коннектор отправляет ключ потребителя и секрет на /oauth2/v3/token на выбранном хосте (учетные данные клиента) и получает токен доступа, действительный примерно 8 часов, который он повторно использует и обновляет самостоятельно.
Что может использовать новое приложение: каждое приложение начинается с продукта по умолчанию USPS: OAuth, Адреса, Внутренние цены, Международные цены, Местоположения, Стандарты обслуживания, Варианты отправки и Отслеживание. Адреса, цены, дни доставки, варианты отправки, отслеживание, почтовые отделения и пункты сдачи, таким образом, работают сразу. Забор курьером, Платежи, Этикетки, Международные этикетки и формы SCAN требуют одобрения USPS: запроси их с помощью запроса на обслуживание API USPS на странице Email Us (https://emailus.usps.com/s/usps-APIs). API Этикеток также требуют регистрации в USPS Ship (этикетки для отправки и возврата) и Enterprise Payment Account (EPS), который оплачивает почтовые расходы. Почтовые шкафчики (usps_find_parcel_lockers) и международный стандарт обслуживания (usps_get_international_service_standard) имеют свои собственные области; если они отвечают 403, запроси их у USPS тем же способом.
С чего начать: usps_get_city_state с ZIP-кодом подтверждает соединение. Для запроса usps_search_shipping_options возвращает цены и даты доставки для каждой услуги за один вызов; usps_search_domestic_prices и usps_search_international_prices дают разбивку цен с дополнительными услугами.
Адреса: usps_validate_address стандартизирует адрес в США и возвращает ZIP+4, DPVConfirmation (Y подтвержден, D отсутствует вторичный номер, S вторичный номер не подтвержден, N не подтвержден), business (Y или N) и vacant. usps_get_zip_code находит ZIP-код улицы в городе и штате, usps_get_city_state — город и штат ZIP-кода. Штаты — это двухбуквенные коды; только адреса США (включая территории и военные адреса) охватываются.
Цены: посылки взвешиваются в фунтах и измеряются в дюймах; письма, плоские конверты и открытки взвешиваются в унциях. price_type COMMERCIAL — это то, что ты платишь за этикетки, купленные онлайн, RETAIL — цена на стойке почтового отделения, CONTRACT требует account_type и account_number. usps_search_domestic_prices возвращает rateOptions с totalBasePrice, totalPrice и дополнительными услугами; usps_list_domestic_prices перечисляет каждый подходящий продукт с его SKU, rateIndicator и processingCategory, значения, необходимые для запроса этикетки. usps_search_letter_prices оценивает письма первого класса. За границей: usps_search_international_prices (по желанию с пошлинами и налогами на каждый товар), usps_list_international_prices и usps_search_international_letter_prices. Даты отправки могут быть сегодня или до 7 дней вперед. Суммы указаны в долларах США. USPS_GROUND_ADVANTAGE заменил службу первого класса и розничную наземную доставку.
Дни доставки: usps_get_delivery_estimates дает запланированную дату доставки для дня отправки с временем окончания приема (cutOffTime, HHMM местное); usps_get_service_standards — стандартное количество дней для каждого класса почты; usps_get_international_service_standard — предложение, например, Ожидаемая доставка через 5-9 рабочих дней. Стандарт обслуживания — это цель, а не гарантия.
Отслеживание: usps_track_package для одного номера, usps_track_packages для до 35 сразу. Оба используют отслеживание 3.2; устаревший API отслеживания 3.0 будет закрыт 31 июля 2027 года. Ответ содержит statusCategory, statusSummary, trackingEvents (eventTimestamp в местном времени события, GMTTimestamp в UTC), deliveryDateExpectation и uniqueTrackingID. Пакет отвечает HTTP 207, когда некоторые номера не проходят, и каждый неудачный номер имеет свой собственный error. usps_register_tracking_notifications подписывает до 3 адресов электронной почты для отслеживания и usps_request_proof_of_delivery отправляет письмо с подтверждением доставки по электронной почте; оба требуют uniqueTrackingID из ответа отслеживания, отправляют электронную почту от USPS и ничего не стоят.
Местоположения: usps_find_post_offices ищет по ZIP-коду, городу и штату, адресу или координатам (радиус в милях, по умолчанию 20) и перечисляет часы работы каждой службы; usps_find_dropoff_locations перечисляет пункты сдачи для Parcel Select, USPS Connect и Package Services по ZIP-коду назначения; usps_find_parcel_lockers находит почтовые шкафчики.
Заборы: usps_check_pickup_eligibility и usps_get_pickup только для чтения. usps_schedule_pickup бронирует бесплатный забор курьером (с понедельника по субботу), а usps_cancel_pickup отменяет его; оба отключены. Забор нельзя изменить здесь: отмени его и забронируй новый.
Этикетки (отключены): каждый вызов этикетки требует токен авторизации платежа. usps_create_payment_authorization с твоим CRID, Mailer ID и EPS-аккаунтом возвращает paymentAuthorizationToken; передай его в usps_create_label, usps_create_return_label, usps_create_international_label, usps_cancel_label или usps_cancel_international_label. Этикетки возвращаются в формате JSON: labelMetadata с номером отслеживания и почтовыми расходами, и labelImage в base64 (по умолчанию PDF 4x6). Создание этикетки покупает почтовые расходы с EPS-аккаунта. Отмена отвечает CANCELED или DISPUTED с disputeId, когда USPS открыл запрос на возврат. usps_get_payment_account читает аккаунт и, с amount, сообщает, достаточно ли средств. usps_create_scan_form объединяет множество этикеток в одну форму PS Form 5630 для одного сканирования при приеме. Включай эти инструменты только после одобрения USPS API Этикеток и сначала попробуй их на тестовом хосте.
Ошибки: сбои приходят как error с code, message и списком errors (title, detail, source.parameter). 400 указывает на неправильное поле; 401 означает неправильные учетные данные или истекший токен; 403 означает, что у приложения нет этого API (он вне продукта по умолчанию); 404 означает, что USPS ничего не нашел, например, неизвестный номер отслеживания.
Лимиты: каждое приложение имеет квоту вызовов в час; 429 означает, что она исчерпана до следующего часа. USPS увеличивает квоту по запросу через страницу Email Us. Даты в формате ГГГГ-ММ-ДД.
Предварительные требования: USPS_CLIENT_ID, USPS_CLIENT_SECRET, USPS_API_HOST
Установи коннектор локально
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
Открой http://localhost:3000/connectors/store, выбери USPS и вставь переменные окружения, указанные в предварительных требованиях.
Доступные инструменты
| Инструмент | Что он делает |
|---|---|
usps_validate_address | Проверяет и стандартизирует один адрес в США. Возвращает address в стандартной форме USPS (streetAddress, city, state, ZIPCode, ZIPPlus4)… |
usps_get_city_state | Ищет город и штат по 5-значному ZIP-коду. Возвращает city (в заглавных буквах), state (две буквы) и ZIPCode. Дешевый вызов, используется как… |
usps_get_zip_code | Находит ZIP-код и ZIP+4 для адреса улицы в городе и штате. Возвращает address со стандартизированной улицей, city, state… |
usps_search_domestic_prices | Оценивает внутреннюю посылку по классам почты, включая дополнительные услуги. Возвращает rateOptions, по одному на каждый подходящий продукт, каждый с… |
usps_list_domestic_prices | Перечисляет каждый продукт, на который подходит внутренняя посылка, с его базовой ценой и без дополнительных услуг. Возвращает rateOptions с… |
usps_search_letter_prices | Оценивает письмо первого класса, плоский конверт (большой конверт) или открытку, отправленную внутри США. Возвращает totalBasePrice и rates (SKU… |
usps_search_international_prices | Оценивает исходящую международную посылку, включая дополнительные услуги и, по запросу, пошлины и налоги на каждый товар. Возвращает rateOptions, по одному на… |
usps_list_international_prices | Перечисляет каждый международный продукт, на который подходит исходящая посылка, с базовыми ценами и без дополнительных услуг. Возвращает rateOptions с… |
usps_search_international_letter_prices | Оценивает международное письмо первого класса, плоский конверт или открытку. Возвращает totalBasePrice, rates (SKU, description, price, fees)… |
usps_get_delivery_estimates | Оценивает дату доставки почты, принятой в определенный день. Возвращает список, по одной записи на класс почты, с serviceStandard (дни)… |
usps_get_service_standards | Получает стандартное количество дней доставки между двумя ZIP-кодами по классам почты. Возвращает список с mailClass, days… |
usps_get_international_service_standard | Получает ожидаемое время доставки международного класса почты в страну. Возвращает countryCode, mailClass и… |
usps_search_shipping_options | Сравнивает все способы отправки одной посылки за один вызов: цены и обязательства по доставке вместе, внутренние или международные. Возвращает… |
usps_track_package | Отслеживает одну посылку USPS с использованием отслеживания 3.2. Возвращает trackingNumber, uniqueTrackingID, mailClass, status, statusCategory (например,… |
usps_track_packages | Отслеживает до 35 посылок USPS за один вызов с использованием отслеживания 3.2. Возвращает один результат на номер с trackingNumber, uniqueTrackingID… |
usps_register_tracking_notifications | Подписывает до 3 адресов электронной почты для получения уведомлений об отслеживании USPS о одной посылке: ожидаемые обновления доставки, активность доставки или все обновления. Требует… |
usps_request_proof_of_delivery | Отправляет по электронной почте письмо с подтверждением доставки (или электронный возвратный квитанцию) для доставленной посылки до 3 получателей. Требует… |
usps_find_post_offices | Находит почтовые отделения и другие розничные точки рядом с ZIP-кодом, адресом или координатами, ближайшие первыми. Возвращает locations с… |
usps_find_dropoff_locations | Находит пункты сдачи, где можно сдать почту Parcel Select, USPS Connect и Package Services для ZIP-кода назначения… |
usps_find_parcel_lockers | Находит почтовые шкафчики USPS по ZIP-коду или по городу и штату. Возвращает список шкафчиков с facilityID, locationName, locationAddress… |
usps_check_pickup_eligibility | Проверяет, предлагает ли USPS бесплатный забор курьером по адресу. Отвечает 200 с pickupAddress в стандартизированной форме, когда адрес… |
usps_get_pickup | Получает запланированный забор курьером по номеру подтверждения. Возвращает confirmationNumber, pickupDate и carrierPickupRequest (адрес… |
usps_get_payment_account | Проверяет учетную запись Enterprise Payment Account или разрешение. Возвращает детали аккаунта и, когда указано amount, sufficientFunds (true или false)… |
usps_create_payment_authorization | Получает токен авторизации платежа, который требуется для каждого вызова этикетки: называет твой бизнес как PAYER и LABEL_OWNER с его CRID, Mailer ID и… |
usps_create_label | Покупает почтовые расходы и создает этикетку для внутренней отправки, оплачиваемую с Enterprise Payment Account в токене авторизации платежа. Возвращает… |
usps_create_return_label | Создает этикетку для возврата для клиента, чтобы отправить посылку обратно (to_address — это твой адрес возврата, from_address — адрес клиента).… |
usps_cancel_label | Отменяет неиспользуемую внутреннюю этикетку или запрашивает возврат почтовых расходов. Возвращает trackingNumber, status (CANCELED или DISPUTED, когда запрос на возврат… |
usps_create_international_label | Покупает почтовые расходы и создает международную этикетку с ее таможенной формой (First-Class Package International Service, Priority Mail International… |
usps_cancel_international_label | Отменяет неиспользуемую международную этикетку или запрашивает возврат почтовых расходов. Возвращает номер отслеживания, status (CANCELED или DISPUTED) и… |
usps_schedule_pickup | Бронирует бесплатный забор курьером USPS для посылок по твоему адресу (с понедельника по субботу; только в тот же день до 2 часов ночи по центральному времени). Возвращает… |
usps_cancel_pickup | Отменяет запланированный забор курьером по номеру подтверждения. Возвращает 200 при отмене. Установлено отключенным: отмены остаются с… |
usps_create_scan_form | Создает форму SCAN (PS Form 5630), которая связывает этикетки с одним штрих-кодом, так что одно сканирование при приеме фиксирует каждую посылку. Возвращает… |
Примеры запросов
- "Где посылка USPS 9400111899223197428490?"
- "Является ли 1600 Pennsylvania Ave NW, Washington DC 20500 действительным адресом, и какой у него ZIP+4?"
- "Сравни цены и даты доставки USPS для коробки весом 3 фунта из 10001 в 94105, отправленной завтра."
- "Сколько стоит посылка весом 2 фунта в Торонто с USPS Priority Mail International?"
- "Найди почтовые отделения, открытые в субботу, рядом с ZIP 60614."
Следующие шаги
Это руководство помогло?