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

# Rozetka

Інтеграція з Rozetka через Seller API приймає замовлення маркетплейсу в «Угоди», передає статус і ТТН назад на Rozetka, приносить чати покупців у «Переписки» і дає створювати ТТН у «Магазини Rozetka». Підключити можна одним натиском: увійти логіном і паролем кабінету продавця і натиснути «Підключити Rozetka» — налаштування, статуси й приймання замовлень увімкнуться самі.

## Можливості
- Вхід логіном і паролем кабінету продавця (тимчасовий токен на 24 години оновлюється сам) або ключем API.
- «Підключити Rozetka» — одна кнопка: перевірка доступу, налаштування продажів, пов'язані статуси, «Магазини Rozetka», приймання замовлень і перше опитування.
- Замовлення Rozetka (нові, підтверджені й ті, що «Обробляються менеджером») кожні 5 хвилин стають угодами; повтор не дублюється.
- Статуси Rozetka беруться з Seller API; таблиця «Пов'язані статуси» — статус → етап угоди.
- Автоприйняття: «Нове замовлення» → «Обробляється менеджером» на Rozetka; чи й куди переводити угоду в CRM — налаштування
  «переводити угоду на етап» (типово для Rozetka — «не переводити», як у KeepinCRM).
- Статус назад на Rozetka, коли менеджер рухає угоду.
- Чати про товари, про замовлення і запитання до продавця.
- ТТН у «Магазини Rozetka» через Rozetka Delivery з доступом по людях.
- «ТТН із замовлення» (16.10): замовлення з доставкою ROZETKA Delivery — окрема форма в угоді, накладну створює сама Rozetka в кабінеті продавця й одразу прив'язує до замовлення (як у KeepinCRM).
- Імпорт усіх старих замовлень і клієнтів за N днів.
- Оновлення залишків і цін на Rozetka — через Seller API (у кабінеті Rozetka прайс-лист типу «Особистий кабінет (API)»): Helomi шле `PUT /items/mass-update` для кожного оголошення Rozetka з прайс-листа («Оголошення з каналів»): залишок — вільний залишок пов'язаних товарів складу, ціна — з прайс-листа. Автоматично за розкладом («Склад → Публікації» → картка Rozetka → «автоматично кожні N хв», типово 60) або кнопкою «Оновити зараз» у картці Rozetka / «Публікаціях» (спершу «Показати, що зміниться»). Позиція без зв'язку зі складом не чіпається. Запобіжник: якщо за один прогін у нуль пішло б забагато оголошень — прогін зупиняється, підтвердити можна кнопкою. Фід каналу `/feed/channel/rozetka.xml` лишається для перевірки.
- «На Rozetka» в рядку ТТН угоди — передати ТТН. Rozetka приймає ТТН **лише разом зі статусом** (Seller API «Редагування замовлення (статус, ТТН)»: `status` обов'язковий; без нього Rozetka відповідає «успіх», але ТТН не записує). Helomi бере дозволені переходи замовлення (`expand=status_available`) і шле `PUT /orders/{id}` `{status, ttn}`: 61, якщо дозволено, інакше 2 «Дані підтверджено» (з ТТН Rozetka сама ставить 61), інакше 3; далі трекінг веде Rozetka. Приймає з «Обробляється менеджером» (26) і «Підтверджено» (2); з «Нове» Helomi спершу ставить 26 (як автоприйняття). Результат перевіряється перечитуванням замовлення, новий статус записується в угоду (етап угоди не змінюється). Правило — «Налаштування продажів → Передача ТТН на маркетплейс».

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «Rozetka» → вкладка «Підключення».

Є два способи доступу — оберіть один:
- **Логін і пароль кабінету продавця.** Рядок «Кабінет Rozetka» → «Логін» → логін і пароль → «Увійти». Після входу видно «Авторизований як: <логін>» і до якого часу діє токен. Rozetka дає токен на 24 години — CRM оновлює його сама перед опитуванням. Пароль зберігається зашифрованим. «Вийти» забуває логін і пароль (далі діє ключ API, якщо він заданий).
- **Ключ API.** Рядок «API ключ (Seller API)» → «Ввести» → «Зберегти ключ». Ключ береться в кабінеті продавця Rozetka в розділі безпеки API.

«Перевірити» — безпечний запит лише на читання; успіх — «доступ до замовлень є».

Друга вкладка картки — «Налаштування продажів»: «Основне» (перемикач, «Джерело угод», «Відповідальний»), «Нові замовлення» («Автоприйняття», «Зв'язувати товари по»), «Чати», «Пов'язані статуси», «Автоматична відправка ТТН», «Фід для маркетплейсу», «Магазини Rozetka», «Імпорт замовлень і клієнтів». Унизу — «Зберегти» і «Скасувати зміни».

Дані замовлення пишуться в додаткові поля угоди з ключами `rozetka_order_id`, `rozetka_status` (назва статусу) і `rozetka_status_code` (його код), `rozetka_status_history`, `rozetka_order_amount`, `rozetka_amount_with_discount`, `rozetka_payment_type`, `rozetka_payment_status`, `rozetka_user_rating`, `rozetka_delivery_address`, `rozetka_delivery_recipient_title`, `rozetka_delivery_cost` та інші (повний перелік — у розділі 8). Самі поля налаштовуються в «Налаштування → Типи даних → Угоди».

Юрособа для угод Rozetka — правилом у «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

## 2. Підключити одним натиском
1. Увійдіть логіном/паролем або введіть ключ API.
2. Рядок «Одним натиском» → «Підключити Rozetka» → підтвердіть.
3. CRM перевірить доступ і поставить налаштування як у KeepinCRM: джерело «Rozetka», головний відповідальний, «Нове замовлення» → «Обробляється менеджером» через 1 хвилину, товари за артикулом, усі три види чатів, статус назад на Rozetka, пов'язані статуси (статуси шукаються в списку Rozetka за назвою, етапи — у воронці «Продажі» за назвою), «Магазини Rozetka» з доступом відповідальному; потім увімкне приймання і зробить перше опитування.
4. Під кнопкою з'явиться «Підключено: …», перелік застосованого і пропущеного (з рискою): наприклад, етапу з такою назвою у воронці нема. Пропущене допишіть у «Налаштуваннях продажів» вручну.

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

Повторне натискання — «Застосувати налаштування знову».

**Важливо.** Того ж дня вимкніть інтеграцію Rozetka в KeepinCRM, інакше замовлення прийдуть двічі.

## 3. Приймати замовлення в угоди
Коли інтеграцію ввімкнено, CRM кожні 5 хвилин забирає замовлення. Клієнт шукається за телефоном (нема — створюється), угода отримує назву = № замовлення, етап за «Пов'язаними статусами», позиції — за вибраним полем зв'язку, доставку й оплату. Повторне надходження оновлює статус і додаткові поля (оплату, статус оплати, ТТН, історію статусів), а якщо статус на Rozetka справді змінився і є в мапі — рухає угоду. Те саме замовлення з тим самим кодом статусу етап не чіпає, навіть якщо змінився лише запис статусу (наприклад, код «1» став назвою «Нове замовлення»). Результат — «Стан роботи → Приймання замовлень» і «Журнал подій».

«Адреса доставки» угоди — як у KeepinCRM: місто, вулиця, будинок і точка з номером, напр. «Київ, вул. Якуба Коласа, 15, Відділення №88»; поштомат — «Поштомат №13 (маг. …)», село — з районом і областю, точка ROZETKA Delivery — адреса з описом. До 15.10 номер відділення потрапляв у вулицю («вул. Якуба Коласа 88 15») — такі незмінені адреси в уже створених угодах уточнено разовою заявкою; вписане людиною не чіпали.

## 4. Пов'язані статуси і статус назад на Rozetka
1. «Налаштування продажів» → «Пов'язані статуси» → «+ Додати статус».
2. «Статус на Rozetka» (зі списку Rozetka за назвою) → «Етап угоди»; для етапу скасування — «Причина скасування» і «Коментар покупцю».
3. Один статус можна прив'язати до кількох етапів: нова угода стане на перший рядок, а угода на будь-якому з цих етапів не рухатиметься.
4. «Зворотний зв'язок» → «Передавати етап назад на маркетплейс»: етап угоди → статус на Rozetka за цією мапою.
5. «Автоприйняття» → «Автоматично змінити статус з «Нового замовлення» на «Обробляється менеджером»» через N хвилин: CRM ставить цей статус на Rozetka, лише поки угоду ніхто не рушив вручну. Під перемикачем — «переводити угоду на етап»: «не переводити (лише статус на Rozetka)» — угода лишається там, куди її поставив рядок «Пов'язаних статусів» (наприклад «1» → «Новий»); «перший етап «Прийнято» воронки» — перший за порядком етап з роллю «Прийнято» (у «Продажах» це «Бронь» — тому 15–17.10 нові замовлення опинялись на «Бронь»); або будь-який етап зі списку (лише своєї воронки). Власник 17.10 обрав «як у KeepinCRM»: «1» → «Новий», автоприйняття не переводить.

## 5. Магазини Rozetka: ТТН у точки видачі
1. «Налаштування продажів» → блок «Магазини Rozetka» → перемикач «Увімкнути створення ТТН в магазини Rozetka».
2. «Відправник»: «Оновити інформацію» підтягує відправника з налаштувань сервера; або заповніть ім'я, телефон, місто й відділення руками.
3. «Параметри відправлення»: довжина, висота, ширина, вага, об'єм і короткий опис (вага товарів угоди, якщо є, головніша).
4. «Доступ до доставки»: після підключення доступу нема ні в кого — поставте «Показати» тим, хто створює ТТН. Без галочки людина бачить і друкує ТТН, але створити не може.
5. В угоді з доставкою «Магазини Rozetka» у блоці «Доставка» ТТН створюється в точку видачі через Rozetka Delivery. Докладно — [Rozetka Delivery](int-rozetka-delivery.md).

## 5а. ТТН із замовлення: доставка ROZETKA Delivery (16.10)
Покупець вибрав у замовленні доставку ROZETKA Delivery — таке замовлення не приймає ТТН ззовні (ЕН з власного акаунта Rozetka Delivery Rozetka відхиляє: `check_correctness_of_data`). Накладну створює сама Rozetka — так робить і KeepinCRM.
1. Перемикач — «Налаштування продажів» → блок «Магазини Rozetka» → «ТТН із замовлення на боці Rozetka» (типово увімкнено). Вимкнули — в угоді знову звичайна шторка «Створити ТТН».
2. В угоді з Rozetka, де «Служба доставки (Rozetka)» — ROZETKA Delivery, у блоці «Доставка» «+» і «Додати місце» відкривають форму «ТТН із замовлення Rozetka».
3. «Замовлення Rozetka» — одержувач, куди й оплата: лише показ, Rozetka бере їх із замовлення (накладений платіж — як у замовленні).
4. «Параметри відправлення» — вага (0,1–30 кг), довжина, ширина, висота (1–120 см), місць, опис до 100 символів. Типово — посилка з налаштувань ROZETKA Delivery кабінету продавця (або вага товарів угоди, або параметри цієї картки).
5. «Відправник» — ПІБ, телефон, місто й відділення відправлення зі списку ROZETKA Delivery; типово — відправник за замовчуванням з кабінету продавця. Інше місто — введіть назву, список відділень оновиться. У списку всі відділення міста (Rozetka віддає їх сторінками по 50, форма збирає всі); відділення з кабінету, якого у списку нема, показується як «З кабінету Rozetka».
6. «Платник доставки» — одержувач або відправник; безкоштовна для покупця доставка (вартість у замовленні 0) — типово відправник.
7. «Створити ТТН на Rozetka» — ТТН з'являється в угоді (служба Rozetka Delivery), у полі `rozetka_ttn` і в трекінгу; стікер — «⋮ → Роздрукувати стікер» (друк Rozetka). У замовленні вже є ТТН — кнопка вимкнена, номер можна записати через «вручну». «Інший перевізник» — звичайна шторка.
8. Видалити таку ТТН можна лише в кабінеті продавця Rozetka (у Seller API методу нема); «⋮ → Видалити ТТН» пояснить це й запропонує прибрати її лише з угоди.

Доступ — той самий «Доступ до доставки» з блоку «Магазини Rozetka».

## 6. Імпорт старих замовлень і клієнтів
1. Спершу пов'яжіть статуси з етапами — інакше всі замовлення стануть на початковий етап.
2. «Імпорт замовлень і клієнтів» → «Запуск»: вкажіть «за N дн.» → «Запустити імпорт».
3. Імпорт іде у фоні сторінка за сторінкою (Rozetka віддає по 20 замовлень): «Триває», потім «Готово» з лічильниками «отримано, створено, оновлено, в архів». Виконані й скасовані замовлення йдуть в архів; дублі за `rozetka_order_id` не створюються.

## 7. Другий кабінет Rozetka (акаунти)
Картка «Rozetka» → «Підключення» → «Акаунти» → «+ Додати акаунт» → «Назва» і «API ключ (Seller API)» (можна пізніше) → «Додати акаунт». Новий акаунт вимкнений: перевірте ключ і ввімкніть. У нього свої ключ, вхід у кабінет, налаштування продажів і журнал. «Прибрати» — угоди лишаються, зникають ключ, налаштування й журнал акаунта.

## 8. Блок «Rozetka» в угоді
У картці угоди з джерелом Rozetka є блок «Rozetka (<джерело>)» з даними замовлення. Чого Rozetka не передала — «…». Значення, яке можна змінити, змінюється кліком по ньому.

| Рядок | Звідки (Seller API) | Поле угоди |
| --- | --- | --- |
| ID | номер замовлення | `rozetka_order_id` |
| Рейтинг клієнта, (id) | `user_rating`: 1 — високий, 2 — середній, 3 — низький відсоток викупу | `rozetka_user_rating`, `rozetka_user_rating_id` |
| Сума замовлення, Сума зі знижкою | `amount`, `amount_with_discount` (товари, без доставки) | `rozetka_order_amount`, `rozetka_amount_with_discount` |
| Статус замовлення | назва статусу (`status_data`), код — окремо | `rozetka_status`, `rozetka_status_code` |
| Коментар | коментар покупця | `rozetka_comment` |
| Джерело створення | `created_type`: від покупця, з кабінету продавця, по API… | `rozetka_source` |
| Історія статусу замовлення | `order_status_history`, найновіші зверху | `rozetka_status_history` |
| Спосіб оплати, Статус оплати | `payment`: метод оплати і статус («Оплачено»…) | `rozetka_payment_type`, `rozetka_payment_status` |
| ТТН, Спосіб доставки, ПІБ і телефон отримувача, Адреса, Вартість доставки | `ttn`, `delivery` | `rozetka_ttn`, `rozetka_delivery_*` |
| Інша особа отримувач | ПІБ або телефон отримувача не ті, що в покупця | `rozetka_other_recipient` |
| Перетелефоновувати | `callback_off`: «Ні», коли покупець просив не дзвонити | `rozetka_callback` |
| Фулфілмент | `is_fulfillment` | `rozetka_fulfillment` |

Комісії Rozetka Seller API у замовленні не віддає — рядок «Комісія» лишається порожнім.

- Натиск на **ID** або на **назву блоку** відкриває це замовлення в кабінеті продавця Rozetka (`seller.rozetka.com.ua/main/orders/all/<ID>`) у новій вкладці. Якщо ви ще не входили в кабінет у цьому браузері, Rozetka спершу попросить увійти. Замовлення з другого кабінету (акаунта) відкриється, коли в браузері виконано вхід саме в той кабінет.
- **«?»** праворуч у заголовку блоку відкриває цю статтю у шторці одразу на цьому розділі; «Відкрити у WIKI» — повна сторінка статті.

## Усі замовлення, не лише нові (14.10)
Приймання бере замовлення в УСІХ статусах Seller API (нові, підтверджені, у доставці, виконані, скасовані, повернення); етап — за мапою «статус → етап», без мапи — за змістом статусу (у доставці → «Відправлено», виконано → «Отримано», не буде → «Скасована», повернення → «Повернення»). У картці каналу → «Стан роботи» → «Вивантажити замовлення» за N днів назад.

## Якщо замовлення не з'являються
Опитування йде кожні 5 хвилин: Seller API `/orders/search` з групою «усі замовлення» двічі — від дати створення і від дати зміни (останнє опитування мінус 2 години), усі сторінки (по 20 замовлень). Так нові замовлення стають угодами, а оплата, статус і ТТН, що змінились на Rozetka пізніше, оновлюються в уже створених угодах. У картці Rozetka → «Журнал подій» має бути «intake: отримано N, створено M»; якщо рядків нема зовсім — замовлень за вікно не було; «ПОМИЛКА» з текстом — ключ чи Rozetka. «Вивантажити замовлення» за N днів у «Стані роботи» бере все заново без дублів.

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші Rozetka у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «Rozetka» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · Rozetka» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: сума з поля угоди `rozetka_commission` (її пише Rozetka). Виплата Rozetka на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки Rozetka ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: «ТОВ РОЗЕТКА ПЕЙ» платить і за Rozetka, і за Пром-оплату — транзит спільний, «Транзит · RozetkaPay (Prom, Rozetka)»; дохід — коли угода виграна, лише якщо «Тип оплати checkbox» Rozetkapay (картка, Apple/Google Pay, наложка ROZETKA Delivery; наложка Новою поштою йде через NovaPay). Комісія — одразу при замовленні, для будь-якої оплати: поле `rozetka_commission` — приймання бере його з API замовлення (`commission_sum` позицій × кількість, як KeepinCRM); порожнє чи 0 — комісії нема (рішення власника 20.10); з «Баланс · Rozetka» — це звірка, у P&L і «Грошовий потік» не входить; витрата на Rozetka — поповнення кабінету («Комісія Розетка» на гаманці, з якого платили, власник 21.10). Виплата з виписки — переказ із транзиту сам, винагорода з призначення — «Комісія RozetkaPay». Щодня (і кнопкою «Підтягнути з API за 7 днів» у шторці правила каналу) комісію звіряє журнал балансу кабінету з API: комісія замовлення мінус повернення при скасуванні — якщо інша, ніж у журналі, береться з кабінету; зарахування на баланс без замовлення — у підсумку як «поповнення». Докладно — «Фінанси», розділ 7а, «Виписка майданчика».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| Біля ТТН замість кнопки «На Rozetka» — підказка «Доставка ROZETKA Delivery — ТТН створює сама Rozetka…» | Замовлення з доставкою ROZETKA Delivery: накладну створює Rozetka після підтвердження даних, ТТН від продавця вона не приймає (`check_correctness_of_data`) | Нічого передавати не треба; якщо створили ЕН з власного акаунта Rozetka Delivery — вона зайва, видаліть її («⋮ → Видалити ТТН»); ТТН створіть формою «ТТН із замовлення» (розділ 5а) |
| «Rozetka не створила ТТН: …» у формі «ТТН із замовлення» | Rozetka відхилила дані посилки чи відправника (текст після двокрапки — від Rozetka) | Перевірте вагу, габарити, відділення відправлення; замовлення має бути в статусі, де Rozetka дозволяє створити ТТН |
| «На угоді вже є активна ТТН Rozetka …» | Друга ТТН Rozetka на ту саму угоду | Зайву ТТН спершу видаліть з угоди |
| «ТТН … створено в кабінеті Rozetka із замовлення — видалити її можна лише в кабінеті продавця» | У Seller API нема методу видалення такої ТТН | Видаліть у кабінеті продавця Rozetka, потім «Прибрати з угоди» |
| «Rozetka не прийняла ТТН: 1005 — check_correctness_of_data …» після «На Rozetka» | Rozetka не прийняла номер ТТН: щойно створена ЕН Rozetka Delivery ще не відома кабінету продавця або гонка статусів | Helomi сам повторює до 3 разів; не допомогло — натисніть «На Rozetka» ще раз за кілька хвилин; подробиці після коду — що саме не так |
| «Вкажіть логін і пароль кабінету продавця Rozetka» | Порожнє поле у формі входу | Заповніть обидва поля |
| «Rozetka не прийняла логін/пароль: …» | Неправильний логін чи пароль | Перевірте дані в кабінеті продавця |
| «Нема ключа Rozetka — увійдіть або введіть ключ API» | Немає ні входу, ні ключа | Увійдіть або введіть ключ |
| «не задано (у картці чи .env): ROZETKA_SELLER_API_KEY» | «Перевірити» без ключа | Увійдіть або введіть ключ |
| «Rozetka не приймає ТТН у статусі «…»» | З поточного статусу замовлення Rozetka не дозволяє перейти ні в 61, ні в 2, ні в 3 (наприклад, виконане чи скасоване) | Перевірте замовлення в кабінеті продавця |
| «Rozetka не дозволяє змінювати доставку замовлення …» | У замовленні `is_delivery_edit_available = false` | Змініть доставку в кабінеті продавця або зверніться в підтримку Rozetka |
| «У .env не задано ROZETKA_SENDER_NAME / PHONE / CITY / DEPARTMENT — заповніть відправника руками» | «Оновити інформацію» без відправника на сервері | Заповніть «Відправник» вручну |
| «Нема доступу до створення ТТН у магазини Rozetka — надайте його в картці Rozetka → …» | Людині не дано «Показати» в «Доступ до доставки» | Адміністратор ставить галочку в «Магазини Rozetka» → «Доступ до доставки» |
| Замовлення прийшло двічі | Rozetka ще підключена до KeepinCRM | Вимкніть Rozetka в KeepinCRM |

## Для ШІ-співробітників
5`). «ТТН із замовлення» (розділ 5а) ШІ робить тими самими маршрутами, що й форма: `shipping_list` (поле `rozetka_order`), `shipping_rozetka_order_form`, `shipping_rozetka_order_pickups`, `shipping_rozetka_order_create` (через кошик підтверджень — відправка назовні). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело «Rozetka», додаткові поля `rozetka_order_id`, `rozetka_status`, `rozetka_status_code`, `rozetka_payment_type`, `rozetka_payment_status`, `rozetka_order_amount`… і акаунт, з якого прийшла угода (`crm_integration`; для основного кабінету його нема). Статтю ШІ читає інструментом `help("int-rozetka")`.

Чого не робити: не створювати вручну угоду на замовлення, яке вже прийшло; не змінювати `rozetka_order_id`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Доставки і ТТН](shipping.md), [Rozetka Delivery](int-rozetka-delivery.md), [Prom](int-prom.md), [Переписки](chats.md).