Посібник користувача — Кабінет 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 або VALUABLE_LETTER.
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-РРРР-######; платником виступає юрособа з вашого профілю.

Неочевидність 4. «Цінний лист» має фіксовані правила

«Цінний лист» (VALUABLE_LETTER) — окремий тарифний тип із жорсткими правилами Укрпошти: оголошена вартість завжди 500 ₴, опис вкладення (ф.107) обов'язковий, а накладений платіж недоступний. У формі створення кабінет підставляє ці обмеження сам: щойно ви оберете тип «Цінний лист», поле оголошеної вартості стає 500 ₴ і доступне лише для читання, опис вкладення вмикається примусово (створити ТТН без жодної позиції опису не вийде), а поле накладеного платежу зникає. Спроба відступити від цих правил впала б на боці Укрпошти (UPE02000 — вартість ≠ 500, UPE01002 — без опису вкладення).

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) та орієнтовний обсяг відправлень.
• Куди звертатися — стартова точка й порядок укладення договору на порталі розробника Укрпошти (розділ для бізнесу).

Webhook-сповіщення про зміну статусу

На картці підключення можна зареєструвати webhook — URL, на який кабінет надсилатиме сповіщення про зміну статусу ваших ТТН, щоб ваша система не опитувала API вручну. Для цього потрібен Bearer StatusTracking: без трекінгу джерела зміни статусу немає.

У списку підписок показано і чинний endpoint, і раніше вимкнені. Над активним доступні три дії: «Редагувати» — змінити URL (підписний секрет при цьому лишається незмінним); «Ротувати секрет» — видати новий секрет замість чинного; «Деактивувати» — вимкнути доставку сповіщень. У вікні редагування є перемикач «Активна»: знявши його й зберігши, ви вимикаєте доставку, а повернувши — вмикаєте назад (активним може бути лише один endpoint, тож увімкнення гасить попередній).

Неактивну підписку теж можна відкрити — кнопкою «Увімкнути» поряд із її рядком. У тому самому вікні ви за потреби правите URL і ставите перемикач «Активна», тож змінити адресу й повторно увімкнути підписку можна одним збереженням; секрет при цьому не змінюється. Формат payload і перевірку підпису цей посібник не дублює — вони живуть в API quickstart для розробників (розділ 11).

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

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

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

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

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

Працює це так: друга адреса чіпляється до тієї самої картки відправника, і накладна починає нести її як адресу повернення, тоді як адреса відправлення лишається старою. Штрихкод, відправник і тека при цьому не змінюються (замір на обох контурах — docs/api-map.md).

Дві межі, про які варто знати:

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

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

Зайву додаткову адресу можна прибрати кнопкою «Відв'язати адресу» поруч із нею (кабінет перепитає підтвердження). Головну адресу — адресу відвантаження — відв'язати не можна, тож кнопки на ній немає: картка клієнта завжди мусить мати хоча б адресу відправлення.

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

Перевірити, куди поїде повернення конкретної накладної, можна в її картці: секція «Куди і кому», рядок «Адреса повернення». Саме цю адресу Укрпошта друкує в полі Від: наліпки (не адресу відвантаження). Якщо вона збігається з адресою відправлення, під нею стоїть позначка збігається з адресою відправлення.

Кілька відправників з одним телефоном (інший індекс відвантаження)

Якщо змінити треба саме адресу відвантаження, то це вже другий відправник: та сама фірма з іншим індексом відправлення — окрема картка.

За замовчуванням кабінет упізнає відправника за телефоном (а якщо заданий — за зовнішнім ID) і повторної картки не заводить: це захист від випадкових дублів. Якщо в такому стані натиснути кнопку створення, кабінет не додасть новий рядок, а оновить наявний і прямо про це скаже.

Щоб усе-таки завести окремого відправника з тим самим телефоном, увімкніть у формі створення «Створити окрему картку в Укрпошті» — тоді пошук наявного пропускається, в Укрпошті створюється окрема картка зі своєю адресою, і в книзі з'являється другий рядок. Далі призначте його основним, і нові накладні підуть уже з новим індексом; раніше створені ТТН лишаються зі старим.

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

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

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

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

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

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

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

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

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

Передперевірка відділення одержувача

Коли ви обираєте відділення одержувача, кабінет звіряє його з довідником Укрпошти ще до відправки й показує три перевірки прямо у формі, щоб не ганяти ТТН на відмову:

• Пересувне відділення (ПВ) при доставці на склад. У пересувного ВПЗ фіксованої точки видачі немає, тож Укрпошта автоматично змінює доставку зі складу на адресу (W2W → W2D). Форма це передбачає: щойно обрано пересувне ВПЗ одержувача, поруч з'являються обов'язкові поля Вулиця та Будинок (позначені зірочкою), а кнопка «Створити ТТН» лишається неактивною, доки їх не заповнено.
• Закрите вантажне відділення. Відділення з обмеженим доступом у переліку показано, але обрати його не можна — поруч стоїть пояснення причини. Адресувати на нього ТТН Укрпошта не дозволяє.
• Ліміти підтипу відділення. Якщо вага місця, габарити, оголошена вартість, наявність післяплати чи кількість місць перевищують те, що приймає обране відділення, форма показує блокуюче застереження (кнопку створення вимкнено). Можливе перевищення об'єму показано як м'яке попередження — створення не блокує, бо одиниця виміру в довіднику не уточнена.

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

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

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

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

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

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

Попередження про ймовірний дубль

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

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

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

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

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

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

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

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

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

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

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

Коли до ТТН замовлено зворотну доставку документів (є зворотна накладна), у рядку списку поруч із кнопкою друку наклейки зʼявляється компактне меню «Друк» із двома пунктами зворотної наклейки: «Друк ТТН+докбек» — один PDF із наклейкою ТТН і зворотною document-back разом (для першого друку), та «Друк зворотної (докбек)» — лише зворотна наклейка окремим PDF, для передруку, якщо зворотна наклейка загубилась або зіпсувалась. Обидва пункти показуються тільки коли зворотна накладна вже має штрихкод.

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

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

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

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

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

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

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

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

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

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

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

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

Фільтр за датою створення

Над списком, поруч із рештою фільтрів, стоять два поля дати — Створено від і до. Вони звужують список до ТТН, створених у заданому проміжку: межі включні, а доба рахується за київським часом (не за UTC), тож період з 1-го по 1-ше число охоплює весь той день цілком. Фільтр діє наскрізно, як пошук: звужує і плоский список, і дерево тек, і експорт CSV/XLSX, і вибір усього за фільтром — масова дія бере рівно ТТН цього періоду. Активний діапазон живе в адресі сторінки (параметри ?from / ?to), тож переживає перезавантаження й кнопку Назад; хрестик поруч скидає обидві межі.

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

Фільтр за типом відправлення

Поруч із рештою фільтрів стоїть селектор «Тип відправлення» — тарифний клас ТТН (Базовий, Пріоритет, Документ, Вантаж, Цінний лист); перший пункт усі типи знімає звуження. Вибір типу звужує список на сервері — це не клієнтський зріз видимих рядків, а серверний фільтр, тож під типом видно ТТН з усіх сторінок і партій одразу. Фільтр діє наскрізно, як пошук: згортає дерево тек у плоский список, звужує й вибір усього за фільтром (масова дія бере рівно ТТН цього типу). Обраний тип живе в адресі сторінки (параметр ?type), тож переживає перезавантаження й кнопку Назад.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Фонові задачі над ТТН: перенос і видалення великих партій

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

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

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

Щоб на самій сторінці «Мої ТТН» було видно, що перенос почався, над списком висить банер Йде перенос N/M у теку „назву" (N — скільки ТТН уже оброблено, M — усього; для кількох завдань — Йде перенос: K завдань, залишилось R ТТН). Банер показує лише завдання поточного підключення і зникає, щойно їх не лишилось. Кнопка «Показати» відкриває те саме вікно прогресу, що й клік по індикатору в шапці.

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

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

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

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

Фонова розкладка великої партії по теках

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

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

Фонові масові повернення

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

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

Фонове створення ТТН з імпорту і масове дублювання

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

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

Обидва види підпорядковані правилу „одна активна фонова задача на підключення": поки по підключенню працює будь-яке фонове завдання (перенос, видалення, повернення, перетарифікація, розкладка, імпорт чи дублювання), наступне в роботу не береться — щоб види не конкурували за квоту Укрпошти одного тенанта. Спроба завести друге завдання поверне зрозумілу відмову, а не почне його нишком.

«перевіряємо розміщення в Укрпоші»

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

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

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

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

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

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

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

Масова зміна відправника

Поруч зі зміною тарифу в панелі виділення є список «Змінити відправника…» — оберіть нового відправника з книги відправників і натисніть «Змінити відправника». Кожна обрана ТТН переїде в дефолтну папку обраного відправника; штрихкод не зміниться.

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

Великі партії йдуть у фон — так само, як зміна тарифу: понад поріг сервера кабінет заводить фонове завдання Зміна відправника й показує вікно прогресу (індикатор «Фонові задачі», мітки на рядках в черзі на зміну відправника, «перевіряємо», відправника змінено або помилка: причина). Якщо адміністратор тимчасово вимкнув зміну відправника, кабінет не заводить ні синхронну, ні фонову зміну: спроба одразу повертає відмову з поясненням (окремої кнопки-гейта в інтерфейсі немає — рішення про доступність осі приймає сервер).

Масова зміна адреси повернення

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

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

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

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

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

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

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

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

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

Секція вантажу вікна «Редагувати ТТН» працює й для багатомісної ТТН: у ній правляться вага, габарити й оголошена цінність кожного місця окремо (обмеження одномісного редагування знято). Тут же для кожного місця правляться «Вартість пакування, ₴» і «Матеріал пакування (KMAT)», а спільний для всієї ТТН перемикач «Пакування сплачує» — хто несе вартість пакування (відправник чи одержувач). Для тарифу «Вантаж» (CARGO) ці поля неактивні. А от додати чи видалити місце і змінити опис вкладення (форма 107) у цій секції не можна — це робиться окремим вікном за кнопкою «Складові посилки» (керування місцями багатомісної ТТН).

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

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

Тип виклику — масовий чи одиночний. Укрпошта розрізняє два забори, і кабінет сам обирає потрібний за набором обраних ТТН та показує його на кроці підтвердження. «Масовий забір» — складська доставка (W2W/W2D) від 10 ТТН; якщо придатних менше, вікно підказує, скільки ТТН іще бракує. «Одиночний забір» — доставка від дверей відправника (D2W/D2D) від 1 ТТН, без такого мінімуму. Набір, у якому змішані дверні й складські ТТН, одним викликом не приймається — вікно пропонує замовити забір окремо для кожного типу. Обраний тип видно й після замовлення — окремою колонкою «Тип» у реєстрі та рядком у картці заявки («Масовий забір» / «Одиночний забір»). Давні заявки, замовлені до появи цього поля, показують у колонці «—» — тип по них кабінет не зберіг і не відновлює з API.

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

Якщо забір більше не потрібен або дата змінилась. Кабінетного шляху тут немає — жодна кнопка не допоможе, бо скасування/перенесення живе на боці Укрпошти поза API. Зв'яжіться з Укрпоштою напряму: гарячою лінією або через вашого B2B-менеджера (той самий, що видавав ключі за договором). Про саму проблему в кабінеті можна написати через Підтримка — але скасувати чи перенести виклик там теж не вийде, звернення лише зафіксує ситуацію для нашої команди.

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 журнал-доказ). Це не таймлайн однієї ТТН, а наскрізний технічний лог — джерело доказів для розшуку й розбору інцидентів на рівні всього підключення.

Вкладення до нотаток кейса. У картці кейса до нотатки (кнопка «Додати нотатку») можна прикріпити файли — зображення (JPEG, PNG, WEBP) або PDF, до 5 МБ кожен і до 10 на одну нотатку. Тип перевіряється за вмістом файлу, а не за розширенням, тож перейменований файл чужого формату кабінет не прийме; завеликий або невідповідний файл відсікається ще у формі, до відправлення. Прикріплені файли показуються під текстом нотатки в таймлайні окремими чипами з назвою й розміром — клік по чипу завантажує файл. Вкладення зберігаються приватно й доступні лише членам підключення кейса (у кабінеті Укрпошти їх немає); видалити вкладення може автор нотатки або учасник із підвищеною роллю (власник/адміністратор) — тим самим правом, що й саму нотатку.

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

Панель «SLA проблемних ТТН»

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

Показники плиток (по обох групах):

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

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

Нижче — розріз за пріоритетом: скільки кейсів кожної пріоритетності (низька, середня, висока) компактними барами; порожній розріз (кейсів у ньому немає) показано прочерком, а не рядом нулів. А під ним — воронка претензій: окремий блок саме про претензії/розшуки (не про кейси, щоб не плутати) — скільки їх на кожному етапі: чернетка, сформовано, подано, вирішено, відхилено. Коли претензій за період немає — теж прочерк.

Сповіщення в Telegram

На сторінці Сповіщення під налаштуванням email-дайджесту може зʼявитися блок «Сповіщення в Telegram». Він видимий лише тоді, коли канал Telegram налаштований адміністратором інсталяції — якщо бот на вашому сервері не піднято, блок просто не показується, і це нормально.

Щоб отримувати сповіщення в Telegram:

1. натисніть «Привʼязати Telegram» — кабінет відкриє бот за персональним посиланням;
2. у боті натисніть Start;
3. поверніться в кабінет і натисніть «Оновити стан» — щойно бот підтвердить привʼязку, замість кнопок зʼявиться бейдж «Telegram привʼязано».

Щоб більше не отримувати сповіщення, натисніть «Відвʼязати». Окремо відкликати згоду і стерти свої дані на боці бота можна прямо в чаті командою /delete_my_data — бот запитає підтвердження й видалить привʼязку та збережені про вас дані.

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

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

Пошук на сторінці звужує лише список на екрані: експорт у 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.

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

Поруч стоїть окремий прапорець «Відхиляти автоматичну зміну доставки на адресну (W2W→W2D)» — він стосується лише цього ключа /api/v1 і за замовчуванням вимкнений. Укрпошта іноді сама переводить доставку у відділення (W2W) на дорожчу доставку до дверей (W2D), коли в населеному пункті немає точки видачі. З увімкненим прапорцем кабінет після створення звіряє фактичний тип із запитаним і, якщо сталася така підміна, відкочує створення помилкою замість того, щоб мовчки віддати дорожчу адресну ТТН. Поки прапорець знято (типово), ТТН створюється з фактичним типом, який повернула Укрпошта, — як і до цього нововведення.

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

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

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

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

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

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

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

⚠ Що змінилось для раніше випущених посилань. Раніше кабінет показував відкликаними всі неактивні посилання — зокрема ті, що просто згасли від випуску наступного. Тепер такі рядки показані призупиненими, і кнопка «Відновити» підніме їх назад із тим самим publicToken: посилання, яке ви колись роздали, знову запрацює. Якщо старе посилання має лишитись мертвим — натисніть «Відкликати», це незворотно.

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

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

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

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

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

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

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

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

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

Під кожним рядком у таблиці «Рахунки підключення» бухгалтер може розгорнути зону «Акти рахунку» (кнопка «Акти» в рядку): тут видно вже прикладені акти — імʼя файлу, розмір і дату, кожен можна завантажити повторно. Кнопка «Завантажити акт» приймає PDF або зображення (скан) розміром до 10 МБ; завелику чи не той тип кабінет відхиляє одразу підказкою, а остаточну перевірку робить сервер. Щойно акт завантажено, він одразу зʼявляється у списку рахунку, а власник підключення бачить той самий акт у себе в розділі Рахунки і теж може його завантажити.

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