# Кабінет B2B відправника Укрпошти (неофіційний)

> Незалежний мультитенантний SaaS-кабінет для B2B-відправників Укрпошти. Не є офіційним сайтом АТ «Укрпошта» і не афілійований з нею. Весь цикл роботи з відправленнями — створення ТТН, реєстри (групи), друк наклейок і форм, розрахунок вартості та відстеження статусів — доступний як людині в кабінеті, так і програмно через власний REST API. Кабінет керований програмно: цей файл допомагає LLM/агентам знайти специфікацію та зрозуміти модель роботи.

## API

Повна машиночитана специфікація (OpenAPI 3): [OpenAPI v1](https://ukrposhta.main.fish/openapi/v1.json)

Каталог API (RFC 9727 linkset): [api-catalog.json](https://ukrposhta.main.fish/.well-known/api-catalog.json)

Модель роботи:

- Базовий шлях усіх ендпоінтів — `/api/v1` (напр. `https://ukrposhta.main.fish/api/v1/shipments`).
- Авторизація — ключ у заголовку `X-Api-Key` (без нього — 401). Ключ прив'язаний до підключення (тенанта) і має скоуп `read`/`write`/`manage` (ієрархія: manage ⊃ write ⊃ read).
- Ключ API цього кабінету генерується самим користувачем у кабінеті після реєстрації. Це НЕ ключі самої Укрпошти: ключі до API Укрпошти видає B2B-менеджер відділу продажів Укрпошти за договором, і вони підключаються в кабінеті окремо.
- Ключі Укрпошти (підключаються окремо) — це чотири сутності: обов'язкові `Bearer eCom` (заголовок `Authorization: Bearer` для всіх eCom-ендпоінтів) і `counterparty token` (передається як query `?token=`; у документації Укрпошти зустрічається також під назвою «user token» — це ОДНА сутність під двома іменами, а не два ключі); опційні `Bearer StatusTracking` (єдиний вхід для трекінгу: ТТН, реєстри й наклейки без нього працюють, але відпадають статусні алерти, вебхуки зміни статусу, аналітика доставок і повернень та докази статусу для претензій) і `UUID контрагента` (не ключ доступу, а ідентифікатор контрагента: у специфікації зустрічається лише як поле тіла `counterpartyUuid`; кабінет працює без нього — форма підключення позначає його опційним, і в запити до API клієнт його не підставляє; єдине видиме місце — друкована заява на розшук). Counterparty token (`?token=`) і UUID контрагента (`counterpartyUuid` у тілах) — різні речі. У шляхах на кшталт `/clients/{uuid}` стоїть uuid клієнта-відправника, а не контрагента.
- Відповіді — JSON; друковані форми (наклейки, реєстри, описи, акти) — PDF.

## Ключові операції

- `POST /api/v1/shipments` — створити ТТН (без `groupId` потрапляє в дефолтну групу «Різне»).
- `POST /api/v1/shipments/batch` — bulk-створення N ТТН одним запитом, поелементний результат.
- `GET /api/v1/shipments` — список ТТН (наш реєстр), фільтр за `groupId`, пагінація `offset`/`limit`.
- `GET /api/v1/shipments/{id}` — одна ТТН разом із поточним статусом доставки (трекінг).
- `PUT /api/v1/shipments/{id}` — редагувати ТТН; `DELETE /api/v1/shipments/{id}` — скасувати.
- `POST /api/v1/shipments/price` — розрахунок вартості доставки (delivery price).
- `GET /api/v1/groups`, `POST /api/v1/groups`, `POST /api/v1/groups/{id}/close` — групи/реєстри (папки відправлень; закриття фіналізує партію).
- `POST /api/v1/shipments/{id}/postpay`, `.../recipient`, `.../return-order` — операції над ТТН (накладний платіж, отримувач, повернення).
- `POST /api/v1/courier/orders` — виклик кур'єра.

## Довідник адрес (read)

Окрема здатність: власна копія довідника адрес України (області, населені пункти, вулиці, відділення), яку кабінет роздає програмно. Читається з нашого зліпка — запити до самої Укрпошти тут не йдуть, тож ці виклики не залежать від доступності її API.

- `GET /api/v1/address/regions` — області.
- `GET /api/v1/address/cities` — населені пункти (звуження `regionId`/`districtId`, префіксний пошук `q`).
- `GET /api/v1/address/streets` — вулиці населеного пункту (`cityId` обов'язковий).
- `GET /api/v1/address/postoffices` — відділення (ВПЗ) населеного пункту (звуження `cityId` **або** `index`).

Кожна відповідь віддається з міткою свіжості `syncedAt` (коли шар копії востаннє проходився повністю) та атрибуцією джерела `source` — дані походять із довідника Укрпошти. Ідентифікатори — з продакшен-простору Укрпошти (у sandbox простір id інший).

## Друковані форми (PDF)

- `GET /api/v1/shipments/{id}/sticker`, `GET /api/v1/groups/{id}/sticker` — наклейки; `size=A4|A5|A6` (за замовчуванням термонаклейка A6 100×100).
- `GET /api/v1/groups/{id}/registry` — реєстр групи, форма 103.
- `GET /api/v1/shipments/{id}/form119`, `GET /api/v1/groups/{id}/form119` — опис/повідомлення, форма 119.
- `GET /api/v1/shipments/{id}/form107`, `GET /api/v1/groups/{id}/form107` — опис вкладення, форма 107.
- `GET /api/v1/shipments/{id}/form20` — акт форми 20 (повернення/зберігання).
- `POST /api/v1/shipments/bulk` — масове завантаження набору ТТН у обраному форматі (наклейка → один PDF; ф.119/107/20 → ZIP).

## Публічні документи

- [Кабінет відправника](https://ukrposhta.main.fish/kabinet-vidpravnyka/) — чим цей кабінет B2B-відправника відрізняється від офіційного особистого кабінету Укрпошти (ok.ukrposhta.ua) і кому він потрібен.
- [Можливості](https://ukrposhta.main.fish/mozhlyvosti/) — огляд функцій кабінету та API.
- [Посібник користувача](https://ukrposhta.main.fish/posibnyk/) — покроковий гайд повного циклу роботи з кабінетом (від реєстрації до API).
- [Документація API](https://ukrposhta.main.fish/api-dokumentatsiya/) — quickstart для розробників: ключі, скоупи, приклади коду, вебхуки.
- [Розбір API Укрпошти](https://ukrposhta.main.fish/rozbir-api-ukrposhty/) — першоджерело «твердження → факт → джерело»: скільки ключів насправді, чого API Укрпошти не вміє (немає списку всіх ТТН, видалення групи), індекс зони проти індексу відділення.
- [FAQ](https://ukrposhta.main.fish/faq/) — часті питання.
- [Тарифи](https://ukrposhta.main.fish/tarify/) — модель оплати.
- [Публічна оферта](https://ukrposhta.main.fish/oferta/)
- [Політика конфіденційності](https://ukrposhta.main.fish/pryvatnist/)
- [Умови використання](https://ukrposhta.main.fish/umovy/)