> Усі статті WIKI Helomi: /wiki/llms.txt

# Укрпошта

Інтеграція з Укрпоштою створює відправлення з угоди через eCom API, відстежує їх за API статусів і переводить угоду на етап за статусом доставки. Налаштування повторюють KeepinCRM: кілька акаунтів-відправників, адреси відправника, списки відправлень (реєстри) з формою ф.103А, додаткові послуги, зв'язок статусів і полів угоди.

## Можливості
- Створення відправлень з угоди: відділення або адреса, стандарт чи експрес, післяплата на рахунок або готівкою.
- Трекінг статусів і «Пов'язані статуси» → етап угоди; окремо — з огляду на тип оплати.
- Кілька акаунтів-відправників зі своїми ключами, дефолтами й доступами.
- Адреси відправника і списки відправлень (ф.103А).
- Додаткові послуги: рекомендоване, SMS інформування, крихке, огляд під час вручення, повідомлення ф. 119, що робити, якщо не вручено.

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Укрпошта». Картка відкривається на вкладці «Налаштування»; поруч — «Підключення».

1. **Ключі.** Укрпошта видає окремо доступ до eCom API (створення відправлень) і до API статусів (трекінг). Їх вводять в акаунті (розділ 2: «Bearer», «Bearer StatusTracking», «Токен» контрагента) або у вкладці «Підключення»: «Токен статусів», «eCom токен», «eCom bearer» — діють, коли акаунтів нема. Ключі зберігаються зашифрованими й назад не показуються.
2. **Перевірка.** «Перевірити» в «Підключенні» запитує статус свідомо неіснуючого відправлення: «токен статусів прийнято» означає, що ключ працює. У картці акаунта «Перевірити» читає дані клієнта Укрпошти.
3. **Налаштування.** Блоки: «Інтеграція» («Увімкнути інтеграцію»), «Додаткова інформація» (що писати в полі відправлення: без автогенерації, назва товару, артикул і кількість, назва й кількість, шаблон), «Номер замовлення» (не заповнювати, ID угоди, назва угоди), «Акаунти», «Адреси відправника», «Списки відправлень», «Доступи», «Пов'язані статуси», «Пов'язані типи оплат та статуси», «Пов'язані поля», «Вага й габарити з товарів» (галочка: вага й розмір посилки — з товарів угоди й кількості, а не з акаунта; [докладно](shipping.md#3а-вага-й-габарити-з-товарів-угоди)). Унизу — «Скасувати зміни» / «Зберегти».

## 2. Акаунти, адреси відправника, списки відправлень
**Акаунт** — «Акаунти» → «+ Додати акаунт» → назва → «Додати». Розгорнутий акаунт: «Увімкнено», «Перевірити», «Прибрати акаунт» і групи:
- «Акаунт»: «Назва» — як підписати відправника у списку акаунтів і формі ТТН;
- «Відправник»: «Ім'я відправника», «Тип відправника» (Фізична особа підприємець, Фізична особа, Юридична особа), «Телефон», «Адреса відправника» (з блоку «Адреси відправника»; це клієнт-відправник у кабінеті Укрпошти — з нього беруться ПІБ, IBAN та ІПН, як у KeepinCRM), «Номер банківського рахунку (IBAN)», «ІПН»;
- «Доступ до API»: «Bearer» (eCom API), «Bearer StatusTracking» (API статусів), «Токен» (токен контрагента);
- «Відправлення за замовчуванням»: «Метод доставки» (Склад-Склад, Склад-Двері, Двері-Склад, Двері-Двері), «Тип відправлення» (Укрпошта стандарт / Укрпошта експрес), «Список відправлення», «Платник доставки», «Платник комісії за післяплату», «Післяплата» (На банківський рахунок (IBAN) / Готівкою), «Короткий опис» (опис у відправленні; порожньо — з назв товарів);
- «Додаткові послуги»: «Рекомендоване», «SMS інформування», «Крихке», «Огляд під час вручення», «Повідомлення про вручення ф. 119», «Повернення відправлень» (Повернути; Повернути через 7 календарних днів; Розглянути як відправлення, від якого відмовився відправник);
- «Розмір і вага відправлення».

**Доступи** — блок «Доступи · <акаунт>»: «Показати» тим, хто створює відправлення цим відправником; без галочки акаунта не видно у формі. Адміністратор бачить усі.

**Адреси відправника** — «+ Додати» → «Адреса відправника» (напр. «Україна, 03127, Київ, вул. …») → «Додати». Адреса акаунта вибирається з цього списку.

**Списки відправлень** — створити ТТН без списку неможливо; у списку до 500 ТТН, далі потрібен новий (як у KeepinCRM). «+ Додати» → «Назва списку відправлень» → «Додати». Таблиця: «Назва», «Тип», «ТТН», «Форма ф.103А» (друк, коли форму віддає API). Новий список додається в налаштування й зберігається кнопкою «Зберегти».

## 3. Статуси, типи оплат і поля угоди
- «Пов'язані статуси»: статус відправлення (назва події з API статусів Укрпошти: «Створено», «Відправлення прийняте», «Надходження на сортувальний центр», «Відправлення з сортувального центру», «Відправлення у точці видачі/доставки», «Відправлення вручено», «Відправлення вручено відправнику», «Повернення відправлення» тощо) → етап угоди; без рядка етап не змінюється. Укрпошта в трекінгу пише й інакше («Прийнято», «Прибуло до Логістичного центру», «Прибуло до Сортувального депо», «Прибуло до Відділення», «Вручено Одержувачу», «Повернення. Вручено Відправнику») — назви вище й назви з KeepinCRM («Отримано», «Надійшло у відділення») спрацьовують і на них; під рядком видно, на що саме, а рядок без відповідника позначено.
- **Кожна воронка — свої рядки** (17.10): рядок діє лише на угоди воронки свого етапу (воронку видно біля етапу: «Відправлено [Продажі Каста]»). Посилки цієї служби їздять у кількох воронках — додайте для кожної свої рядки з тими самими статусами.
- **«Скасовані угоди не чіпати»** і **«Не повертати угоду на етап до збірки»** (перемикачі над таблицею, типово ввімкнені, 17.10): скасовану угоду статус посилки не рухає й не закриває «Виграно»; коли посилка вже поїхала, рядки на етапи з роллю «Створено», «Прийнято», «Передали на збірку», «Зібрано», «Допомога» пропускаються — діє наступний рядок.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».
- «Пов'язані типи оплат та статуси»: те саме з огляду на тип оплати; ці рядки головніші.
- «Пов'язані поля»: «Місто», «Поштовий індекс», «Одержувач», «Телефон» — з яких полів угоди брати дані у форму; «Тип отримання грошей» — поле-список угоди і відповідність значень типам оплати.

Етап змінюється, коли оновлюється статус ТТН: фоном (автооновлення нижче, крок ШІ Ростіка) і кнопкою «Оновити статус» у «⋮» рядка ТТН в угоді. ТТН замовлень маркетплейсу, записані службою «ukr_poshta», фон теж опитує (до 17.10 пропускав).

- **Автооновлення й архів отриманих** (над «Пов'язаними статусами»): «Оновлювати статуси ТТН автоматично» кожні N хв (типово так, 30 хв) — статуси відкритих угод оновлюються самі, без кнопки «Оновити статус»; «Посилку отримано → угода «Виграно» в архів» (типово так) — коли перевізник каже «отримано», угода переходить на етап «Виграно» своєї воронки й іде в архів навіть без рядка «Пов'язаних статусів». Відмови й повернення не архівуються.

## 4. Створити відправлення з угоди
Картка угоди → «Доставка» → «+» → «Створити ТТН» → вкладка «Укрпошта» → акаунт → одержувач, індекс відділення або адреса з індексом, вага → «Створити ТТН». Покроково — [Доставки і ТТН](shipping.md).

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

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): UKRPOSHTA_STATUS_TOKEN, …» | Ключі не введено | Введіть ключі в акаунті або в «Підключенні» |
| «HTTP 401» / «HTTP 403» після «Перевірити» | Токен статусів не прийнято | Перевірте токен |
| «Укрпошта: індекс відділення — 5 цифр (наприклад 79000)» | Неправильний індекс | Виправте індекс |
| «Укрпошта: для адресної доставки вкажіть індекс адреси (5 цифр)» | Адреса без індексу | Додайте індекс |
| «Укрпошта: одне відправлення — одне місце» | У формі кілька місць | Розбийте на кілька відправлень |
| «Укрпошта: нема eCom-кредів (UP_BEARER / UP_TOKEN) — список створити неможливо» | В акаунті нема eCom-ключів | Введіть «Bearer» і «Токен» |
| «Укрпошта не віддала форму ф.103А для цього списку» | API не повернув форму | Спробуйте пізніше або роздрукуйте в кабінеті |
| «Нема доступу до акаунта «…» Укрпошта — …» | Не поставлено «Показати» | Адміністратор дає доступ |

## Для ШІ-співробітників
З доступами «Інтеграції» і «Налаштування інтеграцій» (вкладка «Доступи» пульта ШІ) ШІ читає ці налаштування (`integrations_carrier_get`, `integrations_carrier_statuses`), натискає «Перевірити» акаунт (`integrations_carrier_check`) і пропонує зміни (`integrations_carrier_update`, `integrations_carrier_account_add`, `integrations_carrier_account_delete`) — кожна чекає «Підтвердити» адміністратора. Ключі й токени ШІ не бачить (лише «задано» й `••••1234`) і не вводить. Докладно — [Інтеграції — вхід для ШІ](integrations.md). Список відправлень ф.103А ШІ пропонує створити через `integrations_carrier_list_create` (теж із підтвердженням). Відправлення створює людина. ШІ бачить доставки угоди в `deals_get`. Статтю ШІ читає інструментом `help("int-ukrposhta")`.

## Додаткова інформація
- Пов'язані статті: [Доставки і ТТН](shipping.md), [Нова Пошта](int-nova-poshta.md), [Meest](int-meest.md).