Кратко
API Укрпошты для бизнес-клиентов в Украине: отслеживание отправлений, отправления и PDF-этикетки, расчеты внутренних цен, проверки маршрутов, клиенты и адреса, а также классификатор адресов с почтовыми отделениями и часами работы. Создание и удаление отправлений отключено. Токены контрагентов и держателей контрактов.
Пошаговая настройка
Подключи Ukrposhta к Microsoft Copilot за 2 минуты
Начни бесплатный пробный период в AnythingMCP Cloud, подключи Ukrposhta в пошаговой настройке и добавь свой MCP URL в Microsoft Copilot. Без кода и без собственного сервера.
Без банковской карты · 7 дней пробного периода · Есть вариант self-host
Попробуй спросить
Примеры промптов для Ukrposhta
Кликни по промпту — он скопируется. Вставь в Claude, ChatGPT, Cursor, Gemini, Copilot или OpenClaw и запусти через этот коннектор.
Claude — это AI, он может ошибаться. Проверяйте ответы.
💡 Нет установки? Используй cloud.anythingmcp.com напрямую. Войди в систему, нажми Connectors → Укрпошта, вставь свои учетные данные, создай ключ API MCP, и все готово. Никакого Docker, никакого
git clone, никакого локального сервера.
Укрпошта + Microsoft Copilot
API Укрпошты для бизнес-клиентов в Украине: отслеживание отправлений, отправления и PDF-этикетки, расчеты внутренних цен, проверки маршрутов, клиенты и адреса, а также классификатор адресов с почтовыми отделениями и часами работы. Создание и удаление отправлений отключено. Токены контрагентов и держателей контрактов.
Предварительные требования
Смотри полные инструкции по настройке, встроенные в коннектор (видно в магазине приложения, когда ты выбираешь коннектор). Необходимые переменные окружения для этого коннектора:
UKRPOSHTA_ECOM_BEARER, UKRPOSHTA_TRACKING_BEARER, UKRPOSHTA_COUNTERPARTY_TOKEN
Шаг 1 — Получи учетные данные
- Подпиши контракт на API с Укрпоштой (служба поддержки бизнес-клиентов, [email protected]). С контрактом ты получишь приложение с твоими производственными ключами.
- Скопируй PRODUCTION BEARER eCom в
UKRPOSHTA_ECOM_BEARER, PRODUCTION BEARER StatusTracking вUKRPOSHTA_TRACKING_BEARERи PROD_COUNTERPARTY TOKEN вUKRPOSHTA_COUNTERPARTY_TOKEN.
Ключи песочницы (SANDBOX ...) здесь не работают: этот коннектор обращается к производственному хосту. Токен eCom также открывает классификатор адресов и сервис этикеток; отслеживание имеет свой собственный токен; токен контрагента идентифицирует твой аккаунт при запросах о клиентах и отправлениях.
С чего начать: ukrposhta_track_shipment или ukrposhta_get_last_status с штрих-кодом. Для отправлений твоего аккаунта, ukrposhta_get_shipment_by_barcode или ukrposhta_list_sender_shipments с uuid клиента отправителя.
Отслеживание: ukrposhta_track_shipment (все события), ukrposhta_get_last_status, ukrposhta_get_last_statuses (до 50 штрих-кодов) и ukrposhta_get_shipment_route. Передай lang en для английских названий событий.
Отправления: ukrposhta_get_shipment, ukrposhta_get_shipment_by_barcode, ukrposhta_list_sender_shipments, ukrposhta_get_shipment_lifecycle, ukrposhta_list_shipment_groups, ukrposhta_list_group_shipments и ukrposhta_get_label (PDF). Перед отправкой, ukrposhta_check_route и ukrposhta_calculate_domestic_price (UAH, без скидок по твоему контракту).
Создание отправления следует порядку Укрпошты: ukrposhta_create_address для отправителя и получателя, ukrposhta_create_client для каждого (или используй их повторно: ukrposhta_get_client, ukrposhta_find_clients_by_phone, ukrposhta_get_address), затем ukrposhta_create_shipment, затем этикетка. ukrposhta_create_shipment и ukrposhta_delete_shipment отключены: созданное отправление оплачивается при сдаче, а удаленное не может быть восстановлено. Адреса и клиенты ничего не стоят.
Классификатор адресов: ukrposhta_search_regions, ukrposhta_search_districts, ukrposhta_search_cities, ukrposhta_search_streets, ukrposhta_get_house_postcode, ukrposhta_get_city_by_postcode, а для почтовых отделений ukrposhta_find_post_offices_by_postcode, ukrposhta_find_post_offices_near и ukrposhta_get_post_office_hours. Ответы приходят в виде списков Entries.Entry с именами полей в верхнем регистре; id — строки.
Единицы и подводные камни: вес в граммах, размеры в см, деньги в UAH. Типы доставки: W2W от почтового отделения к почтовому отделению, W2D до двери, D2W и D2D от двери. Почтовый индекс, помеченный как RESTRICTED_ACCESS, может быть только адресом отправителя или возврата. Статусы: CREATED (еще не сдано), REGISTERED, DELIVERING, IN_DEPARTMENT (ожидание в офисе), DELIVERED, RETURNING, RETURNED, CANCELLED, DELETED. Время — местное киевское время.
Шаг 2 — Установи адаптер
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
Шаг 3 — Добавь коннектор в Microsoft Copilot
URL вашего сервера: в AnythingMCP откройте MCP Servers → сервер, на котором находится этот коннектор, и скопируйте его URL (
https://cloud.anythingmcp.com/mcp/…). Используйте его везде, где в этом руководстве указаноYOUR_SERVER_ID.
Microsoft Copilot использует MCP-серверы через агентов, созданных в Copilot Studio: ты добавляешь AnythingMCP в агента как инструмент, а затем публикуешь агента в Microsoft 365 Copilot и Teams. Copilot Studio подключается из облака Microsoft по Streamable HTTP, который AnythingMCP поддерживает.
- В Copilot Studio открой своего агента (или создай нового), перейди в Tools и выбери Add a tool → New tool → Model Context Protocol.
- Укажи Server name (например,
AnythingMCP), Server description, которое объясняет, что делает коннектор, и Server URLhttps://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID. По описанию Copilot Studio решает, когда вызывать сервер. - В аутентификации выбери API key, установи Type в Header, укажи имя заголовка
X-API-Keyи нажми Create. - В окне Add tool выбери Create a new connection, вставь MCP API-ключ из AnythingMCP (MCP Servers → твой сервер → API keys) и нажми Add to agent.
- Проверь в панели Test агента: попроси о том, для чего нужны инструменты
Укрпошта. - Нажми Publish, затем Channels → Microsoft 365 and Microsoft Teams, оставь включённым Make agent available in Microsoft Copilot и нажми Add channel. See agent in Teams установит агента для тебя; в Microsoft 365 Copilot введи @ и выбери агента.
Хочешь, чтобы каждый входил под своей учётной записью? Вместо API-ключа выбери OAuth 2.0 → Dynamic discovery: каждый пользователь войдёт в AnythingMCP при первом вызове агентом.
Размещаешь сам? Используй публичный HTTPS-адрес своего экземпляра вместо https://cloud.anythingmcp.com. Copilot Studio подключается из облака Microsoft, поэтому localhost не подойдёт.
Доступные инструменты
| Инструмент | Что он делает |
|---|---|
ukrposhta_track_shipment | Полная история статусов одного отправления по штрих-коду: по шагам события, дата, индекс и название почтового отделения, код события и eventName (например… |
ukrposhta_get_last_status | Последний статус одного отправления по штрих-коду: дата, индекс и название почтового отделения, код события, eventName и eventReason. Только для чтения |
ukrposhta_get_last_statuses | Последний статус до 50 отправлений одновременно, плюс штрих-коды, которые Укрпошта не знает: по штрих-коду дата, почтовое отделение, код события и… |
ukrposhta_get_shipment_route | Откуда и куда путешествует отправление (страна и местность) по штрих-коду. Только для чтения |
ukrposhta_get_shipment | Прочитать одно отправление твоего аккаунта по uuid: штрих-код, тип, клиенты отправителя и получателя с адресами, deliveryType, посылки (вес… |
ukrposhta_get_shipment_by_barcode | Прочитать одно отправление твоего аккаунта по его штрих-коду (те же поля, что и у ukrposhta_get_shipment). Только для чтения |
ukrposhta_list_sender_shipments | Список отправлений, созданных для одного клиента-отправителя: uuid, штрих-код, получатель, deliveryType, посылки, цены и статус жизненного цикла. Только для чтения |
ukrposhta_get_shipment_lifecycle | Текущий статус одного отправления с eCom стороны: shipmentUuid, shipmentBarcode, статус (CREATED, REGISTERED, DELIVERING, IN_DEPARTMENT… |
ukrposhta_list_shipment_groups | Список групп отправлений (реестры для формы 103a) одного клиента: uuid, имя, тип, дата создания, флаг закрытия и количество отправлений.… |
ukrposhta_list_group_shipments | Список отправлений в одной группе отправлений: uuid, штрих-код, получатель, посылки, цены и статус жизненного цикла. Только для чтения |
ukrposhta_get_label | Скачать этикетку адреса (наклейку) отправления, которое ты создал, в виде PDF-файла: по умолчанию 100 x 100 мм или на листе A4 или A5. Печать… |
ukrposhta_calculate_domestic_price | Оценить цену отправления внутри Украины перед его созданием: deliveryPrice в UAH, rawDeliveryPrice, postPayDeliveryPrice… |
ukrposhta_check_route | Проверить, что Укрпошта доставляет между двумя почтовыми индексами: код (SUCCESS, когда доступно), описание и mrtps (где мобильный почтовый офис… |
ukrposhta_get_client | Прочитать одного клиента (отправителя или получателя) твоего аккаунта: uuid, тип (INDIVIDUAL, PRIVATE_ENTREPRENEUR, COMPANY), имя, firstName, lastName… |
ukrposhta_find_clients_by_phone | Найти клиентов твоего аккаунта по номеру телефона: uuid, имя, тип, адреса. Только для чтения |
ukrposhta_get_address | Прочитать адрес, созданный с помощью ukrposhta_create_address: id, почтовый индекс, регион, район, город, улица, номер дома, номер квартиры, страна… |
ukrposhta_create_address | Создать адрес для использования для клиента или отправления. Только почтовый индекс обязателен; добавь улицу и дом для доставки до двери. Бесплатно; ответы… |
ukrposhta_create_client | Создать клиента (отправителя или получателя) по адресу из ukrposhta_create_address. Физическим лицам и частным предпринимателям нужны first_name… |
ukrposhta_create_shipment | Создать внутреннее отправление от клиента-отправителя к клиенту-получателю. Оно получает штрих-код и цену, и оплачивается при сдаче в… |
ukrposhta_delete_shipment | Удалить отправление, которое все еще в статусе CREATED (еще не сдано). Не может быть отменено. Отключено |
ukrposhta_find_post_offices_by_postcode | Почтовые отделения, обслуживающие почтовый индекс: ID, PO_SHORT и PO_LONG (название), АДРЕС, ТЕЛЕФОН, TYPE_LONG, ШИРОТА, ДОЛГОТА, POSTTERMINAL… |
ukrposhta_find_post_offices_near | Почтовые отделения рядом с точкой, ближайшие первыми: ID, название, адрес, почтовый индекс, расстояние, координаты и тип. Только для чтения |
ukrposhta_get_post_office_hours | Часы работы почтового отделения по почтовому индексу: по рабочим дням время открытия и закрытия и перерывы. Только для чтения |
ukrposhta_get_city_by_postcode | Местность, район и регион почтового индекса с их id. Только для чтения |
ukrposhta_search_regions | Найти регионы (области) по части названия, на украинском или английском: REGION_ID, REGION_UA, REGION_EN, коды KOATUU и KATOTTG. Оставь оба… |
ukrposhta_search_districts | Найти районы области по названию: DISTRICT_ID, названия на UA и EN, регион. Только для чтения |
ukrposhta_search_cities | Найти местности по названию, при необходимости в пределах области и района: CITY_ID, названия на UA и EN, тип (город, село), район, область и… |
ukrposhta_search_streets | Найти улицы местности по названию: STREET_ID, названия на UA и EN, тип улицы. Только для чтения |
ukrposhta_get_house_postcode | Почтовый индекс дома на улице: номер дома и POSTCODE. Только для чтения |
Примеры подсказок
- "Где находится посылка Укрпошты 0503112345678?"
- "Покажи последний статус этих 10 штрих-кодов из отправки вчера."
- "Сколько стоит посылка весом 2 кг из Киева 01001 в Львов 79000?"
- "Какие почтовые отделения находятся рядом с почтовым индексом 65000, и когда они открыты в субботу?"
- "Скачать этикетку отправления 0503112345678."
Часто задаваемые вопросы
Откуда берутся ключи? Только из бизнес-контракта: Укрпошта отправляет производственный токен eCom, токен StatusTracking и токен контрагента в приложении к твоему API-контракту. Ключи песочницы здесь не работают.
Что это охватывает? Отслеживание, твои отправления и группы, PDF-этикетки, расчеты внутренних цен, проверки маршрутов, клиенты и адреса, а также классификатор адресов с регионами, местностями, улицами, почтовыми индексами и почтовыми отделениями с часами работы.
Какие инструменты установлены отключенными? ukrposhta_create_shipment и ukrposhta_delete_shipment. Включай их на странице коннектора только если ИИ должен создавать или удалять отправления.
Для какого Copilot это руководство? Для Microsoft 365 Copilot на работе — через агентов Copilot Studio. В приложении Microsoft Copilot для личных аккаунтов добавить свой MCP-сервер нельзя.
Что нужно? Рабочий аккаунт с доступом к Copilot Studio (лицензия или пробная версия), чтобы создать агента. Тем, кто будет пользоваться им в Microsoft 365 Copilot или Teams, нужен доступ к агенту: поделись им или попроси администратора опубликовать его для организации. Если в организации действуют политики данных для коннекторов Power Platform, они распространяются и на MCP-серверы.
Агент не вызывает инструменты. Проверь, что имя заголовка — ровно X-API-Key, а ключ относится к тому же MCP-серверу, что и URL, и сделай Server description конкретным: по нему Copilot Studio решает, когда вызывать сервер. После каждого изменения опубликуй агента заново; в открытом чате введи «start over», чтобы перейти на новую версию.
Следующие шаги
Это руководство помогло?