# Доставка — WIKI Helomi

> ТТН з угоди, трекінг і статуси, повернення, усі відправки компанії в одному списку.


---

# Доставки і ТТН

ТТН (експрес-накладна) створюється прямо з картки угоди в Новій Пошті, Укрпошті, Meest або Rozetka Delivery: дані отримувача, адреса, вага й накладений платіж підставляються з угоди, а номер, статус і стікер з'являються в блоці «Доставка». Кожен перевізник може мати кілька акаунтів відправника, а статуси доставки можна зв'язати з етапами угоди.

## Можливості
- Шторка «Створити ТТН» з вкладками служб: «Нова Пошта», «Укрпошта», «Meest», «Rozetka Delivery», «Kasta».
- Кілька акаунтів відправника на службу, кожен зі своїми ключами, відправником і значеннями за замовчуванням; доступ до акаунта — за людьми.
- Міста й відділення зі списку служби; адресна доставка там, де служба її дає.
- Одне або кілька місць з вагою і габаритами (об'ємна вага рахується сама).
- «Перевірити без створення» показує, що піде перевізнику.
- «Додати ТТН» — записати номер, створений деінде.
- «Редагувати ТТН» — змінити створену ТТН Нової Пошти (номер той самий) або запис ручної ТТН.
- Стікер 100×100, оновлення статусу, посилання на сайт служби, скасування.
- Статус перевізника → етап угоди; тип оплати → статус оплати.

## 1. Налаштування перевізника
1. «Інтеграції» → картка перевізника (Нова Пошта, Укрпошта, Meest, Rozetka Delivery) → вкладка «Налаштування».
2. «Увімкнути інтеграцію».
3. «Додаткова інформація»: що писати в опис відправлення, «Номер замовлення»; для Нової Пошти ще «Внутрішній номер відправлення», «Супроводжуючі документи», «Тип отримання грошей», «Кількість місць», «Розмір відправлення».
4. «Акаунти» → «+ Додати акаунт»: назва, ключі (зберігаються зашифровано, показується лише «задано» і чотири останні знаки), відправник, значення за замовчуванням для форми ТТН. «Перевірити» звіряє ключі зі службою; «Прибрати акаунт» видаляє.
5. «Доступи»: які люди (і ШІ) можуть створювати ТТН від цього акаунта. Адміністратор може завжди.
6. «Пов'язані статуси»: статус перевізника → етап угоди (див. розділ 6). «Пов'язані типи оплат та статуси» і «Пов'язані поля» (з якого поля угоди брати місто, відділення або індекс, отримувача, телефон, тип отримання грошей).
7. «Зберегти» внизу; «Скасувати зміни» повертає збережене.

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

## 2. Створити ТТН з угоди
1. Відкрийте угоду → блок «Доставка» → «+» у заголовку або «Додати місце» під таблицею. Дані одержувача шторка бере з полів блоку «Доставка» («Адреса доставки», «Одержувач», «Телефон одержувача», «Спосіб доставки»): туди їх кладе приймання замовлення з маркетплейсу чи сайту, поки ТТН ще нема (рядка ТТН до створення в таблиці нема — він з'являється з номером). Біля кожного номера ТТН — кнопка «Скопіювати» (і в угоді, і в пультах Ростіка й Віктора, і на панелі маркетплейсу).
2. Угорі виберіть службу і «Акаунт відправника»; режим — «Створити нову ТТН». «Дані відправника» (місто, відправник, відділення відправки, ПІБ, телефон) і параметри відправлення підставляються з цього акаунта в «Інтеграції → <служба> → Налаштування → Акаунти»; інший акаунт у списку — підставляються його дані. Акаунтів, до яких у вас нема доступу («Доступи» → «Показати»), у списку нема.
3. Перевірте отримувача, телефон (`+380XXXXXXXXX`), місто й відділення (зі списку) або адресу, платника, накладений платіж («Післяплата»), оголошену вартість. Більшість полів уже заповнено з угоди, клієнта й налаштувань акаунта.
   «Прізвище», «Ім'я», «По батькові» шторка бере з одержувача угоди в порядку «Прізвище Ім'я По батькові» — однаково для Нової Пошти, Укрпошти, Meest і Rozetka Delivery. Покупці часто вписують ім'я в поле прізвища (Rozetka, угода 909015134: «Богдан Баран євгенович»); якщо на місці прізвища відоме ім'я, а на місці імені — ні, шторка міняє їх місцями, по батькові ставить третім, а слово з малої літери пише з великої («Баран Богдан Євгенович»). Обидва слова схожі на імена («Роман Олена») — лишає як є: перевірте поля перед створенням. Те саме правило діє, коли замовлення Rozetka, Prom, Епіцентру, Kasta чи сайту створює клієнта.
   Місто й відділення з угоди шторка не підставляє текстом, а шукає в довіднику служби: знайдено однозначно — біля поля пігулка «вибрано», а під полем «з довідника: …» (місто з областю, повна назва відділення чи поштомата, як у службі). Однойменних населених пунктів кілька, а області в адресі нема (адреси Rozetka: «Кам'янське, : Конституції пр-т, 17Г») — шторка сама перевіряє, у якому з них є відділення / магазин з угоди, і бере його; не визначилось — єдине місто серед сіл; і лише тоді під полем підказка «виберіть потрібний зі списку». Назви з «м.» / «с.» і друкарським апострофом («Кам’янське») порівнюються без різниці. Натиск на поле відкриває список: на «Місто» — населені пункти з такою назвою (з областю), на «Відділення» — усі відділення й поштомати міста, вибране жирним; почніть вводити номер чи вулицю — список звузиться.
   **Адреса клієнта** (власник 22.10, лише Нова пошта): у «Дані одержувача» — пігулки адрес доставки з картки клієнта. Коли в
   угоді своєї адреси нема (або там той самий старий текст «Адреса доставки» клієнта), основна адреса вже у формі: тип одержувача
   (організація з ЄДРПОУ й назвою компанії або приватна особа), ПІБ, телефон, місто й відділення з довідника. Клік по іншій адресі —
   форма заповнюється нею; «З угоди» — повертає адресу із замовлення. Адреси додають у картці клієнта (стаття «Клієнти», §5а).
4. За потреби натисніть «Перевірити без створення» — побачите «Що піде перевізнику».
5. «Створити ТТН». Номер з'явиться в блоці «Доставка», запис — у журналі угоди, PDF перевізника — у «Файлах» угоди.

Активна ТТН тієї самої служби в угоді вже є — Helomi попросить підтвердити другу. На телефоні шторка відкривається на весь екран, поля йдуть в одну колонку.

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

## 3. Місця відправлення
- «Загальні параметри» — одна вага й розмір на все відправлення.
- «кожне місце окремо» — таблиця «Місця відправлення»: «Вага *», «Довжина *», «Ширина *», «Висота *», «Цінність»; «Вага об'ємна» рахується як Д×Ш×В / 4000. «Додати місце», «×» — прибрати.
- Укрпошта: одне місце на відправлення.

## 3а. Вага й габарити з товарів угоди
Власник 19.10: щоб у ТТН ішли справжні вага й розмір посилки, а не дефолти акаунта (0,5 кг, 20×15×10).
1. У товарів заповніть системні поля «Вага, кг», «Об'єм, м³», «Довжина, см», «Ширина, см», «Висота, см» — у картці товару складу
   (група «Вага й габарити») або позиції прайс-листа. Позиція прайс-листа, пов'язана зі складом, бере їх із товарів складу сама.
2. У картці служби («Налаштування» → «Інтеграції» → «Перевізники» → Нова Пошта / Укрпошта / Meest / Rozetka Delivery →
   «Налаштування») увімкніть «Вага й габарити з товарів» → «Заповнювати вагу й габарити посилки з товарів угоди» → «Зберегти».
3. Тепер для кожної угоди посилка рахується з її товарів і кількості — одна коробка: вага й об'єм — сума (одиниця × кількість),
   довжина й ширина — найбільші серед товарів, висота — стопкою (висота × кількість, додається). Набір із прайс-листа
   («3 шт») рахується своїми габаритами позиції.
4. Шторка «Створити ТТН» показує ці числа в «Розмірі відправлення» з підказкою «Вага й габарити — з товарів угоди: … кг, Д×Ш×В см».
   Їх можна змінити руками перед створенням.
5. Так само працюють усі, хто створює ТТН без шторки: ШІ Олесь, авто-ТТН на етапах каналу (Prom, Rozetka, Епіцентр), інструмент ШІ
   `shipping_create_ttn`, ТТН Rozetka Delivery для замовлення Rozetka.
6. Чого в товарах нема (наприклад, висоти), береться з акаунта служби, як раніше. У журналі угоди біля створеної ТТН записано,
   з якою вагою й розміром пішла посилка й чи взято їх з товарів угоди.

## 4. Записати наявну ТТН
«вручну» в блоці «Доставка» або режим «Додати ТТН» у шторці: служба, номер ТТН («Наявна ТТН») → «Записати ТТН». Номер записується в угоду без звернення до перевізника.

## 5. Стікер, статус, скасування
**Як виглядає рядок ТТН.** Колонки: ТТН, Адреса, Післяплата, Вартість, Статус, «⋮». Під номером ТТН — сірим площадка («На Prom» або «Prom ✓») і коли ТТН створено; кнопка «Скопіювати» з'являється, коли наводите на рядок (на телефоні видно завжди); відправник — у підказці номера. Під адресою — одержувач коротко (повне ім'я й телефон — у підказці). Статус — кольорова пігулка: створено — сіра, у дорозі — блакитна, чекає у відділенні — жовта, отримано — зелена, повернення — червона; під нею — очікувана дата доставки, а подробиці (де посилка, коли звірено, чи роздруковано стікер) — у підказці, якщо навести на статус. Роздрукований стікер видно й маленьким принтером біля номера. Якщо блок вузький (ліва колонка картки на ПК, телефон), кожна ТТН — картка: «⋮» ліворуч, номер і статус, нижче адреса з одержувачем і суми — без прокрутки вбік.

«⋮» у рядку ТТН:
- «Редагувати ТТН» — див. [5а](#5а-редагувати-ттн);
- «Роздрукувати стікер» — PDF 100×100 (після друку біля номера з'являється принтер);
- «Оновити статус» — запитує свіжий статус у перевізника;
- «Відкрити на сайті служби», «Скопіювати номер ТТН»;

Для угоди з маркетплейсу в клітинці ТТН є **постійна кнопка «На Prom / Rozetka / Kasta / Епіцентр»** — передати ТТН на площадку (як «Відправити в Prom» у KeepinCRM). Коли ТТН уже записана на площадці (ви передали її звідси або вона прийшла з площадки), замість кнопки стоїть **«Prom ✓» (назва площадки з галочкою)**; натискання на неї передає ще раз. Площадка приймає ТТН лише на певному статусі замовлення: Prom — «Прийнято»/«Оплачено», Rozetka — «Обробляється менеджером» або «Підтверджено» (ТТН іде разом зі статусом, далі Rozetka сама веде трекінг), Kasta — після «Підтверджено» та «Упаковано», Епіцентр — «Підтверджено». Якщо замовлення ще не на такому статусі, Helomi спершу переводить його туди на площадці, передає ТТН, а **етап угоди в Helomi не змінює** (підтвердження каже, у який статус буде переведено). Назад на площадці статус не повертається — маркетплейси цього не дозволяють. Якщо автоперехід вимкнено, кнопка лише показує підказку й нічого не шле. Для замовлення Rozetka з доставкою **ROZETKA Delivery** кнопки нема: накладну створює сама Rozetka після підтвердження даних, ТТН від продавця вона не приймає — як у KeepinCRM, де для цієї доставки вводять лише вагу, розміри й сторони. Правило — у картці каналу «Налаштування продажів → Передача ТТН на маркетплейс». Запис про передачу — у журналі угоди й картки каналу.

**Замінити ТТН на площадці.** Якщо на площадці вже стоїть інша ТТН (стару видалили й створили нову), кнопка «На Prom» над новою ТТН питає «На Prom зараз ТТН … Замінити її на …?» і записує нову замість старої. Якщо стара ТТН уже в дорозі, у підтвердженні є попередження — перевірте, що посилку справді відправлено новою. ТТН з KeepinCRM зі службою «ukr_poshta» — це Укрпошта, вона передається на Prom так само.
- «Видалити ТТН» — після підтвердження ТТН, створену в Helomi, видаляється в перевізника і зникає з угоди (як у KeepinCRM). Якщо перевізник відмовив (наприклад, посилку вже оформлено у відділенні), з'являється його причина і питання «Прибрати ТТН з угоди все одно?» — тоді вона зникає лише з угоди, у перевізника лишається. ТТН, додану вручну чи з KeepinCRM, і вже скасовану — прибирає з угоди без запиту до перевізника. Кожне видалення — запис у журналі угоди.

## 5а. Редагувати ТТН
«⋮» рядка ТТН → «Редагувати ТТН» відкриває шторку з поточними даними.
- **ТТН Нової Пошти, створена в Helomi** — та сама форма, що й «Створити ТТН»: одержувач, телефон, місто й відділення (або адреса), вага, місця, післяплата, опис. Дані підтягуються з самої Нової Пошти. «Перевірити без змін» показує, що піде перевізнику, «Зберегти зміни» змінює ТТН у Новій Пошті — **номер лишається той самий**. Стікер після зміни треба роздрукувати заново. Акаунт відправника змінити не можна — для іншого акаунта видаліть ТТН і створіть нову.
- **ТТН, додана вручну чи з KeepinCRM** — змінюється лише запис в угоді: номер, адреса, одержувач, телефон, післяплата. У перевізника нічого не змінюється.
- ТТН інших служб, створені в Helomi (Укрпошта, Meest, Rozetka Delivery), змінити не можна — видаліть і створіть нову. Скасовану чи вже отриману ТТН не редагують.
Кожна зміна — запис у журналі угоди з тим, що було і що стало.

## 6. Статус доставки змінює етап угоди
1. «Інтеграції» → перевізник → «Налаштування» → «Пов'язані статуси» → «+ Додати»: «Зовнішній статус» → «Етап» (з воронкою).
2. Коли оновлюється статус ТТН, угода переходить на пов'язаний етап (запис у журналі від «трекінг доставки»). Архівні угоди не змінюються.
3. Для Нової Пошти статус можна задати шаблоном (наприклад, з датою), або початком тексту.
4. Там само — «Міняти етап, коли посилка»: стани посилки, на яких етап за статусом міняється. Типово позначено «відправлена / в дорозі», «у відділенні», «отримана», «повернення»; «створена, ще не відправлена» — ні: поки посилку не здали службі, етап угоди стоїть, навіть якщо для статусу «Створено» є рядок (власник 16.10, угода 36829027: «Укрпошта: Створено онлайн. Очікує приймання» переводила угоду назад у «Прийнято»). Це правило діє однаково для ШІ Ростіка, фонового оновлення статусів і «⋮ → Оновити статус».
5. **Рядок діє лише на угоди воронки свого етапу.** У списку «Етап» біля кожного етапу видно воронку: «Відправлено [Продажі]», «Відправлено [Продажі Каста]». Щоб статус рухав угоди кількох воронок, додайте для кожної воронки свій рядок з тим самим статусом (власник 17.10: раніше рядок лише «Продажів» переносив угоду «Продажі Епіцентр» у «Продажі»). Нема рядка для воронки угоди — етап не змінюється.
6. **«Скасовані угоди не чіпати»** (перемикач, типово ввімкнено): угоду на етапі з роллю «Скасована» статус посилки не переводить на інший етап і не закриває «Виграно» в архів. Вимкніть, якщо скасовану угоду має «оживляти» посилка, що таки поїхала.
7. **«Не повертати угоду на етап до збірки»** (перемикач, типово ввімкнено): коли посилка вже поїхала, рядки, що ведуть на етап з роллю «Створено», «Прийнято», «Передали на збірку», «Зібрано» чи «Допомога», пропускаються — діє наступний рядок, що збігся. Так старий рядок KeepinCRM «Прийнято» → «Прийнято» не тягне відправлену угоду назад.
8. **Як налаштувати вручну (приклад Rozetka Delivery і Укрпошти, 17.10).** Беріть статус зі списку біля поля — там справжні тексти служби. Rozetka Delivery: «В дорозі» → «Відправлено», «У відділенні» → «У відділенні», «Видано» → «Отримано», «Відмова від одержання» → «Повернення». Укрпошта: «Прийнято», «Прибуло до Логістичного центру», «Прибуло до Сортувального депо» → «Відправлено»; «Прибуло до Відділення» → «У відділенні»; «Вручено Одержувачу» → «Отримано»; «Повернення. Вручено Відправнику» → «Повернення». Назви KeepinCRM («У дорозі», «Готово до видачі», «Відправлення прийняте», «Надходження на сортувальний центр»…) теж працюють — під полем видно підказку, які справжні тексти вони ловлять. Повторіть рядки для кожної воронки, де їздять такі посилки.

**Звідки статус.** Статус ТТН приходить з API служби: Нова Пошта — `TrackingDocument.getStatusDocuments`, Укрпошта — StatusTracking (токен трекінгу акаунта), Meest — openAPI (токен акаунта; Meest показує лише відправлення свого договору — для ТТН, які створив Prom під своїм договором, статус береться із замовлення Prom: «Доставлено (Prom)»…), Rozetka Delivery — публічний трекінг. Фоном статуси оновлюються самі — у налаштуваннях перевізника (типово раз на 30 хв) і на кожному кроці ШІ Ростіка, з переходом угоди на пов'язаний етап; вручну — «⋮ → Оновити статус».

**Яким ключем.** Спершу — ключем акаунта, з якого ТТН створено, далі базовим ключем і ключами інших акаунтів служби (ТТН, додану вручну, могли створити в іншому кабінеті). Ключ кабінету, з якого ТТН створено, дає повні дані (телефон одержувача, точну післяплату); без ключа Нова Пошта віддає лише базовий статус. Номер, скопійований із сайту служби з пробілами («20 4005 5552 6300»), записується й перевіряється без пробілів. Поки служба ще не відповідала, щойно створена чи додана ТТН показується як «створено, не відправлено» (сірим), а не «в дорозі».

**Опис і номер замовлення для Rozetka Delivery.** В ЕН Rozetka йде лише те, що є у формі KeepinCRM: вага, розміри, короткий опис, відправник і одержувач, післяплата й оголошена вартість. Опис з «Додаткової інформації» акаунта очищається від службових символів («A000001-#2шт.» → «A000001-2шт.», до 90 символів), номер замовлення — лише цифри й латиниця до 20 символів (інакше не передається). Якщо Rozetka все одно відмовляє, не назвавши поле, запит повторюється без номера замовлення і з описом «Угода <id>».

## 7. Kasta і «Магазини Rozetka» на Prom
- Угода з Kasta: ТТН створюється лише в кабінеті hub.kasta.ua коштом Kasta (вкладка «Kasta» → «Створити в hub.kasta.ua»); інші служби для неї вимкнені.
- «Магазини Rozetka» для угоди з Prom: ЕН створюється лише через кабінет Prom («Створити через кабінет Prom»), якщо таке створення увімкнено; інакше — вручну в кабінеті Prom.

## 7а. Замовлення Rozetka з доставкою ROZETKA Delivery
Угода з Rozetka, де покупець вибрав ROZETKA Delivery: «+» і «Додати місце» відкривають не звичайну шторку, а форму **«ТТН із замовлення Rozetka»** (16.10). Накладну створює сама Rozetka в кабінеті продавця й одразу прив'язує до замовлення — ЕН з власного акаунта Rozetka Delivery таке замовлення не приймає. Одержувач і оплата — із замовлення (лише показ); заповнюєте вагу, габарити, місць, опис, відправника з відділенням відправлення і платника, далі «Створити ТТН на Rozetka». «Інший перевізник» — звичайна шторка. Перемикач і докладно — стаття [Rozetka](int-rozetka.md), розділ 5а.

## 8. Укрпошта: адреси і списки відправлень
У налаштуваннях Укрпошти є ще «Адреси відправника» і «Списки відправлень». ТТН можна додати до списку, а для списку — сформувати «Форма ф.103А» (PDF). Назви полів API для списків ще не звірено наживо.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Акаунт служби не налаштовано» / «Не задано ключі акаунта: …» | Нема акаунта або ключів | Додайте акаунт і ключі в «Інтеграції → перевізник → Налаштування» |
| «Акаунт «…» вимкнено в налаштуваннях …» | Акаунт вимкнено | Увімкніть акаунт або виберіть інший |
| «Телефон отримувача «…» — потрібен формат +380XXXXXXXXX» | Неправильний номер | Виправте телефон |
| «…: вкажіть прізвище та ім'я отримувача (щонайменше 2 слова)» | Неповний ПІБ | Впишіть прізвище й ім'я |
| «Не вказано місто отримувача», «Виберіть відділення зі списку» | Місто чи відділення не вибрано зі списку служби | Виберіть зі списку |
| «…: адресна доставка недоступна — виберіть відділення» | Служба не возить на адресу | Виберіть відділення або поштомат |
| «Укрпошта: індекс відділення — 5 цифр (наприклад 79000)» | Неправильний індекс | Виправте індекс |
| «Укрпошта: одне відправлення — одне місце» | Кілька місць для Укрпошти | Залиште одне місце або створіть кілька ТТН |
| «Kasta-угода: ТТН створюється ЛИШЕ через кабінет hub.kasta.ua …» | Для Kasta вибрано іншу службу | Оберіть вкладку «Kasta» |
| «Угода в архіві — спершу поверніть її з архіву» | ТТН для архівної угоди | «⋮ → Розархівувати» в угоді |
| «Перевізник відповів без номера ТТН» | Служба не повернула номер | Перевірте кабінет перевізника; за потреби «Додати ТТН» вручну |
| «ТТН … змінити не можна: вона неактивна або … не дозволяє змінювати створену ТТН» | Скасована/отримана ТТН або служба без зміни через API | Видаліть ТТН і створіть нову |
| «Акаунт відправника створеної ТТН змінити не можна…» | У шторці редагування вибрано інший акаунт | Видаліть ТТН і створіть нову з потрібного акаунта |
| «Нова Пошта не знайшла ТТН … жодним ключем кабінету…» після «Оновити статус» | Номер помилковий або ТТН видалено — Нова Пошта не знаходить її навіть без ключа | Перевірте номер на сайті служби; за потреби «⋮ → Редагувати ТТН» або «Видалити ТТН» |
| «… статус ще недоступний» | Служба ще не віддала статус (нова ТТН Укрпошти / Meest / Rozetka) або не задано токен трекінгу | Спробуйте пізніше; для Укрпошти й Meest перевірте токен трекінгу акаунта |
| «Стікер недоступний (служба ще не сформувала PDF або ТТН не наша)» | ТТН створено не з Helomi або PDF ще нема | Спробуйте пізніше або друкуйте в кабінеті служби |

## Для ШІ-співробітників
ШІ працює з ТТН угоди тими самими маршрутами, що й шторка: `shipping_list`, `shipping_prefill`, `shipping_track`, `shipping_create_ttn` (через кошик підтверджень; `values.address_id` — адреса доставки клієнта з `clients_addresses`, без нього — основна, коли в угоді своєї адреси нема; `shipping_prefill` повертає `addresses` і підставлений `address_id`). Для замовлення Rozetka з ROZETKA Delivery (`shipping_list` дає `rozetka_order`) — `shipping_rozetka_order_form`, `shipping_rozetka_order_pickups`, `shipping_rozetka_order_create` (теж через кошик). Окремого розділу в каталозі `describe_section` для доставок нема.

ШІ бачить доставки угоди в `deals_get` (блок доставок) і може шукати угоду за номером ТТН через `deals_list` з `q`. Ключі перевізників ШІ не бачить і не змінює.

«Пов'язані статуси» і перемикачі трекінгу (`stage_phases`, `keep_lost`, `no_back`) ШІ читає `integrations_carrier_get` і змінює `integrations_carrier_update` — ті самі поля, що у формі, і лише після «Підтвердити» адміністратора (стаття «Інтеграції»).

Чого не робити:
- Не обіцяти клієнту номер ТТН, якого нема в `deals_get`.
- Не вигадувати номери ТТН і не записувати їх у поля угоди замість блоку «Доставка».

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md); інтеграції [Нова Пошта](int-nova-poshta.md), [Укрпошта](int-ukrposhta.md), [Meest](int-meest.md), [Rozetka Delivery](int-rozetka-delivery.md), [Kasta hub](int-kasta-hub.md).


---

# Доставка

«Доставка» — усі ТТН з угод одним списком, як розділ «Доставка» у KeepinCRM. Тут видно, де кожна посилка, хто її одержувач, яка післяплата й вартість доставки, на якому етапі угода і коли почнеться платне зберігання. Звідси масово оновлюють статуси й друкують стікери, а відкрити угоду можна одним кліком. Вигляд «Статистика» показує, на який день після прибуття клієнти забирають посилки і скільки відсотків повертається — окремо по кожній службі.

## Можливості
- Усі ТТН з усіх угод: Нова Пошта, Укрпошта, Meest, Rozetka Delivery, Kasta.
- Колонки як у KeepinCRM: «Створено», «Адреса», «Відправник», «Головний відповідальний», «Клієнт», «Угода», «ТТН», «Післяплата», «Вартість доставки», «Статус», «Етап угоди», «Прибуло», «Платне зберігання», «Планована дата доставки», «Список відправлень». Додатково: «Дата отримання», «Контроль оплати», «Філія», «Телефон одержувача».
- Фільтри: «Створено», «Дата отримання», «Філія», «Тип доставки», «Етап», «Сплачено», «Статус», «Відправник», «Головний відповідальний», «Контроль оплати», «Список відправлень».
- Пошук за ТТН, телефоном, клієнтом, номером угоди, адресою.
- Сортування кліком по назві колонки.
- Масові дії: «Оновити статуси», «Скопіювати ТТН».
- «Статистика»: по кожній службі — % повернень, на який день після прибуття забирають посилку (1-й, 2-й… день, наростом), медіана, частка в межах безкоштовних днів, по місяцях.
- Внизу — суми післяплати й вартості доставки за всіма знайденими ТТН, «Рядків на сторінці» і «Всього».

## 1. Налаштування
Окремо налаштовувати нічого не потрібно: ТТН з'являються тут, коли їх створюють в угоді («Доставка» → «Створити ТТН»), записують вручну або вони приходять з маркетплейсів.

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

«Платне зберігання» рахується від дня, коли посилка прибула у відділення, плюс безкоштовні дні з налаштувань ШІ Ростіка («Інтеграції» → «ШІ» → «Ростік»). Дата червона — платне зберігання вже йде.

## 2. Знайти посилку
1. Головне меню → «Доставка».
2. У полі пошуку вгорі введіть номер ТТН, телефон, ім'я клієнта, номер угоди або частину адреси → Enter.
3. Клієнт і угода в рядку — посилання: картка клієнта чи угоди відкриється одразу.

Типово список показує ТТН, створені за останні 30 днів. Щоб побачити старіші, змініть «Створено» у фільтрах або очистіть його хрестиком.

На телефоні кожна ТТН — картка: служба, номер, статус, етап, клієнт, угода й адреса. Фільтри відкриваються кнопкою «Фільтри».

## 3. Фільтри
Кнопка «Фільтри» поруч із пошуком відкриває чи ховає панель. Число на кнопці — скільки фільтрів вибрано.
- «Створено» і «Дата отримання» — період: дата «від» і «до» (включно).
- «Тип доставки» — служба.
- «Статус» — «Створено», «В дорозі», «У відділенні», «Отримано», «Повернення», «Скасовано».
- «Етап» — етап угоди (за воронками).
- «Сплачено» — «Сплачено», «Частково», «Не сплачено» (за оплатами угоди).
- «Контроль оплати» і «Список відправлень» — як їх вибрали у формі «Створити ТТН». Для ТТН, створених раніше (до 15.10.2026) чи вручну, ці поля порожні.
- «Скинути» повертає типовий вигляд: останні 30 днів, без інших фільтрів.

## 4. Колонки
«⋮» праворуч від «Фільтрів» → «Колонки». Поставте чи зніміть галочки. «Як було» повертає типовий набір. Вибір зберігається на цьому пристрої.

## 5. Дії з ТТН
«⋮» на початку рядка:
- «Відкрити угоду».
- «Скопіювати ТТН». Номер копіюється й кнопкою поруч із ним.
- «Роздрукувати стікер» — PDF 100×100, як у блоці «Доставка» угоди. Значок принтера біля номера означає, що стікер уже друкували.
- «Оновити статус» — запит до перевізника. Етап угоди змінюється за «Пов'язаними статусами» налаштувань перевізника.
- «Відкрити на сайті служби».

Створити, змінити чи видалити ТТН можна в угоді, у блоці «Доставка».

## 6. Оновити статуси кількох ТТН
1. Поставте галочки в рядках. Галочка в шапці таблиці вибирає всю сторінку.
2. На чорній панелі виберіть «Оновити статуси» (до 100 ТТН за раз) або «Скопіювати ТТН» (номери стовпчиком).
3. Скасовані ТТН і ТТН без номера пропускаються, під панеллю видно, скільки оновлено.

Те саме для всієї сторінки — «⋮» → «Оновити статуси на сторінці». Статуси відкритих угод і так оновлюються самі кожні 5 хвилин.

## 7. Статистика: на який день забирають і % повернень
1. У шапці перемкніть «Список | Статистика» на «Статистика» (або «⋮» → «Статистика»). Вибір запам'ятовується на цьому пристрої.
2. Над картками виберіть період: «30 днів», «3 місяці», «Пів року», «Рік». Це той самий фільтр «Створено»: свої дати можна задати в панелі «Фільтри».
3. Угорі — підсумок по всіх службах: скільки відправлень, % повернень, скільки забрали в 1-й день, медіана.
4. Нижче — картка на кожну службу (Нова Пошта, Укрпошта, Meest, Rozetka Delivery, Kasta):
   - «Повернення» — % повернень із завершених посилок (отримано + повернення); ті, що ще в дорозі чи у відділенні, не рахуються.
   - «Медіана» — день, до якого забирають половину посилок.
   - «До N-го дня» — скільки посилок забрали за безкоштовні дні зберігання.
   - Таблиця днів: «Забрали» — скільки посилок забрали саме цього дня (% і кількість), «Наростом» — скільки вже забрали до кінця цього дня включно. Дні після безкоштовних позначені червоним — там уже платне зберігання.
   - «По місяцях» — отримано, повернення і % повернень за місяцями створення ТТН.
5. Усі фільтри панелі діють і на статистику: служба, етап, філія, відправник, відповідальний, пошук.

Як рахується:
- 1-й день — день, коли посилка прибула у відділення (за київським часом). Забрали того ж дня — 1-й день, наступного — 2-й.
- Дати «Прибуло» і «Дата отримання» записує трекінг служби: Нова Пошта віддає обидві, Укрпошта, Meest і Rozetka Delivery — дату тієї події, яку трекінг побачив (статуси оновлюються кожні 5 хвилин). Якщо служба не дала дати прибуття, береться мить, коли посилку вперше побачили у відділенні.
- Посилки без цих дат у днях не враховуються (видно «без дат N» під карткою). Коли посилок з датами менше 10, розподіл не показується: один-два випадки дають неправдиву картину.
- Безкоштовні дні зберігання беруться з налаштувань ШІ Ростіка («Інтеграції» → «ШІ» → «Ростік»), окремо для кожної служби. Змінили там — статистика одразу рахує за новими днями.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «ТТН за цими фільтрами нема» | Період «Створено» або інші фільтри відсікли все | «Скинути» або розширте період |
| «Серед вибраних нема активних ТТН (скасовані й без номера не трекаються)» | Вибрано лише скасовані ТТН | Виберіть інші |
| «Перевізник не відповів: …» | Сервіс перевізника недоступний | Повторіть пізніше |
| Розділу «Доставка» нема в меню | Адміністратор не відкрив розділ або ви сховали його в «Моєму меню» | Попросіть адміністратора або увімкніть у «Моє меню» |
| У картці служби «Служба не дала дат прибуття й отримання» | Служба не віддає ці дати (Rozetka Delivery — лише дату отримання; Meest — лише свої ТТН) або посилки старші, ніж трекінг почав їх записувати (19.10.2026) | Нічого: нові посилки з'являться в розподілі самі; % повернень рахується й без дат |
| «За цей період ТТН нема» у статистиці | Період чи фільтри відсікли все | Виберіть довший період або «Скинути» у фільтрах |

## Для ШІ-співробітників
Розділ у каталозі — `describe_section("deliveries")`.
- `deliveries_list` — список з тими самими фільтрами й пошуком: `q`, `date_from`, `date_to`, `received_from`, `received_to`, `office`, `service`, `stage_id`, `paid`, `status` (`created`, `in_transit`, `at_branch`, `received`, `return`, `cancelled`), `sender`, `responsible_id`, `pay_control` (`yes`/`no`), `shipment_list`, `deal_id`, `sort`, `order`, `page`, `per_page`.
- `deliveries_refs` — довідники для фільтрів.
- `deliveries_track` — оновити статуси вибраних ТТН (`values: {ids: [...]}`, до 100).
- `deliveries_stats` — статистика по службах з тими самими фільтрами (`date_from` — період, `days_max` — скільки днів окремо, типово 10): `carriers[]` і `total` з `outcomes`, `return_pct`, `days.hist` (`day`, `pct`, `cum_pct`, `count`), `days.median`, `days.within_free_pct`, `months[]`. Лише читання.

Створити ТТН, надрукувати стікер чи оновити одну ТТН — інструментами угоди `shipping_*`. Створення ТТН відправляє дані назовні, тому спершу треба запитати людину.

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