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

# Prom

Інтеграція з Prom приймає замовлення з вашого кабінету Prom прямо в «Угоди»: клієнт знаходиться за телефоном або створюється, товари зв'язуються зі складом, доставка й оплата лягають у картку угоди. Через Prom приходять і угоди магазинів Rozetka, що працюють через Prom; переписки з покупцями йдуть у «Переписки», а залишки й ціни можна оновлювати на Prom зі свого складу.

## Можливості
- Нові замовлення Prom (статуси «Новий» і «Прийнято») опитуються кожні 5 хвилин і стають угодами; повторне надходження того самого замовлення дубля не створює, а оновлює статус і додаткові поля.
- Джерело й відповідальний для угод каналу, зв'язок позицій з товарами за артикулом, ID маркетплейсу або назвою.
- Таблиця «Пов'язані статуси»: статус Prom → етап угоди; скасовані замовлення йдуть на етап скасування з причиною.
- «Передавати етап назад на маркетплейс»: менеджер рухає угоду — статус на Prom змінюється сам.
- Автоприйняття «Новий» → «Прийнято» через N хвилин, автоматична ТТН на вибраних етапах.
- Чати про товари й замовлення в «Переписках», оператори чату.
- Оновлення залишків і цін на Prom зі складу і адреса фіду товарів.
- Кілька кабінетів Prom: кожен зі своїм ключем, налаштуваннями й журналом.

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

1. **Ключ.** У картці відкрийте вкладку «Підключення» → рядок «API ключ» → «Ввести» (або «Змінити»), вставте токен і натисніть «Зберегти ключ». Токен створюється в кабінеті Prom у налаштуваннях API. Ключ зберігається зашифрованим і більше ніде не показується повністю — лише останні символи («задано (••••1234)»). «Прибрати» стирає ключ з CRM; тоді діє значення з налаштувань сервера, якщо воно там є.
2. **Перевірка.** «Перевірити» робить безпечний запит лише на читання. Успіх — «Зв'язок є: доступ до замовлень є» з часом; помилка — текст від Prom.
3. **Налаштування продажів.** Друга вкладка картки — «Налаштування продажів». Блоки:
   - «Основне»: перемикач «Увімкнути інтеграцію», «Джерело угод», «Відповідальний»;
   - «Нові замовлення»: «Автоприйняття» з затримкою в хвилинах, «Зв'язувати товари по» (артикул / ID маркетплейсу / назва);
   - «Чати», «Пов'язані статуси», «Автоматична відправка ТТН», «Фід для маркетплейсу».

Унизу липка панель: «Зберегти» (активна лише зі змінами) і «Скасувати зміни». Зберігати може лише адміністратор.
4. **Увімкнення.** Перемикач «Інтеграція» у «Підключенні» або «Увімкнути інтеграцію» в «Налаштуваннях продажів» — це одне й те саме: приймати замовлення каналу напряму в угоди. Вибір зберігається в базі й переживає перезапуск сервера.

Поля угоди, у які лягають дані замовлення, налаштовуються як завжди — «Налаштування → Типи даних → Угоди». Дані Prom пишуться в додаткові поля з ключами `prom_order_id`, `prom_status`, `prom_payment_type`, `prom_delivery_address` та інші (ті самі ключі, що ставила інтеграція KeepinCRM).

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

**Важливо при переході з KeepinCRM.** Якщо Prom ще підключений до KeepinCRM, замовлення приходять у Helomi дзеркалом. Увімкнули приймання тут — того ж дня вимкніть Prom у KeepinCRM, інакше замовлення прийде двічі.

## 2. Приймати замовлення в угоди
1. Увімкніть інтеграцію (див. вище).
2. Кожні 5 хвилин CRM забирає нові замовлення Prom.
3. Для кожного замовлення: клієнт шукається за телефоном у будь-якому форматі (нема — створюється з джерелом каналу); угода отримує назву = № замовлення Prom, етап за «Пов'язаними статусами» (без мапи — початковий етап «Новий»), позиції — товари складу за вибраним полем (не знайдено — позиція без товару); доставка — у полях блоку «Доставка» угоди («Адреса доставки», «Одержувач», «Телефон одержувача», «Спосіб доставки»), рядок ТТН з'являється, коли ТТН створено. «Адреса доставки» — як дав Prom, лише відділення Нової Пошти названо повністю: «Київ, Відділення №88 (до 30 кг): вул. …» (Prom пише «№88»); поле Prom «prom_delivery_address» — дослівно.
4. Що сталося, видно в картці: «Стан роботи → Приймання замовлень» (час останнього прогону, скільки створено й оновлено) і «Журнал подій».

На телефоні картка йде в одну колонку; таблиця статусів стає картками рядків.

## 3. Пов'язані статуси і статус назад на Prom
1. «Налаштування продажів» → «Пов'язані статуси» → «+ Додати статус».
2. У рядку: «Статус на Prom» (Новий, Прийнято, Оплачено, Виконано, Скасовано, Відхилено, Чернетка), «Етап угоди», для етапу скасування — «Причина скасування» і «Коментар покупцю».
3. Нова угода стає на етап з мапи. Якщо замовлення прийшло повторно зі зміненим статусом, що є в мапі (або скасоване), угода рухається на відповідний етап — із записом у журналі й складськими наслідками етапу.
4. Перемикач «Зворотний зв'язок» → «Передавати етап назад на маркетплейс»: коли менеджер переводить угоду на етап з мапи, CRM ставить відповідний статус на Prom (для скасування — з причиною). Типово вимкнено.

## 4. Автоприйняття, автоматична ТТН, чати
- **Автоприйняття**: «Автоматично переводити з «Новий» на «Прийнято»» через вказані хвилини. Діє, лише поки угоду ніхто не рушив вручну. «Переводити угоду на етап» (17.10): перший за порядком етап з роллю «Прийнято» (типово), обраний етап своєї воронки або «не переводити».
- **Автоматична відправка ТТН**: позначте етапи (чипи по воронках) і «Службу доставки» (або «з даних угоди (інакше Нова Пошта)»). Коли угода переходить на позначений етап, ТТН створюється сама — лише якщо активної ТТН ще нема і є дані доставки. Помилка пишеться в журнал каналу.
- **Передача ТТН на маркетплейс**: статуси замовлення Prom, на яких приймається декларація (типово «Прийнято», «Оплачено»), і перемикач «спершу перевести в потрібний статус» («Новий» → «Прийнято»). В угоді — «⋮» рядка ТТН → «Передати ТТН на Prom» (`POST /delivery/save_declaration_id`; лише Нова Пошта, Укрпошта, Meest). Номер замовлення береться з поля `prom_order_id` і завжди йде на Prom цілим числом — навіть якщо поле має тип «число» (з імпорту KeepinCRM) чи номер записано з «№». Служба «ukr_poshta» з KeepinCRM — це Укрпошта. Якщо на Prom уже стоїть інша ТТН, підтвердження питає, чи замінити її (і попереджає, якщо стара вже в дорозі).
- **Чати**: «Чати про товари», «Чати про замовлення» і «Оператори» — хто відповідає. «Відкрити переписки →» веде в «Переписки».

## 5. Оновлення товарів і фід
- У «Підключенні» → «Стан роботи» рядок «Оновлення товарів» показує, автоматично чи вручну оновлюються залишки й ціни на Prom зі складу; «Оновити зараз» запускає оновлення.
- «Налаштування продажів» → «Фід для маркетплейсу»: перший рядок — «Фід каналу з прайс-листа» (`/feed/channel/prom.xml`: оголошення Prom з ціною з прайс-листа і залишком зі складу), другий — фід усього складу `/feed/all.xml`; у кожного «Скопіювати». Адреси не змінюються — змінюються лише товари в них. З 14.10 Аліна читає склад Helomi (`CRM_BACKEND=local`), не KeepinCRM.
- Як Аліна знаходить оголошення у фіді (23.10): спершу за точним артикулом («К000028» кирилицею і «K000028» латиницею — різні товари). Двійник з іншою літерою береться лише тоді, коли він у фіді один. Якщо двійників кілька, Аліна не вгадує: ставить оголошенню 0 і «Немає в наявності», а артикул записує в журнал прогону як «неоднозначний». Виправте артикул оголошення на Prom або в прайс-листі, і наступний прогін поставить правильну кількість.

## 6. Другий кабінет Prom (акаунти)
1. Картка «Prom» → «Підключення» → блок «Акаунти» → «+ Додати акаунт».
2. «Назва» (як підписати кабінет, напр. «Semenchenko Prom») і «API ключ» (можна ввести й пізніше) → «Додати акаунт».
3. Відкриється картка нового акаунта. Новий акаунт створюється вимкненим: перевірте ключ («Перевірити») і ввімкніть.
4. В акаунта свої перемикач, ключ, «Налаштування продажів» (джерело, відповідальний, мапа статусів) і журнал; ключ основної картки він не бере.
5. Перейменувати — поле «Назва акаунта»; прибрати — «Прибрати» (угоди лишаються, зникають ключ, налаштування й журнал акаунта).

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

- Натиск на **ID** або на **назву блоку** відкриває це замовлення в кабінеті Prom (`my.prom.ua/cms/order/edit/<ID>`) у новій вкладці.
- **«?»** праворуч у заголовку блоку відкриває цю статтю у шторці одразу на цьому розділі; «Відкрити у WIKI» — повна сторінка статті.

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

## Статуси Prom у картці угоди (15.10)
Панель «Prom» у картці угоди показує коди Prom людською мовою: «Статус замовлення» — «Новий», «Прийнято», «Оплачено», «Виконано», «Скасовано» (кольоровою пігулкою: зелена — оплачено чи виконано, жовта — новий, червона — скасовано); «Статус оплати» — «Оплачено», «Не оплачено», «Повернено покупцю», «Виплачено продавцю»; «Джерело створення» — «Сайт Prom», «Застосунок Prom», «Сайт компанії на Prom», «Кабінет компанії», «Bigl». У полі зберігається код Prom (`paid`, `mobile_catalog_app`…), його видно в підказці при наведенні; за кодом рухаються етапи. Власний статус магазину (`custom-…`) показується як є.

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

З 20.10 увімкнено: Пром-оплату виплачує «ТОВ РОЗЕТКА ПЕЙ» разом з оплатами Rozetka, тож транзит спільний — «Транзит · RozetkaPay (Prom, Rozetka)»; дохід — коли угода виграна (отримана покупцем), лише Пром-оплата чи «Тип оплати checkbox» Rozetkapay. Комісія — одразу при замовленні, для будь-якої оплати: поле `prom_commission` — приймання бере його з API замовлення (`cpa_commission`, є й у накладеному платежі; повернена — 0); порожнє чи 0 — комісії нема (рішення власника 20.10); списується з «Баланс · Prom» (кабінет) — це звірка, у P&L і «Грошовий потік» не входить. Витрата на Prom — поповнення кабінету: «Комісія Прому» з чату Марії чи рядок виписки «prom.ua» — «Комісія ПРОМ» на гаманці, з якого платили (власник 21.10). Виплата «РОЗЕТКА ПЕЙ» з виписки — переказ із транзиту сам, винагорода з призначення — «Комісія RozetkaPay». API балансу в Prom нема, тож звірити комісію з кабінетом — «Завантажити виписку» у шторці правила каналу: файл історії балансу з кабінету Prom (XLSX чи CSV) — списання «оплата за замовлення» по номерах замовлень стають комісією угод, повернення її зменшують, поповнення й решта — у підсумку як «інше». Докладно — «Фінанси», розділ 7а, «Виписка майданчика».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): PROM_API_TOKEN» | Ключ не введено | «Підключення» → «API ключ» → «Ввести» |
| У журналі картки «статус не опитано — …: Incorrect status value» | Prom не знає такого статусу списку | Решта статусів опитується далі; якщо помилка на всіх — перевірте токен і версію Helomi |
| «Помилка: …» або «HTTP 401» після «Перевірити» | Prom не прийняв токен | Створіть новий токен у кабінеті Prom і замініть ключ |
| «Prom не перевів замовлення … у «Прийнято» (без цього декларацію не прийме): …» | Замовлення на Prom «Новий», і Prom відмовив перевести його в «Прийнято» перед передачею ТТН; причина — текст Prom після двокрапки | Перевірте замовлення в кабінеті Prom (скасоване, чуже, іншого кабінету); переведіть у «Прийнято» там і передайте ТТН ще раз |
| «Prom не прийняв декларацію: …» | Prom відмовив записати ТТН (уже є інша, не та служба доставки) | Перевірте замовлення в кабінеті Prom і службу доставки ТТН |
| «Перемикати канали може лише адміністратор» | Ви не адміністратор | Попросіть адміністратора |
| «Акаунт з ключем «…» уже є» | Така назва вже зайнята іншим акаунтом | Дайте акаунту іншу назву |
| «Пов'язані статуси, рядок N: оберіть етап» | У рядку мапи не вибрано етап | Виберіть етап або приберіть рядок |
| «Пов'язані статуси: статус «…» з тим самим етапом вказано двічі» | Дубль рядка | Приберіть зайвий рядок |
| «Затримка автоприйняття: від 0 до 1440 хв» | Завелика затримка | Вкажіть менше число |
| Замовлення прийшло двічі | Prom ще підключений і до KeepinCRM | Вимкніть Prom у KeepinCRM |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» через `deals_list` / `deals_get`: джерело угоди, додаткові поля `prom_order_id`, `prom_status` (код Prom: `pending`, `received`, `paid`, `delivered`, `canceled`), `prom_payment_status` (`paid`, `unpaid`, `refunded`, `paid_out`), `prom_source`, `prom_payment_type`, `prom_delivery_address`… і акаунт, з якого прийшла угода (поле `crm_integration`, напр. `prom-semenchenko`; для основного кабінету його нема). Цю статтю ШІ читає інструментом `help("int-prom")`.

Чого не робити: не створювати вручну угоду на замовлення Prom, яке вже прийшло (шукати за № замовлення в `deals_list`); не змінювати поле `prom_order_id` — за ним CRM впізнає повтор.

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