Посібник користувача — Кабінет B2B відправника Укрпошти (неофіційний)

Кабінет (ukrposhta.main.fish) — це незалежне B2B-робоче місце відправника для сервісів Укрпошти: реєстрація, підключення власних ключів Укрпошти, оформлення та друк ТТН, реєстри, трекінг, повернення й інтеграція через API. Цей документ веде нового користувача від першого входу до першої накладної — в інтерфейсі та через API.

Дисклеймер. Це неофіційний сервіс: він не є офіційним сайтом АТ Укрпошта і не афілійований з нею. Укрпошта згадується лише як перевізник, чиї публічні API кабінет використовує за вашими ключами.

Цей самий текст відкривається просто в кабінеті — пункт меню Посібник.

Зміст

1. Повний флоу роботи з кабінетом
2. Реєстрація та вхід
3. Профіль і дані платника
4. Підключення ключів Укрпошти
5. Відправник за замовчуванням
6. Створення ТТН в інтерфейсі
7. Друк, реєстри та партії
8. Масове створення ТТН
9. Гроші: баланс, ліміти, рахунки
10. Відстежити й розслідувати
11. Інтеграція через API
12. Ролі та спільний доступ

Мапа розділів меню

Ліве меню кабінету зібране за флоу-задачами, а не за сутностями — п'ять розділів, кожен охоплює один етап роботи. Ось повний склад (у дужках — де про пункт читати далі):

• Відправити — усе про створення й здачу відправлень: Мої ТТН, Чекаут → ТТН, Відправники, Отримувачі, Чорний список, Журнал друку, Виклики кур'єра.
• Відстежити й розслідувати — трекінг, обзвон і розшук: Пошук, Сповіщення, Кейси, Повернення, Історія розслідування, Технічний журнал.
• Гроші — оплата підключення й розрахунки: Підсумки за період, Мій план, Рахунки, Післяплата — гроші.
• Інтеграції — робота через API (лише ролям Owner і Admin): API-ключі, Хостований чекаут.
• Налаштування — ключі, доступ і профіль: Ключі Укрпошти, Доступ, Профіль, Підтримка, Посібник.

1. Повний флоу роботи з кабінетом

Один цикл відправлення від краю до краю: ТТН, реєстр, друк, закриття, передача, трекінг, зберігання — а якщо щось пішло не так, то розшук, претензія, акт ф.20, повернення вартості й бухгалтерія. Нижче — схема всього шляху й три неочевидності, на яких найчастіше спотикаються. Решта посібника (розділи 2-12) розбирає ті самі кроки по одному, зі знімками меню й порядком дій.

Потрібні технічні деталі — ключі X-Api-Key, скоупи, приклади коду й вебхуки? Дивіться API quickstart для розробників. Огляд функцій кабінету — на сторінці можливостей, ціни за відправлення — у тарифах.

Схема повного циклу

Основний шлях іде згори вниз. Гілка втрати й розшуку — кроки 8 і 9 — вмикається лише тоді, коли відправлення втрачено або не отримано; у звичайному сценарії трекінг закінчується врученням.

1. ТТН — створення відправлення. Оформіть його в кабінеті або через API. У ТТН фіксується тарифний тип: STANDARD, EXPRESS, DOCUMENT або CARGO.
2. Група (реєстр) — ТТН лягає в групу-реєстр відправника під свій ефективний тип. Без явного groupId кабінет тримає окрему дефолтну групу на кожен тип.
3. Друк наклейок і реєстру ф.103 — реєстр формується й на відкритій групі: закриття для ф.103 не потрібне.
4. Закриття реєстру — закрийте групу перед передачею партії. Виклик ідемпотентний: повторне закриття вже закритої групи повертає 200 без побічних ефектів.
5. Передача — передайте партію Укрпошті: викликом кур'єра або здачею у відділення.
6. Трекінг — відстежуйте семантичні статуси ТТН через кабінет або API. Кабінет веде єдиний таймлайн і фіксує докази: сирі відповіді Укрпошти плюс хеш-ланцюг.
7. Нагадування забрати — кабінет підсвічує ТТН, у яких до кінця терміну зберігання лишається ≤ 3 дні, щоб кол-центр устиг нагадати отримувачу.
8. Втрата або розшук — якщо відправлення втрачено чи не отримано, зберіть доказовий пакет: події трекінгу, сирі відповіді Укрпошти, хеш-ланцюг, бланк claim.pdf.
9. Рішення — претензія/розшук (Claim), юридично значущий акт ф.20 або повернення вартості (return-order).
10. Бухгалтерія — сформуйте рахунки й акти. Номер рахунку наскрізний за рік: UP-РРРР-######.

Найдешевший спосіб пройти цикл цілком — підключити sandbox-ключі й провести тестову ТТН від створення до реєстру, нічого нікуди не передаючи.

Неочевидність 1. Тип ТТН і тип групи мають збігатися

Укрпошта вимагає, щоб тарифний тип ТТН збігався з типом групи-реєстру, у яку ця ТТН лягає. Розбіжність — це помилка UPE01001 на боці Укрпошти.

Неочевидність 2. Що можна до й після закриття реєстру

Закриття групи (реєстру) — це рубіж: набір ТТН у партії фіналізується. До нього й після нього доступні різні операції.

До закриття реєстру:

• ✓ Додавати й переміщувати ТТН між групами.
• ✓ Друкувати наклейки й реєстр ф.103 — закриття для ф.103 не потрібне.
• ✓ Закрити групу, коли партія зібрана.

Після закриття реєстру:

• ✗ ТТН у групу не додати: спроба повертає 400 з поясненням, що група закрита.
• ✗ ТТН не перемістити: спроба повертає 400.
• ✓ Повторне закриття вже закритої групи ідемпотентне — повертає 200 без побічних ефектів.

Неочевидність 3. Сценарій втрати: від моніторингу до бухгалтерії

Якщо відправлення не отримали або воно загубилось, кабінет веде його наскрізним ланцюгом — від виявлення на моніторингу до повернення вартості й проведення в бухгалтерії.

1. Моніторинг «Горить зберігання» — кабінет підсвічує ТТН, у яких до кінця терміну зберігання лишається ≤ 3 дні, і дає список на обзвон (експорт у XLSX: телефон, опис, дата відправки, дедлайн).
2. Розслідування — по кожній ТТН ведеться єдиний таймлайн: події трекінгу, картка номера телефону, історія дій. Тут же збираються докази — сирі відповіді Укрпошти й хеш-ланцюг (tamper-evident журнал).
3. Претензія / розшук (Claim) — дія «Претензія / розшук» спершу відкриває передперегляд: показує, що саме увійде в пакет (файли з розмірами, кількість подій і діапазон їх дат, кількість сирих відповідей Укрпошти, ланки хеш-ланцюга та ключові поля бланка). Пакет (ZIP із claim.pdf — бланком заяви на розшук або претензію, подіями трекінгу, сирими відповідями й хешами) формується лише після того, як ви побачили передперегляд і підтвердили формування, — сам передперегляд нічого не створює. Якщо претензію по ТТН помилково створено, чернетку (статус Formed) можна прибрати прямо в передперегляді кнопкою «Видалити чернетку» й сформувати заново. Якщо претензія по ТТН уже закрита (вирішена або відхилена), передперегляд показує це й пропонує перезавантажити її наявний пакет; завести ще одну можна, але лише свідомо — окремою кнопкою «Сформувати нову претензію», щоб друга претензія не з'являлась мовчки. Статуси претензії: Draft → Formed → Submitted → Resolved.
4. Акт ф.20 — юридично значущий крок: на боці Укрпошти ф.20 єдина з форм створюється (POST), а не лише читається. Тому потрібен скоуп write.
5. Повернення вартості (return-order) — замовлення повернення відправлення або його вартості (скоуп manage).
6. Бухгалтерія — рахунки й акти проводяться у розділі Оплата. Номер рахунку наскрізний за рік: UP-РРРР-######; платником виступає юрособа з вашого профілю.

2. Реєстрація та вхід

1. Відкрийте ukrposhta.main.fish і натисніть «Увійти».
2. Magic-link — введіть e-mail і отримайте лист із посиланням для входу. Лист надходить із noreply@main.fish; якщо його не видно, перевірте теку Спам.
3. Google — вхід через ваш Google-акаунт.
4. Після першого входу відкривається головний екран кабінету з чек-листом налаштування — він проведе вас по кроках нижче (див. Чек-лист налаштування).

Окремої реєстрації з паролем немає: перший вхід за e-mail або Google автоматично створює ваш профіль.

Чек-лист налаштування

Домашній екран кабінету показує чек-лист налаштування — послідовність кроків до оплати з лічильником готовності (Готово N з M). Кроки заблоковані по порядку: наступний відкривається, коли закрито попередній. Повний склад — сім кроків:

1. Додати ключі — підключіть свої ключі Укрпошти на сторінці Ключі Укрпошти (розділ 4). Крок закривається наявністю хоча б одного підключення. Якщо договору з Укрпоштою ще немає — тут же розкривалка «Ще немає ключів?».
2. Прийняти оферту — ознайомтесь із публічною офертою й прийміть її; без згоди мутуючі дії в кабінеті заблоковані. Цей крок зʼявляється в чек-листі лише коли ввімкнено серверний гейт згоди з офертою — при вимкненому гейті його в списку немає взагалі (він не позначається завжди виконаним, а просто не рахується в лічильнику Готово N з M).
3. Задати відправника — збережіть відправника на сторінці Відправники (розділ 5); його дані підставляться в нові накладні. Крок закривається наявністю відправника у підключенні.
4. Створити першу ТТН — оформіть першу накладну кнопкою «Створити ТТН» на сторінці Мої ТТН (розділ 6). Крок закривається появою хоча б однієї ТТН.
5. Додати платника — заповніть реквізити платника (ЄДРПОУ, адреса, банк, IBAN) у розділі «Юрособи-платники» на сторінці Профіль (розділ 3); за ними виставляється рахунок. Крок закривається наявністю хоча б одного платника з повними реквізитами — платника лише з назвою замало.
6. Отримати рахунок — виставте рахунок на права створення ТТН на сторінці Рахунки (розділ 9) і сплатіть його банківським переказом. Крок закривається наявністю виставленого або сплаченого рахунку (статус Issued чи Paid); чернетка або скасований рахунок його не закривають. Оплата відкриває ліміт боргу (= розмір поповнення), тож надквотні ТТН створюються й далі, а поки баланс у межах ліміту, друк наклейок і форм, формування реєстру, закриття партії та виклик кур'єра не призупиняються (той самий перелік, що в розділі 9 — там же описано, що буде, коли ліміт вичерпано).
7. Випустити API-ключ — випустіть ключ кнопкою «Випустити ключ» на сторінці API-ключі (розділ 11). Крок навмисно останній: це крок інтеграції, а не частина шляху до оплати.

Коли всі видимі кроки виконано, чек-лист згортається, і кабінет одразу веде на Мої ТТН. Чек-лист можна згорнути або сховати — стан памʼятається окремо для кожного акаунта.

Якщо щось не спрацювало вже на цьому кроці, напишіть у підтримку просто з кабінету: Налаштування → Підтримка (/app/support). Розділ доступний будь-якій ролі й не вимагає вибраного підключення: там же видно статус звернення (Відкрито, В роботі, В обробці, Вирішено, Відхилено) і всю переписку.

3. Профіль і дані платника

Меню: Налаштування → Профіль (/app/profile).

Тут зберігаються:

• Ваші контактні дані та e-mail — зміна e-mail підтверджується листом.
• Юрособи-платники (розділ «Юрособи-платники» у профілі) — реквізити компанії, від імені якої виставлятимуться рахунки на оплату: назва, ЄДРПОУ, адреса.

Заповніть хоча б одного платника до того, як формуватимете рахунки — ці дані підставляться у рахунок як платник.

4. Підключення ключів Укрпошти

Меню: Налаштування → Ключі Укрпошти (/app/connections).

Щоб працювати з ТТН, кабінет має звертатися до API Укрпошти від вашого імені. Для цього потрібні ваші ключі:

• Bearer eCom — токен доступу до eCom API. Обов'язковий.
• Counterparty token — токен контрагента, передається як параметр запиту ?token=. Обов'язковий.
• Bearer StatusTracking — токен трекінгу. Опційний: ТТН, реєстри й наклейки без нього працюють. Але це єдиний вхід для трекінгу, тож разом з ним не працює й усе, що з нього походить: статусні алерти (черга дзвінків), вебхуки зміни статусу, аналітика доставок і повернень, докази статусу для претензій.
• Counterparty UUID — ваш ідентифікатор контрагента в системі Укрпошти. Опційний.

Де взяти ключі

Ключі не видаються в кабінеті Укрпошти самообслуговуванням. Їх надсилає поштою персональний менеджер відділу B2B Укрпошти після укладення договору. Порядок:

1. Знайдіть контакти менеджера відділу B2B Укрпошти — стартова точка: dev.ukrposhta.ua/for-business (портал розробника, розділ для бізнесу).
2. Укладіть договір на послуги eCom/API.
3. Менеджер надішле вам на пошту набір ключів: обов'язкові eCom і counterparty token, а також опційні StatusTracking і UUID контрагента.

Отримані значення введіть у форму «Додати підключення». Кабінет зберігає їх зашифрованими (AES-256) і ніколи не показує повторно у відкритому вигляді.

Можна додати кілька підключень (наприклад, sandbox і production) і позначити одне за замовчуванням — воно використовуватиметься для нових ТТН.

Ще немає ключів Укрпошти?

Якщо договору з Укрпоштою ще немає, скористайтеся розкривалкою «Ще немає ключів?» — вона доступна у двох місцях: у першому кроці онбординг-чекліста на домашній сторінці (додавання ключів) і тут, на сторінці Ключі Укрпошти. Розкривалка пояснює:

• Звідки беруться ключі — їх видає персональний менеджер відділу B2B Укрпошти й надсилає поштою після укладення договору на послуги API; кабінет ключі не генерує.
• Які саме ключі потрібні — обов'язкові Bearer eCom і Counterparty token; опційні Counterparty UUID і Bearer StatusTracking (без нього не працює трекінг і все, що з нього походить, — див. вище). Окремо від ключів доступу — Sender client UUID (під ним створюються реєстри й ТТН): це не токен, а ідентифікатор вашого клієнта-відправника в системі Укрпошти.
• Що підготувати для звернення — ЄДРПОУ і назву юрособи, потрібне середовище (sandbox і/або production) та орієнтовний обсяг відправлень.
• Куди звертатися — стартова точка й порядок укладення договору на порталі розробника Укрпошти (розділ для бізнесу).

5. Відправник за замовчуванням

Меню: Відправлення → Відправники (/app/senders).

Збережіть свого відправника — ПІБ або назву, телефон, адресу відправлення. Ці дані автоматично підставляються у кожну нову накладну, тож не доведеться вводити їх щоразу.

6. Створення ТТН в інтерфейсі

Меню: Відправлення → Мої ТТН (/app/ttn), кнопка «Створити ТТН».

У формі створення:

1. Відправник — підставляється зі збереженого (розділ 5); за потреби змініть.
2. Отримувач — введіть вручну або оберіть з адресної книги: ПІБ, телефон, адреса чи відділення.
3. Параметри відправлення — вага, оголошена вартість, накладний платіж (за потреби), опис вкладення.
4. Розрахунок вартості — вартість доставки перераховується автоматично за введеними параметрами, її видно ще до створення.
5. Натисніть «Створити ТТН» — ТТН з'явиться у списку «Мої ТТН» зі штрихкодом.

Поштовий індекс: індекс зони і індекс відділення

У полі індексу можна вводити і індекс з конверта (індекс зони обслуговування — те, що зазвичай друкують на листі), і індекс самого відділення. Форма знайде потрібне ВПЗ за будь-яким із них.

Пересувне відділення окремого індексу для вибору не має — оберіть його через свій населений пункт: у переліку з'явиться саме те пересувне ВПЗ, що обслуговує вашу адресу.

Прискорювачі оформлення

• Отримувачі (/app/recipients) — адресна книга: раніше збережені отримувачі підставляються у форму, дедуплікація за нормалізованим телефоном.
• Пресети — збережіть типовий набір параметрів відправлення й застосовуйте його одним кліком.
• Чернетки — незавершена форма зберігається локально в браузері, щоб не втратити введене.

Чорний список

Меню: Відправлення → Чорний список (/app/blacklist).

Телефони та коди ЄДРПОУ, з якими працювати не варто. Запис має один із двох рівнів: Блокування — бекенд відхилить створення ТТН на такого отримувача; Попередження — ТТН створиться, але оператор побачить застереження. Список ведеться на рівні підключення.

Пошук ТТН, UUID або телефон

Меню: Відправлення → Пошук (/app/shipments).

Єдина точка входу пошуку: одне поле приймає штрихкод (ШКІ), UUID відправлення або телефон. Кабінет сам розпізнає, що саме ви ввели, і веде за призначенням:

• штрихкод / UUID — точковий пошук однієї ТТН просто в Укрпошті, навіть якщо цю ТТН створювали не в кабінеті. Це не список: плоского переліку всіх ТТН у API Укрпошти немає, тому власний список кабінет веде у себе (сторінка «Мої ТТН»), а «Пошук» ходить за конкретним номером;
• телефон — ввід одразу веде в картку номера з усією історією цього номера в поточному підключенні (див. нижче), а не шукає окрему ТТН;
• надто короткий числовий ввід (≤8 цифр) не схожий ні на повний штрихкод, ні на телефон, тож кабінет не вгадує, а показує підказку про очікуваний формат — щоб ви дописали номер повністю, а не отримали порожню видачу.

Знайдену за штрихкодом/UUID ТТН кабінет далі розводить за походженням. Якщо вона є у вашому кабінеті, пошук веде одразу в її картку — ту саму єдину сторінку деталей ТТН, що й із «Мої ТТН» (окремої, другої сторінки деталей більше немає): з повною адресою отримувача, історією та всіма діями над ТТН. Якщо ж ТТН у вашому кабінеті немає (чужа або історична), кабінет показує лише сирі дані Укрпошти за цим номером у режимі перегляду, з явною позначкою «ТТН не з вашого кабінету» — жодних дій над такою ТТН тут немає.

7. Друк, реєстри та партії

Меню: Відправлення → Мої ТТН (/app/ttn).

Наклейка (стикер) друкується з картки ТТН або зі списку кнопкою друку: PDF, формат A6 100×100 за замовчуванням. Реєстр ф.103 — друкований реєстр партії; друкується з контекстного меню теки пунктом «Ф.103 (офіційна/велика)» або формується автоматично після закриття реєстру. Саме цей бланк подають разом із партією у відділенні або кур'єру. Поруч у меню теки є пункт «Ф.103 (неофіційна/компактна)» — наш власний скорочений рендер того ж реєстру (це не офіційний бланк Укрпошти, а щільніший список тих самих ТТН для внутрішнього користування).

Партії (теки)

На сторінці «Мої ТТН» відправлення розкладені деревом, як у файловому менеджері: корінь — сумісність (тариф · відправник), тека — партія-реєстр. Дії над партією (закрити реєстр і здати, друк реєстру ф.103, наклейки, виклик кур'єра) — у контекстному меню теки. Окремих сторінок для партій і реєстру ф.103 більше немає: /app/groups і /app/registry тепер редіректять на /app/ttn.

Щойно створена ТТН лягає в кореневий вузол «Нові ТТН» — головний вхідний кошик відправника: ці ТТН ще не розкладені по партіях-реєстрах. Кабінет розкриває цей вузол сам при першій появі дерева. Звідси ТТН треба розкласти по теках, перш ніж друкувати наклейки й здавати партію — цей передвідправний крок описано нижче.

Рядки, що зʼявилися після вашого попереднього перегляду списку, кабінет позначає бейджем «Нове» — однаково в списках ТТН, відправників, отримувачів і тек. Це приватна відмітка вашого браузера (не поле сутності й не стан в Укрпошті): при першому відкритті списку нічого не світиться, а далі «Нове» показує саме те, що додалося з минулого разу.

Після масової операції — імпорту з файлу, масового дублювання чи масового створення — над списком зʼявляється чіп Показати лише щойно створені (N), де N — скільки ТТН щойно створено. На відміну від бейджа «Нове», який лише підсвічує рядки, цей чіп звужує список рівно до цієї партії (id повертає сервер), тож усе інше з очей зникає, а екран переходить у плоский режим. Повторний клік по чіпу знову показує весь список, а хрестик прибирає чіп зовсім. Множина скидається сама при зміні підключення або коли ви запускаєте наступну масову операцію.

Колонки списку

Колонка «Що доставляється» показує опис вкладення ТТН — те, що заявлено до відправки. ТТН без опису (підтягнуті звіркою реєстру чи історичні) показані приглушеним «Без опису».

Лічильник і сортування по цій колонці працюють у плоскому режимі списку — коли ввімкнено пошук чи фільтр (зокрема «Групи товарів» або обрана тека). Тоді в заголовку в дужках стоїть кількість унікальних товарів по всій поточній вибірці (з урахуванням теки, фільтра й гілки активні/архів), тож число міняється разом із ними, а не лише по видимій сторінці, а клік по заголовку сортує список по товару — за зростанням абетки й, повторним кліком, за спаданням; ТТН без опису завжди йдуть у кінці. У звичайному древоподібному вигляді (з розкритим вузлом «Нові ТТН») колонка статична: без лічильника й без сортування кліком — там список теки тягнеться своїм порядком, і пересортувати кліком можна лише плоску вибірку.

Фільтр по товару: «Групи товарів»

Кнопка «Групи товарів» над списком відкриває поповер із переліком товарів поточної вибірки — від найпопулярнішого до менш популярного, з кількістю ТТН у кожній групі; окремим рядком іде кошик «Без опису». Перелік обмежений топом найчастіших; якщо унікальних товарів більше, поповер чесно пише, що показано лише топ (показано топ-N із M). Клік по групі лишає в списку лише її ТТН (екран переходить у плоский режим, як пошук), а клік по значенню товару в рядку ставить той самий фільтр — швидкий шлях показати всі такі, доступний і для товарів поза топом.

Активний фільтр видно чипом із назвою товару поруч із кнопкою; хрестик на ньому скидає звуження. Фільтр живе в адресі сторінки, тож переживає перезавантаження і кнопку Назад у браузері, а клік по пункту «Мої ТТН» у меню скидає його разом з рештою (гілка, пошук, колонка). Під фільтром працює все інше: вибір усієї вибірки бере рівно стільки ТТН, скільки показує група (навіть якщо вони на різних сторінках), а перенос селектором «Перемістити в папку…» переносить саме цю множину; експорт CSV/XLSX теж вивантажує рівно її. Зміна фільтра щоразу скидає поточне виділення — щоб масова дія не поїхала по рядках, яких уже не видно.

Розкласти однакові товари по теках перед відправкою

Типовий передвідправний сценарій: у вузлі «Нові ТТН» зібралась купа щойно створених відправлень із різним вкладенням, а пакувати, обклеювати наклейками й здавати їх зручніше партіями одного товару. Колонка «Що доставляється», фільтр «Групи товарів» і перенос у теку складаються тут в один порядок дій:

1. Розкрийте вузол «Нові ТТН» (кабінет розкриває його сам при першій появі дерева) — це і є набір, який треба розсортувати.
2. Кнопкою «Групи товарів» гляньте розбір цього набору по товару: скільки ТТН на кожен товар, від найпопулярнішого до менш популярного, окремим рядком — кошик «Без опису». Те саме число унікальних товарів стоїть у заголовку колонки «Що доставляється».
3. Клік по групі лишає на екрані лише ТТН цього товару (екран переходить у плоский режим).
4. Виділіть усю вибірку — навіть якщо ТТН розкидані по сторінках, вибір усього за фільтром бере рівно множину цього товару — і перенесіть її селектором «Перемістити в папку…» у теку під цей товар. Так усі однакові відправлення зберуться в одній партії-реєстрі.
5. Скиньте фільтр чипом і повторіть для наступного товару. Коли кожен товар лежить у своїй теці, друкуйте наклейки й реєстр ф.103 партіями, обклеюйте й здавайте — вкладення вже не переплутати.

Сортування теж допомагає розкладанню: клік по заголовку «Що доставляється» шикує список по товару абеткою (ТТН «Без опису» — завжди в кінці), тож однакові відправлення стають поруч навіть без фільтра.

Пошук у списку і картка номера

Над списком — одне поле пошуку: у нього однаково вводиться штрихкод (чи його частина), ПІБ отримувача, зовнішній id замовлення й телефон отримувача. Пошук іде на сервері крізь усю вибірку, тож знаходить ТТН з будь-якої сторінки, а не лише на видимій. Телефон розпізнається в будь-якому записі — +380671234567, 0671234567, (067) 123-45-67 — це той самий номер.

Щойно введене схоже на телефон, поруч спливає кнопка «Картка номера». Це вже не фільтр, а окрема сторінка з усією історією номера в поточному підключенні: лічильники (вручено, повернуто, в дорозі, очікують), перелік ТТН, злитий таймлайн подій і жива перевірка чорного списку Укрпошти. Туди ж веде клік по телефону в рядку списку.

У картці номера клік по рядку відкриває історію ТТН (події, докази, нотатки, кейс), а кнопка Відкрити в «Мої ТТН» повертає в список, відфільтрований на цю ТТН, — з усіма діями над нею. Заархівовану ТТН перехід відкриває одразу в архівному зрізі, тож рядок не губиться.

З картки номера завжди є зворотний вихід у пошук: кнопка «Новий пошук» (у шапці — ← Новий пошук) повертає в те саме єдине поле пошуку. А якщо картку відкрито саме з пошуку (ви ввели те, що кабінет розпізнав як телефон), поруч зʼявляється й друга кнопка Шукали ТТН? Знайти <ваш ввід> як штрихкод (замість <ваш ввід> кнопка підставляє введений вами рядок) — вона бере той самий рядок і шукає його вже примусово як штрихкод, минаючи розпізнавання телефону. Це вихід із випадку, коли ваш номер насправді був штрихкодом, схожим на телефон.

«Сховати папку»

Пункт у тому ж меню: тека зникає з дерева лише в цьому кабінеті. Це не видалення. Укрпошта не дозволяє видаляти реєстри (методу видалення групи в її API не існує), тож у кабінеті Укрпошти тека лишається, а ТТН залишаються в ній і нікуди не переїжджають. Повернути теку — перемикачем «Показати приховані» над деревом: сховані показуються приглушено з дією «Повернути», після якої знову працюють друк ф.103, закриття партії й перенос ТТН.

Перенос ТТН у теку

Перетягніть обрані (або одну) ТТН за ручку ⠿ на потрібну теку: тека під курсором підсвічується зеленим, якщо приймає набір, а несумісні теки одразу показують причину відмови. Перед самим переносом кабінет питає підтвердження й називає в ньому кількість ТТН і теку-ціль — без цього не рухається жодна ТТН.

Ручка ⠿ є лише у режимі дерева. Щойно ввімкнено наскрізний фільтр (пошук, «Горить зберігання», колонка борду, обрана партія), список стає плоским, тек на екрані немає — і кидати набір нікуди. Перенос у цьому вигляді (а також без миші, з клавіатури) — селектором «Перемістити в реєстр…» / «Перемістити в папку…» у панелі над списком.

Масова зміна тарифу

У панелі виділення (з'являється, щойно обрано хоч одну ТТН) оберіть тариф у списку «Змінити тариф…» — Базовий, Пріоритет, Документ, Вантаж — і натисніть «Змінити тариф». Кожна обрана ТТН отримає новий тариф і переїде в теку цього тарифу свого відправника: відправник операцією не змінюється.

Перед запуском обов'язкове підтвердження: операція йде в Укрпошту по одному запиту на ТТН, не відкочується, і кожна ТТН витрачає одне призначення з ліміту цільової теки. ТТН, уже передані у доставку, буде відхилено — тариф їм не змінюється. Після завершення показується розбір по кожній ТТН із причиною відмови; поки є відмови, виділення не скидається, щоб було що повторити чи звірити.

Зміна тарифу теки

Пункт «Змінити тариф папки» в контекстному меню теки: під новий тариф переїжджає весь її вміст, по одній ТТН у теку нового тарифу свого відправника. Правила й застереження ті самі, що в масовій зміні тарифу вище.

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

Дії над окремою ТТН

У кожного рядка ТТН є меню дій. Пункт редагування відкриває єдине вікно «Редагувати ТТН» з трьома секціями у фіксованому порядку — отримувач, вантаж, гроші (накладений платіж): зберігаються лише реально змінені секції, а після збереження кожна секція показує свій результат окремо, і невдалі можна повторити. Окремими діями лишаються переадресація, замовлення повернення, продовження зберігання, розділення післяплати, формування претензії та «Зворотна доставка документів» — замовлення повернення підписаних документів окремою зворотною накладною з веденням її статусу поряд з основною.

Секцією «Куди і кому» того самого вікна можна спробувати виправити отримувача, а з ним — індекс і адресу: кабінет заводить отримувача заново з правильними даними й переприв'язує до нього ТТН. Але тут є пастка Укрпошти. На статусі «Створено» зміна отримувача в їхньому API — мовчазний no-op: сервіс відповідає кодом успіху, наче все вдалося, а насправді не міняє нічого. Тому кабінет не вірить відповіді на слово: він звіряє результат і, якщо переприв'язка не спрацювала, замість фальшивого підтвердження про успіх показує реальні виходи — «Замінити ТТН», повтор прив'язки або скасування незавершеної зміни (нижче). Недоступну в поточному статусі секцію (вантаж і гроші редагуються, лише поки ТТН ще не передано) вікно показує заблокованою з причиною, а не ховає.

Якщо зміна отримувача обірвалася на півдорозі (кабінет уже завів нового клієнта в Укрпоші, а переприв'язати ТТН до кінця не встиг), у рядку такої ТТН — поряд із бейджами нотаток і неверифікованої адреси — з'являється бейдж «Повторити прив'язку». Клік по ньому доводить прив'язку до кінця прямо з рядка, без відкриття вікна (кабінет застосовує вже збережений ввід — нічого вводити не треба); коли все вдалося, бейдж зникає. Поряд стоїть дія «Скасувати незавершену зміну» — вона доступна лише через окреме підтвердження, бо прибирає незавершений запис і розблоковує ТТН для нової зміни. Уже створений у Укрпоші клієнт-отримувач при цьому лишається (кабінет його не видаляє), але кабінет втрачає на нього посилання — наступного разу отримувач заведеться наново.

Якщо будь-яка з трьох секцій не збереглася через відмову Укрпошти, під текстом помилки з'являється згорнутий блок «Технічні деталі для підтримки». Кнопка «Скопіювати звіт» у ньому копіює готовий звіт (крок, HTTP-статус, код і повідомлення Укрпошти, кореляція, час і версія збірки) — його можна одразу вставити у звернення в підтримку. Секретів і токенів у звіті немає.

Картка ТТН

Клік по номеру ТТН у списку «Мої ТТН» (а також у картці номера, «Повернення», кейсі чи історії розслідування) відкриває окрему сторінку картки відправлення /app/ttn/:id — спершу в режимі читання, а редагування вмикається кнопкою прямо в картці (див. нижче). Головна цінність картки — повна адреса отримувача з поштовим індексом, зібрана в одному місці.

Картка поділена на секції: шапка (штрихкод — його можна скопіювати одним кліком, статус, остання подія, тека, тип, дата, зовнішній ID і ознаки ТТН), «Куди і кому» (отримувач, його телефон із переходом у картку номера, повна адреса з індексом і окремо адреса відправника), «Що веземо» (вага, габарити, оголошена вартість, опис і місця з їхніми штрихкодами), «Гроші» (накладений платіж, платник доставки, вартість доставки) і «Строки» (дати створення, останньої події, зберігання та повернення).

Локальні поля (штрихкод, статус, опис, вартість, дати) кабінет показує одразу, ще до відповіді Укрпошти. Живі дані (адреси, вага/габарити, місця, накладений платіж) кабінет довантажує окремо; якщо Укрпошта саме недоступна, замість відповідного блоку зʼявляється плашка про недоступність живих даних з кнопкою повтору — решта картки при цьому лишається на екрані (жодного білого екрана чи вічного завантаження). Кнопка «Назад до списку» повертає у список «Мої ТТН» зі збереженими фільтрами, сторінкою й текою. Позначені прапорцями рядки при переході в картку скидаються — якщо ви готуєте пакетну операцію, спершу завершіть її, а вже потім заходьте в картку.

Під шапкою — панель дій над ТТН: усі операції, доступні і зі списку, зібрані в одному місці. Тут і редагування, і «Видалити», і «Переадресація», «Замовити повернення», «Розділити післяплату», «Продовжити зберігання», «Зворотна доставка документів», «Претензія / розшук» (відкриває передперегляд того, що увійде в пакет, а вже потім формує доказовий ZIP), локальна позначка «Позначити тестовою» і зняття ознаки звірки «Адресу звірено — прибрати ознаку». На відміну від меню в рядку списку, недоступну зараз дію картка не ховає, а показує неактивною з причиною (наприклад, продовження зберігання доступне, лише поки посилка лежить на відділенні) — щоб було видно, чому дія закрита, а не гадати. Мутуючі дії, як і всюди, лишаються під серверними гейтами згоди з офертою та боргу — кабінет нічого не обходить. Після будь-якої дії картка перечитується; після видалення — веде назад у список (перечитувати вже нічого). Якщо над ТТН висить незавершена зміна отримувача, тут же зʼявляються «Повторити прив'язку» і «Скасувати незавершену зміну».

Картку можна не лише читати. Кнопка редагування над секціями відкриває просто в картці ту саму форму «Редагувати ТТН», що й у списку (окремої реалізації немає): три секції — «Куди і кому», вантаж і гроші — розблоковуються інлайн, кожна окремо за своєю доступністю; недоступну секцію показано з причиною блокування замість поля. Збереження, повтор лише невдалих секцій, дії над незавершеною зміною отримувача і «Замінити ТТН» працюють точно так само, як у модалці зі списку. Кнопка скасування повертає секції в режим читання з початковими значеннями, а після збереження картка перечитується.

Внизу картки — секція «Історія»: той самий блок, що відкривається у списку «Мої ТТН» і в картці номера кнопкою історії, тільки вбудований прямо в сторінку (окремої реалізації немає). У ньому три вкладки — таймлайн подій («Історія»), журнал-доказ сирих відповідей Укрпошти з хеш-цепочкою («Докази (журнал запитів)») і внутрішні «Нотатки» менеджера, — а нижче завжди видно секцію «Претензії / розшук» і події заведеного по ТТН кейса. Тут же тулбар кейса: «Завести кейс» (формує кейс і одразу збирає доказовий ZIP), «Претензія / розшук» (відкриває той самий передперегляд того, що увійде в пакет: якщо по ТТН уже є претензія, замість повторного формування пропонує завантажити наявний пакет, помилкову чернетку — «Видалити чернетку», а по вже закритій — свідому «Сформувати нову претензію») і посилання на повну історію розслідування по цій ТТН.

«Відправлені»

Окремий згорнутий рядок під теками кореня, у який кабінет сам прибирає партії, з якими роботи вже немає: усі їхні ТТН або здані Укрпошті, або скасовані. Скасована ТТН партію на екрані не тримає — інакше одна скасована лишала б теку в робочому списку назавжди; тож тека, у якій скасовано все, теж приїде сюди. Тримає теку на видноті будь-яка ТТН, яку ще не здали: зі статусом «Створено» чи з надрукованою наклейкою (надрукована наклейка здачею ще не є), а також тестова та з нерозпізнаним статусом. Підпис каже, скільки за ним ховається: N папок · M ТТН.

Нічого не заархівовано й не змінено — розгорніть рядок, і теки працюють як завжди, з тим самим меню, друком і переносом. Тека, яку ви саме розкрили, з-під рук не зникне: коли партію здали просто під час роботи, тека переїжджає в рядок «Відправлені» разом із розкритим вузлом, тобто лишається на екрані й далі відкритою. Якщо всередині є папка, у якої закінчується місце, сам рядок «Відправлені» підсвічується оранжевим і дописує · N біля межі: сигнал про ліміт згортанням не гаситься.

Скільки ТТН вміщує тека: підпис використано X із N

Укрпошта дозволяє призначити в одну теку-реєстр не більше 500 відправлень за весь її вік. Це штатне правило Укрпошти, записане в її документації (стор. 195, вимога додавати не більше 500), а не збій кабінету — тож звертатись із ним у підтримку Укрпошти немає сенсу.

Два наслідки, які легко прийняти за помилку:

• Місце в теці не звільняється. Рахуються всі ТТН, які коли-небудь у ній були: якщо перенести ТТН із теки назовні, вона зникне зі списку теки, але витрачене місце не повернеться. Повертає його лише видалення (скасування) ТТН. Тому в теці цілком може лежати 3 ТТН, а місця в ній уже не бути.
• Теку не можна видалити. Методу видалення групи в API Укрпошти не існує (підтверджено її підтримкою 21.07.2026), тому кабінет теку ховає. Заводити замість переповненої теки нову з тим самим іменем можна, але стару це не прибирає.

Щоб це не ставало сюрпризом, поруч із назвою теки стоїть підпис використано X із N — саме за витраченими місцями, а не за кількістю ТТН у теці. Мертва тека з трьома ТТН чесно показує 500 із 500. N — стеля вашого підключення: Укрпошта піднімає ліміт поокремо кожному контрагенту, тож у вас там може стояти не 500.

• використано не менше ніж X із N — число ще не звірене з Укрпоштою: кабінет показує оцінку знизу, справжнє може бути більшим. Звірити — пункт «Оновити лічильник» у контекстному меню теки.
• Коли до межі лишається менше 50 місць, рядок такої теки в дереві підсвічується оранжевим, а адміністраторам підключення (той самий список, що для алертів у налаштуваннях підключення) раз на тиждень іде лист-попередження. Платити за це нічого не треба — це не рахунок, а операційна межа Укрпошти.
• Закриті, сховані й заархівовані теки не підсвічуються: їхній лічильник заморожений назавжди, і зробити з цим уже нічого не можна — підпис на них лишається, а сигнал ні. Якщо така тека вже поїхала у згорнутий рядок «Відправлені», підсвічується сам рядок вузла, щоб лист не приходив про папку, якої на екрані не видно.
• Масовий перенос, який у залишок не влазить, кабінет не почне: перед виконанням він скаже числами (переносите 293, у теці лишилось 62), щоб партія не розсипалась між двома теками посеред операції. Залишок цільової теки видно й у вікні підтвердження переносу.

Що робити, коли місце скінчилось: створювати нові ТТН в іншій теці або завести нову. Нерозкладені ТТН кабінет перекладає в наступну теку сам, коли місце в поточній закінчується — уже створені ТТН при цьому нікуди не подінуться й лишаються в старій теці.

Імпорт-звірка за період

Згорнута панель над деревом на сторінці «Мої ТТН»: підтягує позакабінетні ТТН зі зміненою ціною у відділенні за вказаний період у дефолтні партії.

Журнал друку

Меню: Відправлення → Журнал друку (/app/print-journal) — історія друку, повторний друк і масове завантаження наклейок одним архівом.

Виклики кур'єра

Меню: Відправлення → Виклики кур'єра (/app/courier).

Реєстр замовлених заборів: номер замовлення, відправник, дата й інтервал приїзду (09:00-12:00, 12:00-15:00, 15:00-18:00). Дату приїзду кабінет класифікує сам і показує бейджем — «Приїзд сьогодні», «Незабаром приїзд кур'єра», «У минулому». Сам виклик замовляється з контекстного меню теки на сторінці «Мої ТТН»; тут — список того, що вже замовлено.

8. Масове створення ТТН

Меню: Відправлення → Мої ТТН → Імпорт (/app/ttn/import).

Для тижневих партій зручніше завантажити файл, ніж вводити ТТН по одній:

1. Підготуйте CSV або XLSX зі списком відправлень.
2. Завантажте файл, зіставте колонки з полями ТТН.
3. Перегляньте прев'ю з валідацією — система підсвітить помилкові рядки.
4. Підтвердьте — кабінет створить усю партію пакетом і запропонує друк наклейок.

Чекаут → ТТН

Меню: Відправлення → Чекаут → ТТН (/app/ttn/checkout).

Сюди лягають записи, які покупці зібрали самі на хостованому чекауті: обране відділення чи адреса, контакти, характеристики вантажу. На сторінці їх можна відредагувати поодинці або пачкою, а тоді згенерувати ТТН масово — партіями до 500 записів, із результатом Укрпошти по кожному рядку окремо. Розділ доступний ролі Manager і вище — тобто саме тим, хто масову генерацію й робить. Як увімкнути сам чекаут — див. розділ 11.

9. Гроші: баланс, ліміти, рахунки

Розділ меню Гроші.

• Підсумки за період (/app/dashboard) — зведення по відправленнях: скільки ТТН створено, як вони розкладені за статусами, скільки грошей у контурі (вартість доставки, післяплата) і динаміка за обраний період. Це оглядовий екран стану справ, а не операційний список — за конкретною ТТН ідіть у Пошук чи Мої ТТН. Тут же — звіт про нараховане Укрпоштою за період (скільки коштувала доставка ТТН, створених за проміжок, у розрізах за відправником, тарифом і партією), з вивантаженням CSV для звірки з рахунком; окремою сторінкою він не живе.
• Мій план (/app/balance) — єдиний екран про оплату підключення: скільки ви платите і що за це отримуєте. Зверху — відповідь однією стрічкою плиток: чинний пакет лояльності й ефективна ціна за право (ТТН), поточний баланс і прогноз, на скільки вистачить прав за темпом ваших відправлень, залишок безкоштовної місячної квоти, статус кредиту та ліміт боргу. Нижче — дії оплати, картка пакета лояльності, отримувачі сповіщень, блок «Останні рахунки» (три найновіші виставлені/оплачені рахунки з посиланням на повний перелік у Рахунки), а історія операцій підключення — деталізацією в самому низу. Самі реквізити платника екран не дублює (їх формує сервер у PDF рахунку): на них веде посилання «Реквізити платника — у профілі» (юрособи-платники живуть у профілі, розділ 3). Поповнення карткою (LiqPay) відкриває інлайн-форму з кількістю прав і показує суму до сплати (база без ПДВ, ПДВ зверху і разом — той самий розклад, що у формі рахунку) ще до переходу на платіжний хост. Кнопку картки видно лише коли оплату карткою ввімкнено рішенням (cardPaymentsEnabled) — наразі вона тимчасово вимкнена до підключення пРРО, тож поки що баланс поповнюється лише безготівковим переказом за рахунком.
• Рахунки (/app/invoices) — сформувати рахунок на оплату з нашими реквізитами, для оплати банківським переказом від юрособи. Номер рахунку наскрізний за рік (UP-РРРР-######). Платником у рахунку виступає юрособа з вашого профілю (розділ 3).
• Післяплата — гроші (/app/postpay-money) — перекази накладених платежів від Укрпошти: що очікує виплати, що виплачено, затримано чи повернуто, з контрольними сумами у гривнях і експортом у XLSX.

Сповіщення про закінчення лімітів. Якщо передоплаченого або кредитного ліміту вистачає менш ніж на тиждень, кабінет надішле сповіщення (BalanceLow) — щоб ви встигли поповнити рахунок до зупинки відправлень.

Ліміт боргу підключення (= розмір останнього поповнення). Скільки прав підключення може піти в мінус, обмежено розміром вашого останнього поповнення (а якщо бухгалтер виписав кредит — більшим із двох). Правило словами:

• поки платежів не було, ліміт дорівнює нулю: після безкоштовної квоти працює лише передоплата — перша оплата відкриє ліміт, і він дорівнюватиме розміру поповнення;
• якщо наступне поповнення менше за попереднє, ліміт знижується разом із ним (ліміт може падати вниз);
• поточний ліміт і залишок до зупинки видно окремою плиткою на сторінці Мій план.

Коли ліміт вичерпано, створення чергової платної ТТН відхиляється з підказкою поповнити баланс: сформуйте рахунок у Рахунки і сплатіть переказом від юрособи. (Це окремо від глобального анти-abuse обмеження сервісу, яке діє понад цей ліміт.)

Строк зарахування оплати — вручну, 1–2 робочі дні. Права зараховуються не миттєво: після переказу бухгалтер звіряє платіж і зараховує його на баланс вручну, зазвичай протягом 1–2 робочих днів. До моменту зарахування баланс не змінюється, тож плануйте поповнення заздалегідь. Той самий строк ви бачите у формі виставлення рахунку та в листі, до якого додано PDF рахунку.

Що блокується, поки запас прав вичерпано, і що лишається доступним. Коли запас прав (баланс плюс ліміт боргу) вичерпано, кабінет призупиняє лише активаційні дії: друк наклейок і форм, формування реєстру, закриття партії та виклик кур'єра. Решта працює як звичайно — створення й видалення ТТН, довідники адрес і саме поповнення (щоб ви могли виставити й сплатити рахунок навіть у цьому стані). Блок знімається автоматично: щойно оплату зараховано на баланс, активаційні дії відновлюються самі — окремо розблоковувати нічого не потрібно.

Повернення квоти й грошей при видаленні ТТН. Якщо видалити ТТН до її відправлення, кабінет повертає і гроші, і слот безкоштовної місячної квоти — але із застереженнями:

• слот повертається лише для ТТН, створеної в поточному обліковому періоді підключення;
• і лише якщо ця ТТН рухала лічильник квоти: ТТН, підтягнуті обходом реєстру Укрпошти, слот не повертають;
• коли квоту вже вичерпано, повертаються лише гроші за платну ТТН (сторнується списання), а безкоштовна ТТН, видалена в цей момент, не повертає ні грошей, ні слота.

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

Купити пакет можна двома способами:

• «Купити пакет» — оплата карткою через LiqPay. Наразі кнопка неактивна: оплата карткою вимкнена до підключення пРРО.
• «Виставити рахунок» — безготівковий переказ від юрособи. Кабінет одразу видає рахунок з нашими реквізитами (той самий наскрізний номер UP-РРРР-###### і той самий розділ Рахунки, звідки його можна завантажити PDF або надіслати на пошту). Ціну пакета підставляє кабінет — вручну її не вводять.

Кілька важливих деталей:

• у картці видно чинний пакет і чинну ціну за ТТН з урахуванням знижки — це число рахує сервер, звірятися варто саме з ним;
• пакет, який не додає вигоди (такий самий або слабший за вже активний), купити не можна: кнопки для нього неактивні, а спроба відхиляється;
• другий рахунок на пакет кабінет не виставляє, доки перший не оплачено чи не скасовано, — і це стосується не лише того самого пакета, а будь-якого: за раз по підключенню може висіти рівно один неоплачений рахунок на пакет. Кнопка пакета, по якому рахунок уже виставлено, показує «Рахунок виставлено» й неактивна (якщо неоплачених рахунків у вас багато, ця підказка може й не з'явитися — тоді виставлення просто відхилиться помилкою, яка назве вже виставлений пакет; заборона діє однаково). Оплатіть цей рахунок або скасуйте його в розділі Рахунки — оплатити два рахунки на пакети однаково не вийде: знижка вмикається один раз, тож другий переказ довелося б повертати;
• знижка вмикається не в момент виставлення рахунку, а після зарахування оплати — у той самий строк 1–2 робочі дні, що й поповнення балансу; щойно пакет активовано, на адреси кабінету (власник підключення та отримувачі сповіщень) надходить лист про активацію знижки;
• прав на баланс пакет не нараховує: він здешевлює майбутні покупки прав, а не замінює їх;
• уже виставлені рахунки пакет не змінює: у кожного рахунку ціна права зафіксована снапшотом на момент виставлення.

Тарифну модель (безкоштовна квота плюс ціна за відправлення понад квоту) описано на лендингу в розділі Тарифи.

10. Відстежити й розслідувати

Розділ меню Відстежити й розслідувати — трекінг, обзвон і розшук для кол-центру.

• Пошук (/app/shipments) — єдина точка входу за штрихкодом (ШКІ), UUID відправлення або телефоном: кабінет сам розпізнає ввід і веде за призначенням (картка ТТН, картка номера або сирі дані Укрпошти для чужої/історичної ТТН). Докладно — розділ 6.
• Сповіщення (/app/alerts) — те, на що кабінет звертає увагу сам, зібране в робочу чергу обзвону. Задачі розкладені по типах, і зверху стоять чипи-фільтри з лічильниками: «Обдзвонити» (нагадати отримувачу про забір), «Повернення почалося», «Забрати повернення» (повернення вже на відділенні відправника), «Немає руху» (ТТН завмерла) і «Прострочене зберігання» (сплив строк, можлива втрата). Поряд — пошук по штрихкоду. У кожному рядку видно отримувача з телефоном (клік дзвонить), штрихкод веде в картку ТТН, а дедлайн підсвічується червоним, коли він сьогодні або вже прострочений. Рядки можна позначити галочками й закрити пачкою — «Виконано для позначених» або «Відхилити позначені» (за раз — до 200). Готовий список на обзвон із дедлайнами живе в режимі «Горить зберігання» на сторінці «Мої ТТН», і саме там його експортують у XLSX (телефон, опис, дата відправки, дедлайн); проблеми з підключенням і межа ліміту теки теж приходять сюди.
• Кейси (/app/cases) — кейси, з якими менеджер ще працює: Відкрито, В роботі, Очікує Укрпошту. Вирішені й відхилені живуть на тій самій сторінці окремим підвидом, щоб не змішувати робочу чергу з архівом. У картці кейса, прив'язаного до локальної ТТН, є «Експортувати доказ (ZIP)» — пряма вигрузка доказового пакета по цій ТТН без передперегляду: якщо претензія по ній уже є, кнопка перезавантажує її наявний пакет, а формує новий тільки тоді, коли претензії ще немає. Передперегляд того, що увійде в пакет, живе на дії «Претензія / розшук» (див. розділ про картку ТТН).
• Повернення (/app/returns) — дашборд повернень із трьох секцій у фіксованому порядку: «Їдуть як повернення», «Чекають на відділенні» та «Забрані відправником». Для кожної секції — лічильник, контрольна сума накладеного платежу та Σ оголошеної вартості; список під ним показує рівно ті ТТН, що в лічильнику, а порожня секція лишається видимою з нулями. Що означає кожна секція і що дає її експорт — нижче, у підрозділі про три секції.
• Історія розслідування (/app/investigations/timeline) — наскрізний таймлайн по ТТН: події трекінгу, картка номера телефону з історією, зібрані докази (сирі відповіді Укрпошти й хеш-ланцюг) і бланк претензії. Сюди ведуть кнопки історії зі списку «Мої ТТН», картки ТТН і картки номера — це слідча картка одного відправлення.
• Технічний журнал (/app/investigations) — технічний аудит-журнал підключення: службові HTTP-запити до Укрпошти й події кабінету з хеш-ланцюгом (tamper-evident журнал-доказ). Це не таймлайн однієї ТТН, а наскрізний технічний лог — джерело доказів для розшуку й розбору інцидентів на рівні всього підключення.

Три секції екрана «Повернення»

• «Їдуть як повернення» — ТТН ще в дорозі назад до відправника.
• «Чекають на відділенні» — повернення вже прибуло у відділення (ВПЗ), але відправник його ще не забрав. Це ті самі посилки, яких раніше на дашборді взагалі не було видно: їхній статус трекінгу — у відділенні або на зберіганні, а не повернуто, тож у жодну групу повернення вони не потрапляли.
• «Забрані відправником» — повернення вже вручено відправнику. Різниця з попередньою секцією практична: «Чекають на відділенні» — це список на обзвон і забір (гроші й посилки ще у пошти), а «Забрані відправником» — уже закритий цикл.

Пошук на сторінці звужує лише список на екрані: експорт у XLSX завжди вивантажує всю секцію цілком, незалежно від того, що введено в пошук. Для секції «Чекають на відділенні» книга — це робочий список на забір: коли повернення прибуло у ВПЗ, скільки днів воно там лежить, ВПЗ та його індекс, звідки повертається (індекс і назва відділення, з якого стартувало повернення) та причина повернення, отримувач із телефоном, вкладення, гроші й дати таймлайну; відсортовано так, що найдовше лежачі — згори. Решта секцій дають базовий набір колонок.

Вкладка «Вхідні виклики»

Технічний журнал має окрему вкладку «Вхідні виклики» — стрічку невдалих запитів, які до вашого кабінету надсилають зовнішні системи. Це дзеркальний бік решти журналу: там зібрані виклики, що кабінет робить до Укрпошти, а тут — те, що інші стукають у ваш API і чому дістають відмову. У стрічці видно джерело кожного вхідного виклику:

• інтеграції за ключем — публічний API v1 під заголовком X-Api-Key;
• виклики з вбудованого MCP-сервера — але тільки збої самого підключення до нього (відмова ключа, вичерпаний ліміт сесії, зіпсований запит). Провал окремого інструмента MCP сервер повертає помилкою у тілі успішної HTTP-відповіді, тому в цій стрічці його не буде; шукайте такий випадок у вкладці «HTTP-виклики» — виклики до Укрпошти, які інструмент устиг зробити, там видно;
• анонімні колбеки (вебхуки без ключа);
• сам кабінет за токеном сесії (JWT).

Кожен рядок несе джерело, метод, HTTP-статус і машинний код помилки. З деталі вхідного виклику можна перейти до породжених ним викликів до Укрпошти й повернутися назад — так видно весь ланцюг: що саме зовнішня система попросила і що з того пішло в Укрпошту.

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

У деталі кожного запису є заголовок відповіді X-Request-Id. Інтегратор може назвати цей ідентифікатор у зверненні до підтримки: за ним піднімається і сам вхідний виклик, і все, що він породив в Укрпошті.

11. Інтеграція через API

Кабінет надає публічний API /api/v1, щоб ваша система — магазин, ERP, склад — створювала ТТН, забирала наклейки й рахувала вартість доставки без участі людини. Це має сенс тим, хто відправляє щодня й не хоче переносити замовлення руками; якщо у вас кілька ТТН на тиждень, інтерфейсу кабінету цілком достатньо.

Випуск ключа

Меню: Інтеграції → API-ключі (/app/apikeys), кнопка «Випустити ключ». Пункт меню видно лише ролям Owner і Admin.

Ключ (upk_…) прив'язаний до конкретного підключення й має набір скоупів: read — читання (список і картка ТТН, розрахунок вартості, наклейки, форми); write — створення ТТН і груп (містить read); manage — повний ланцюг, тобто редагування й скасування ТТН, закриття реєстру, виклик кур'єра, повернення (містить write). Скопіюйте значення одразу — воно показується лише при випуску.

Кожен запит авторизується заголовком X-Api-Key. Машиночитана специфікація доступна анонімно за GET /openapi/v1.json.

Де читати далі

Перелік ендпоінтів, скоупи, приклади коду й вебхуки цей посібник свідомо не дублює — вони живуть в одному місці й оновлюються разом з API: API quickstart для розробників та файл docs/public-api.md у репозиторії. Швидкий старт із прикладами відкривається також просто в кабінеті на сторінці «API-ключі».

Замість опитування статусів можна підписатися на вебхуки зміни статусу ТТН — як їх підключити, описано там само.

Хостований чекаут

Меню: Інтеграції → Хостований чекаут (/app/checkout-links). Пункт меню видно лише ролям Owner і Admin.

Хостований чекаут — сторінка, на якій покупець сам обирає відділення або адресу доставки, а ви не будуєте цю форму у себе. Тут випускаються й відкликаються checkout-посилання підключення (незмінний шаблон /checkout/{publicToken}) і ведеться allowlist доменів повернення. Саме підписане посилання (вантаж, адреса повернення, підпис) будує ваша інтеграція. Зібрані записи далі обробляються в розділі «Чекаут → ТТН» (розділ 8).

12. Ролі та спільний доступ

Меню: Налаштування → Доступ (/app/access). Пункт меню видно лише ролям Owner і Admin.

Підключення можна розшарити на кількох користувачів за ролями:

• Owner / Admin — повне керування, зокрема API-ключі, хостований чекаут і доступ інших користувачів.
• Manager та інші ролі — робота з ТТН, чекаутом і кур'єром без доступу до чутливих налаштувань.

Чутливі пункти меню — «API-ключі», «Хостований чекаут», «Доступ» — приховані від користувачів без прав керування. Решта пунктів видима всім ролям.

Окрема роль Бухгалтер (Accountant) має крос-тенантний бек-офіс білінгу — пункт «Білінг».

Другий пункт бухгалтера — «Неоплачені рахунки»: спільна черга виставлених рахунків з усіх підключень, найстаріші зверху (поруч із датою виставлення показано вік у добах). Фільтр статусу за замовчуванням — щойно виставлені; пошук — за email власника підключення. Позначити рахунок оплаченим можна прямо з рядка: відкриється те саме вікно, що й на картці підключення (дата платежу та примітка), після чого права зараховуються на баланс, а власник отримує лист про поповнення. Назва підключення в рядку веде на його картку в білінгу.

Питання щодо ключів і договору — до персонального менеджера відділу B2B Укрпошти (старт: dev.ukrposhta.ua/for-business). Питання щодо самого кабінету — через Налаштування → Підтримка.