Часті питання про роботу з кабінетом

Де взяти ключі для роботи з API Укрпошти?

Ключі видає сама «Укрпошта» після укладення договору на послуги API — це чотири сутності. Обов'язкові: Bearer eCom і counterparty token (у документації Укрпошти він зустрічається також під назвою «user token» — це та сама сутність, а не окремий ключ). Опційні: Bearer StatusTracking (без нього не працює трекінг і все, що з нього походить: статусні алерти, вебхуки зміни статусу, аналітика доставок і повернень) і UUID контрагента. Наш кабінет не видає ключі — ви підключаєте свої власні в налаштуваннях після реєстрації.

Які саме ключі потрібні?

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

Чи існує офіційний кабінет Укрпошти для B2B-відправника?

Ні — станом на 10.08.2026 знайти його не вдалося: у публічній документації Укрпошти інтерфейсу для потокового відправлення не описано, для нього вона віддає лише API (production www.ukrposhta.ua/ecom/0.0.1, sandbox dev.ukrposhta.ua/ecom/0.0.1). Це висновок на дату, а не вічна властивість. Особистий кабінет отримувача й разового відправника — це ok.ukrposhta.ua.

Окремо про «красиві» адреси: kabinet.ukrposhta.ua і ecom.ukrposhta.ua не резолвяться взагалі — замір DNS 10.08.2026 через публічний резолвер 8.8.8.8 дав NXDOMAIN на обох іменах. Цей замір доводить відсутність саме цих двох імен, а не відсутність кабінету за якоюсь іншою адресою. Наш кабінет — незалежний сервіс, що закриває цей проміжок: ви працюєте своїми ключами Укрпошти через зручний інтерфейс.

Чим відрізняються sandbox і prod?

Sandbox (dev.ukrposhta.ua) — тестове середовище: відправлення не тарифікуються й не потрапляють у реальну логістику. Production (www.ukrposhta.ua) — бойове середовище зі справжніми відправленнями та оплатою. У кабінеті можна зберегти обидва набори ключів і перемикатися між ними.

З чого почати?

Радимо спершу підключити sandbox-ключі, створити тестову ТТН і надрукувати наклейку, а після перевірки — додати production-ключі для реальних відправлень.

Як зберігаються мої ключі Укрпошти?

Ключі кожного тенанта зберігаються в базі даних у зашифрованому вигляді й використовуються лише для запитів до API Укрпошти від вашого імені. Ми не показуємо повні значення ключів у чужих сесіях і не передаємо їх третім сторонам.

Наскільки ізольовані дані різних клієнтів?

Кабінет мультитенантний: дані, ключі й відправлення кожного облікового запису ізольовані одне від одного. Вхід — через magic-link на email або Google OAuth.

Як авторизуватись у вашому API?

Використовуйте заголовок X-Api-Key з ключем, згенерованим у кабінеті. Базовий шлях — /api/v1. Ключ прив'язаний до вашого тенанта й відкликається в будь-який момент.

Чи можна отримати список усіх ТТН через API Укрпошти?

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

Чи є ліміти на запити?

Базовий план включає безкоштовну місячну квоту — за акцією 100 ТТН на місяць замість базових 10. Понад неї кожне відправлення коштує 1 ₴ і списується з передоплаченого балансу підключення. Жорстких технічних лімітів на REST API для типового потоку немає; розширені можливості з'являться в платних тарифах — див. сторінку тарифів.

Скільки коштує понад безкоштовну квоту?

За акцією 100 ТТН на місяць — безкоштовно (базовий розмір квоти — 10). Кожне відправлення понад квоту коштує 1 ₴ і списується з передоплаченого балансу підключення. Лічильник квоти скидається щомісяця (UTC). Детальніше — на сторінці тарифів.

Як інтегрувати кабінет із моєю системою через API Укрпошти?

Випустіть у кабінеті ключ X-Api-Key на вкладці «API-ключі» й звертайтесь до REST API за базовим шляхом /api/v1: створення ТТН — POST /api/v1/shipments, PDF-наклейка — GET /api/v1/shipments/{id}/sticker, статус трекінгу — GET /api/v1/shipments/{id}. Скоупи read, write і manage обмежують права ключа. Покрокова інструкція — у розділі «Власний REST API» на сторінці можливостей.

Де взяти OpenAPI-специфікацію?

Машиночитана OpenAPI-специфікація доступна анонімно за адресою /openapi/v1.json — з неї генерують клієнт (інтерактивного Swagger-UI немає). Для LLM-агентів і асистентів є короткий покажчик /llms.txt із посиланнями на специфікацію та документацію.