Розбір API Укрпошти

1. Що це за API — і чого в ньому немає

Твердження. «API Укрпошти» — це не один сервіс, а два окремі, і в комплекті до них немає готового веб-кабінету B2B-відправника.

Факт. Публічне API складається з двох незалежних сервісів: eCom (створення й ведення відправлень, групи-реєстри, друковані форми) і StatusTracking (відстеження статусів) — у кожного власний токен. Авторизація eCom двотокенна: заголовок Authorization: Bearer {eCom} плюс query-параметр ?token={контрагента}. StatusTracking має окремий власний Bearer. Базові URL eCom:

Середовище	Базовий URL eCom
Production	https://www.ukrposhta.ua/ecom/0.0.1
Sandbox	https://dev.ukrposhta.ua/ecom/0.0.1

Джерело. Модель авторизації та базові URL — публічна документація eCom API Укрпошти (специфікація v0.0.1). Відсутність кабінету — єдине твердження на цій сторінці, яке спирається на невдалий пошук, а не на замір чи на текст специфікації, і подане воно як є: станом на 10.08.2026 у публічній документації Укрпошти інтерфейсу для потокового відправлення не описано, а знайти його нам не вдалося. Це негативний висновок із пошуку, а не доведена властивість чужої інфраструктури, і так само на дату: Укрпошта може випустити такий кабінет будь-коли.

2. Міфи про адреси кабінету

Твердження. Кабінет B2B-відправника не шукають за «красивою» адресою на кшталт kabinet.ukrposhta.ua — такі імена не резолвяться, а ok.ukrposhta.ua — це зовсім інше.

Факт. У мережі часто шукають кабінет за вгаданими іменами — kabinet.ukrposhta.ua, cabinet.ukrposhta.ua (те саме, але з латинською c) чи ecom.ukrposhta.ua. На 10–11.08.2026 таких хостів у Укрпошти немає: усі три імена віддають NXDOMAIN. Що існує:

Адреса	Що це насправді
ok.ukrposhta.ua	Офіційний особистий кабінет: відстежити свою посилку, оплатити зберігання, звернутися в підтримку як приватна особа чи разовий відправник. Це не B2B-інструмент для потокових відправлень.
www.ukrposhta.ua/ecom/0.0.1	Продакшен-хост eCom API (не веб-сторінка, а програмний інтерфейс).
dev.ukrposhta.ua/ecom/0.0.1	Пісочниця (sandbox) того ж eCom API.

Тобто «кабінет відправника» — це не окремий хост Укрпошти, а надбудова над її API. Детальніше про різницю між особистим кабінетом ok.ukrposhta.ua і кабінетом B2B-відправника — на сторінці «Кабінет відправника».

Джерело. Призначення ok.ukrposhta.ua — публічно описані можливості особистого кабінету Укрпошти; базові хости API — специфікація eCom API. Неіснування вгаданих імен — замір DNS 10.08.2026, 19:22 UTC, публічний резолвер 8.8.8.8: kabinet.ukrposhta.ua і ecom.ukrposhta.ua — NXDOMAIN, тоді як ok.ukrposhta.ua і www.ukrposhta.ua у тому ж прогоні резолвляться на Akamai. Варіант із латинською c (cabinet.ukrposhta.ua) доміряно тим самим резолвером окремо — 10.08.2026, 21:59 UTC, теж NXDOMAIN. Це замір на дату, а не вічна властивість: Укрпошта може завести такий хост будь-коли.

3. Ключі: скільки їх насправді

Твердження. Усього в моделі авторизації чотири різні сутності, але обов'язкові з них лише дві — і дві назви в документації означають те саме.

Сутність	Обов'язковість	Де живе	Навіщо
Bearer eCom	обов'язковий	заголовок Authorization	Доступ до всіх eCom-ендпоінтів (ТТН, групи, форми).
Counterparty token	обов'язковий	query ?token=	Токен контрагента; потрібен більшості методів eCom.
Bearer StatusTracking	опційний	заголовок Authorization	Окремий сервіс відстеження статусів — свій токен. ТТН, реєстри й наклейки без нього працюють, але це єдиний вхід для трекінгу: разом з ним відпадають статусні алерти, вебхуки зміни статусу, аналітика доставок і повернень та докази статусу для претензій.
UUID контрагента	опційний у нашому кабінеті; в API не міряно	у тілах запитів/відповідей (counterpartyUuid)	Ідентифікатор вашого контрагента — не секрет. У специфікації зустрічається лише як поле тіла; наш кабінет працює без нього — форма підключення позначає його опційним, і в запити до API він не підставляється. Єдине видиме місце — друкована заява на розшук: там рядок «UUID контрагента» лишиться з прочерком.

Джерело. Модель авторизації — специфікація eCom API; тотожність «counterparty token = user token» видно з тексту документації Укрпошти, де параметр ?token= названо саме user token. Обов'язковість — із форми підключення в кабінеті: Bearer eCom і Counterparty token — обов'язкові поля, решта — опційні. В API ?token= потрібен більшості методів eCom, тож без нього підключення практично непрацездатне. UUID контрагента приходить тим самим листом від менеджера, а в API зустрічається як поле тіла counterpartyUuid (у картці клієнта, у групі відправлень, в отримувачах післяплати) — жодного ендпоінта, де він був би сегментом шляху, у специфікації немає. Чи вимагає його якийсь із цих блоків тіла, ми не міряли — зокрема гілка післяплати на банківський рахунок у пісочниці недосяжна, — тому й не стверджуємо цього: сказано рівно те, що перевірене нашим кабінетом. Не плутайте його з uuid клієнта-відправника: у шляхах на кшталт /clients/{uuid} стоїть саме ідентифікатор клієнта, а не контрагента.

4. Чого API не вміє

Це найкорисніша частина розбору — межі, об які найчастіше б'ються інтегратори. Кожна обмеженість тут — API самої Укрпошти, а не нашого кабінету. Заміряні речі наведено з датою та середовищем.

Немає плоского «списку всіх ТТН»

Факт. API не віддає плоский перелік усіх відправлень. Знайти ТТН можна лише за конкретним ідентифікатором (штрихкод / UUID / зовнішній id / телефон клієнта) або в межах груп-реєстрів: спершу групи контрагента, потім відправлення всередині групи. Маршрут «усі ТТН відправника за період» відповідає 404 шлюзу — його просто не існує; єдина вибірка за період — вузька (лише ті ТТН, у яких змінилася ціна у відділенні).

Джерело. Живий замір sandbox і prod, 05.07.2026 (реальний відправник повернув 404 шлюзу на маршруті «за період»). Наслідок: список «Мої ТТН» доводиться вести у власній базі, а не питати в Укрпошти.

Видалення групи немає

Факт. Метод DELETE /shipment-groups/{uuid} згаданий у документації (стор. 189), але без прикладу; живцем шлюз WSO2 віддає на нього 404 у форматі XML — і на порожніх, і на непорожніх групах. Перейменувати групу можна; «закриття» API теж приймає (PUT {closed:true} → 200 із повним ехо), але група після цього лишається відкритою. Видалення немає взагалі.

Джерело. Видалення: 6 спроб 20–21.07.2026, prod і sandbox, порожні й непорожні групи — усюди 404. Плюс письмове підтвердження API-підтримки Укрпошти від 21.07.2026: «Методу видалення груп не існує». Закриття: замір sandbox 22.07.2026 — PUT {closed:true} віддає 200, надіслана в тому ж тілі name реально змінюється (тобто запит оброблено), а GET після нього показує closed:false. Тому реєстри-теки, які вже не потрібні, в кабінеті ховаються, а не видаляються, а «закрито» кабінет тримає у себе локально.

Ліміт 500 на групу — кумулятивний за весь її вік

Факт. На одну групу-реєстр можна призначити за замовчуванням не більше 500 відправлень, і це ліміт за весь вік групи, а не на її поточний розмір. Перенесення ТТН у групу витрачає призначення з квоти; перенесення назовні його не повертає (повертає лише видалення ТТН). Тобто лічильник рахує «коли-небудь призначені мінус видалені», а не «скільки лежить зараз».

Джерело. Стеля 500 задокументована самою Укрпоштою (документація API, версія 09.03.2026, стор. 195: «До групи можливо додати не більше 500 відправлень»). Кумулятивність — замір prod 21.07.2026: група з 62 фізичними ТТН показувала 500 за лічильником призначень, і Укрпошта відмовляла в новій ТТН («more then 500 shipments»). Механіка витрат — окремий дослід тієї ж серії на двох порожніх групах з однією ТТН: перенесення у групу дає +1 приймачеві, перенесення назовні лічильник не зменшує, а DELETE самої ТТН звільняє призначення в усіх групах, де вона колись була. Чи піднімає Укрпошта цю стелю за договором — ми не з'ясували: на це питання (як і на питання про базу лічильника) підтримка у відповіді від 21.07.2026 не відповіла. Тому в нашому кабінеті стеля — параметр підключення, а не зашита в код константа 500.

На «спеціальний» метод зміни отримувача покладатися не можна

Факт. Виклик PUT /shipments/management/{uuid}/recipient на ТТН, яку ще можна редагувати, поводиться непередбачувано. В одному замірі на ТТН у статусі CREATED він повернув чесний 200 — і не змінив нічого (свіже читання показало колишнього отримувача й колишній індекс); в іншому прогоні на щойно створеній ТТН той самий метод відповів 400. Тобто вікно доступності зміни отримувача цим методом не з'ясоване, а 200 від нього не доводить, що щось справді змінилося. На рівні API той самий прод-замір показав робочу альтернативу: повний PUT /shipments/{uuid} із новим отримувачем і його адресою індекс таки змінює (штрихкод, ціна й опис при цьому зберігаються).

Джерело. Два окремі заміри 28.07.2026. Перший — prod, ТТН у статусі CREATED: 200 без ефекту (поле «востаннє змінено» лишилося датою створення). Другий — sandbox (dev.ukrposhta.ua), щойно створена ТТН: 400. Обидва — поодинокі спостереження (одна ТТН, один контрагент), до того ж у різних середовищах, тож і різниця кодів може бути різницею середовищ, а не поведінки методу: жодне з двох пояснень цими замірами не відсіяне. Для ТТН уже в доставці поведінка не мірялась, а самé вікно доступності методу лишається відкритим питанням.

Індекс відділення (pi) — це не індекс зони (pc)

Факт. У відділення два різні індекси, і адресний класифікатор розрізняє їх іменем параметра: ?pi= — індекс відділення (для пересувного — індекс його бази), ?pc= — індекс зони обслуговування, той самий, що покупець пише на конверті. В адресу ТТН Укрпошта приймає саме індекс зони (pc). На великому міському відділенні обидва збігаються, тому помилка «шлемо не той параметр» вилазить лише на селах.

Джерело. Замір адресного класифікатора 22.07.2026, середовище — production, хост www.ukrposhta.ua (одне сільське ВПЗ: pi повертав 231 запис усіх зон бази, pc — рівно один запис потрібної зони). Хост тут не формальність: простори id у баз різні (та сама область має різний REGION_ID на www і на dev), тож база і є середовищем. Що адресу ТТН приймають за індексом зони — письмово підтверджено API-підтримкою Укрпошти 21.07.2026.

Адресний класифікатор не потребує окремого третього токена

Факт. Служба адресного класифікатора — окрема від /ecom/0.0.1, і баз у неї дві. Та, що з суфіксом -ws (www.ukrposhta.ua/address-classifier-ws), авторизується тим самим Bearer eCom: окремого третього токена вона не вимагає, counterparty ?token= їй теж не потрібен. Та, що без -ws (www.ukrposhta.ua/address-classifier), не потребує взагалі жодної авторизації — ні Bearer, ні ?token=. А от заголовок Accept: application/json обов'язковий на обох базах: без нього шлюз WSO2 віддає XML замість JSON під тим самим 200 — тиха поломка, яка вилазить уже десь у розборі відповіді, за кілометр від причини.

Джерело. Замір обох баз класифікатора 22–24.07.2026, середовище — production (обидві бази живуть на хості www.ukrposhta.ua: /address-classifier-ws і /address-classifier): база -ws відповідає під Bearer eCom без додаткового токена, база без -ws — без авторизації взагалі. Три набори заголовків міряні на базі без -ws 23.07.2026, той самий URL: із Accept: application/json — JSON, без Accept і з Accept: */* — XML. Для бази -ws обов'язковість Accept взята зі специфікації служби, а не з цього заміру.

5. Що з цим робить наш кабінет

Усе перелічене вище — це те, над чим кабінет бере роботу на себе. Список «Мої ТТН» він веде у власній базі (бо API плоского переліку не дає); квоту на групу тримає лічильником і показує «використано X із N»; теки не видаляє, а ховає; в адресу ТТН підставляє індекс зони, а не відділення. Це не заміна API Укрпошти, а надбудова, яка знімає його гострі кути.

Окремо про зміну отримувача. Кабінет кличе той самий «спеціальний» метод PUT /shipments/management/{uuid}/recipient, але не вірить його 200: після виклику робить свіжий GET і звіряє отримувача — коли Укрпошта віддає його у відповіді. Якщо отримувача в тілі немає, звіряти нема з чим: доказу немає, і кабінет пише про це в лог. Якщо ж Укрпошта відповіла 200 і при цьому не змінила нічого, кабінет не рапортує про успіх, а пропонує заміну ТТН — створює нову накладну з новим отримувачем і видаляє стару. Це вже створення ТТН: новий штрихкод і списання права з квоти, тому кабінет питає про це явно, а не робить мовчки.

Що почитати далі: огляд функцій — на сторінці можливостей; технічний quickstart із власним ключем X-Api-Key, скоупами й прикладами коду — у документації API; чим саме кабінет B2B-відправника відрізняється від особистого кабінету Укрпошти — на сторінці «Кабінет відправника».