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

# Епіцентр

Інтеграція з Епіцентр Маркетплейсом приймає замовлення напряму в «Угоди» за офіційним Merchant API: клієнт, товари, статус, а назад на Епіцентр іде статус замовлення і ТТН. Підключається одним натиском: вставити «API ключ» і натиснути «Підключити Епіцентр». Залишки товарів на Епіцентрі оновлює ШІ Аня.

## Можливості
- Замовлення за датою оновлення кожні 5 хвилин; перше опитування — за останні два дні.
- Нові замовлення одразу переводяться в «Підтверджено продавцем»: поки замовлення «Нове», Епіцентр не показує даних покупця.
- Угода створюється лише для робочих статусів; угоди, що вже прийшли з KeepinCRM, знаходяться за номером і не дублюються. Якщо з одним номером замовлення є кілька угод (наприклад, злитий дубль в архіві), оновлення статусу йде в угоду, що в роботі. Злиті 13.10 дублі (50000001–50000005) видалено 15.10 у «Видалену інформацію» — у картці клієнта лишається одна угода.
- «Пов'язані статуси» (14 статусів Епіцентру) → етапи угоди; один статус можна прив'язати до кількох етапів.
- «Передавати статус і ТТН на Епіцентр»: дозволені проміжні статуси CRM надсилає сама, перед «Відправлено» — ТТН угоди.
- Автоматична ТТН на етапах, фід товарів, кілька магазинів зі своїми ключами.
- Блок «Епіцентр» в угоді заповнюється повністю: сума, коментар, історія статусів, оплата, ТТН, доставка й адреса з номером відділення, вартість доставки, отримувач, комісія. Назва блоку і ID відкривають замовлення в кабінеті Епіцентру.

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

1. Рядок «API ключ» → «Ввести» → вставте ключ → «Зберегти ключ». Ключ береться в кабінеті Епіцентру: «Налаштування → Налаштування компанії → Додаткові параметри → «Підключення до API по замовленням»». Зберігається зашифрованим, показуються лише останні символи.
2. «Перевірити» читає одне замовлення зі списку (лише читання).
3. Вкладка «Налаштування продажів»:
   - «Основне»: «Увімкнути інтеграцію», «Джерело угод», «Відповідальний»;
   - «Нові замовлення»: «Підтвердження» — перемикач «Автоматично «Нове» → «Підтверджено продавцем»» (типово ввімкнено), «Автоприйняття», «Зв'язувати товари по»;
   - «Пов'язані статуси» з перемикачем «Передавати статус і ТТН на Епіцентр»;
   - «Передача ТТН на маркетплейс»: статуси, на яких Епіцентр приймає номер ТТН (типово «Підтверджено», «Підтверджено продавцем»), і «спершу перевести» («Нове» → «Підтверджено продавцем» → «Підтверджено»). В угоді — «⋮» рядка ТТН → «Передати ТТН на Епіцентр» (`PATCH …/shipment-number`; лише Нова Пошта, Укрпошта, Meest; статус «Відправлено» не ставиться — його передає етап угоди).
   - «Автоматична відправка ТТН», «Фід для маркетплейсу» («Фід каналу з прайс-листа» `/feed/channel/epicentr.xml` — оголошення Епіцентру з папки «Епіцентр» прайс-листа, ціна «Ціна Епіцентр», залишок зі складу Helomi; його з 14.10 читає ШІ Аня; і фід усього складу).

Унизу — «Зберегти» і «Скасувати зміни».

Дані замовлення пишуться в додаткові поля угоди з ключами `epicentrk_order_id`, `epicentrk_status` (як у KeepinCRM) і `epicentr_*` — повний перелік у таблиці [розділу 5](#5-блок-епіцентр-в-угоді). Поля налаштовуються в «Налаштування → Типи даних → Угоди». Юрособа угод Епіцентру — правилом «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

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

Набір «одним натиском» узято з компанії власника. Повторно — «Застосувати налаштування знову».

**Важливо.** Того ж дня вимкніть інтеграцію Епіцентру в KeepinCRM — інакше обидві CRM підтверджуватимуть і рухатимуть ті самі замовлення.

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

«Адреса доставки» угоди — місто й відділення з номером: «Київ, Відділення №17: бульв. Лесі Українки, 10» (до 15.10 номер губився — лишалась лише вулиця); інший тип точки — «№55555: вул. …»; самовивіз із магазину — назва магазину й адреса.

У списку замовлень Епіцентр не віддає назв міста й відділення — лише в повних даних замовлення. Тому для нової угоди CRM одразу читає повні дані, а для наявної — щойно замовлення на Епіцентрі змінилось (ТТН, статус, доставка, отримувач). Незмінені замовлення повторно не читаються. Угоди, що прийшли з KeepinCRM, дочитуються при першому опитуванні або коли угоду відкрили.

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

## 5. Блок «Епіцентр» в угоді
У картці угоди з джерелом Епіцентр є два блоки.

**«Епіцентр (<джерело>)»** — дані замовлення. Чого Епіцентр не передав, показано як «…». Рядків, яких у Епіцентру не буває (рейтинг покупця, сума зі знижкою, джерело створення, фулфілмент), у блоці нема. Вони з'являються, лише коли поле в угоді вже є, наприклад в угоді з KeepinCRM.

| Рядок | Звідки (Merchant API) | Поле угоди |
| --- | --- | --- |
| ID | номер замовлення | `epicentrk_order_id` (`epicentr_order_id`) |
| Сума замовлення | `subtotal` (товари) | `epicentr_order_amount` |
| Статус замовлення | назва статусу, код — окремо | `epicentrk_status`, `epicentr_status_code` |
| Коментар | коментар покупця і «До доставки: …» | `epicentr_comment` |
| Історія статусу замовлення | Епіцентр історії не віддає — її веде CRM: рядок на кожну зміну статусу (київський час), найновіші зверху. Перший рядок — статус на момент першого читання | `epicentr_status_history` |
| Спосіб оплати, Статус оплати | `paymentProvider`, `paymentStatus` («Кошти заблоковано»…) | `epicentr_payment`, `epicentr_payment_status` |
| ТТН | номер ТТН, який знає Епіцентр (переданий з CRM або створений Епіцентром), з кнопкою «Скопіювати» | `epicentr_ttn` |
| Спосіб доставки | служба | `epicentr_service` |
| ПІБ і телефон отримувача | отримувач (інша особа, якщо її вказано) | `epicentr_recipient_name`, `epicentr_recipient_phone` |
| Інша особа отримувач | `isAlternateRecipient` | `epicentr_other_recipient` |
| Адреса доставки | населений пункт і точка видачі з номером: «Київ, Відділення №17: бульв. Лесі Українки, 10»; інша точка — «№55555: вул. …»; самовивіз — назва магазину й адреса; кур'єр — вулиця, будинок, квартира | `epicentr_delivery_address` (`epicentr_settlement`, `epicentr_office`) |
| Вартість доставки | `deliveryPrice` | `epicentr_delivery_cost` |
| Перетелефоновувати | «Ні», коли покупець просив не телефонувати для підтвердження (`skipCustomerContact`) | `epicentr_callback` |
| Комісія | деталізація рахунку замовлення (`orderCommissionTotal`). Потрібне право ключа на рахунки. Без нього рядок лишається як був, приймання не зупиняється | `epicentr_commission` (`epicentrk_commission` з KeepinCRM) |

В угодах з KeepinCRM адреса лежить у двох полях, «Населений пункт» і «Відділення». Блок показує їх разом в одному рядку.

- Натиск на **назву блоку** або на **ID** відкриває замовлення в кабінеті Епіцентру (`admin.epicentrm.com.ua/oms/orders/<id замовлення>`) у новій вкладці. Кабінет відкриває замовлення за внутрішнім id (uuid), а не за номером. Тому в угоді з KeepinCRM посилання з'являється після першого відкриття угоди: блок нижче знаходить замовлення за номером і запам'ятовує його id. Якщо ви ще не входили в кабінет у цьому браузері, Епіцентр спершу попросить увійти.
- **«?»** праворуч у заголовку відкриває цю статтю у шторці одразу на цьому розділі.

**«Епіцентр <№>»** — живий стан замовлення: статус, доставка, ТТН, історія статусів і дії. Дії приходять із сервера: передати статус, «Передати ТТН» з номером, «Відмінити…» з причиною; кнопка «Оновити». Номер у заголовку теж відкриває замовлення в кабінеті. Коли блок відкривається, CRM бере свіжі дані замовлення з Епіцентру й одразу дописує їх у поля угоди: доставку, ТТН, оплату, суми, id замовлення. Картка перечитується, а в журналі угоди з'являється запис «оновлено з Епіцентру (відкрито угоду)». Статус блок у поля не пише: зміну статусу й рух етапу робить приймання, щоб етап не пропустити.

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

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

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

З 20.10 увімкнено: «Транзит · Епіцентр», дохід — коли угода виграна й оплачена на майданчику (monobank, картка), комісія — поле `epicentr_commission` з API (порожнє чи 0 — комісії нема, рішення власника 20.10), одразу при замовленні з того самого транзиту (мінус — ми винні Епіцентру). Оплата рахунку Епіцентру за комісію з банку категорією «Комісія Епіцентр» — переказ у цей транзит, а не друга комісія.

**Оплата замовлення (з 22.10).** Передоплату Епіцентр платить кожне замовлення окремо через еквайринг monobank: рядок виписки «Оплата замовлення 58372062. Покриття за проведені трансакції згідно договору еквайринга Еквайринг, MM033489, Загалом 130.00 грн. Комісія банку 1.69 грн.» від АТ «УНІВЕРСАЛ БАНК». Правило імпорту «Оплата замовлень (еквайринг monobank, Епіцентр)» знаходить угоду з цим номером замовлення: угода вже нарахована в «Транзит · Епіцентр» — переказ з транзиту на рахунок (підстава — угода) і комісія банку з транзиту; ще ні — дохід угоди на 130 ₴ і комісія 1,69 ₴ витратою по угоді; угоди нема — рядок у «Вхідних» з поясненням. Докладно — стаття [Фінанси](finance.md), розділ 7, п. 11. До 22.10 ці рядки правило «Кешбек і відсотки банку» клало в «Інші доходи»; два такі рядки (15.10 і 19.10) перенесено скриптом.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): EPICENTR_TOKEN» | Ключ не введено | «Підключення» → «API ключ» → «Ввести» |
| «Нема API ключа Епіцентру в картці інтеграції» | Дія в угоді без ключа | Введіть ключ у картці |
| «Угода не з Епіцентру (нема номера замовлення Епіцентру)» | В угоді нема `epicentrk_order_id` | Дія лише для угод з Епіцентру |
| «В угоді нема ТТН — створіть ТТН (блок «Доставка») і передайте ще раз» | «Відправлено» без ТТН | Створіть ТТН в угоді й повторіть |
| У журналі: перехід не дозволено | Епіцентр не приймає такий перехід статусу | Перевірте «Пов'язані статуси» або змініть статус у кабінеті |
| Замовлення рухаються двічі | Епіцентр ще підключений до KeepinCRM | Вимкніть Епіцентр у KeepinCRM |
| Назва блоку без посилання | В угоді ще нема id замовлення Епіцентру (угода з KeepinCRM) | Відкрийте угоду ще раз після того, як блок «Епіцентр <№>» завантажився, або натисніть «Оновити» |
| «Комісія» порожня | Ключ API не має права на рахунки (`processing.my.invoice.read`) | Дайте ключу це право в кабінеті Епіцентру або дивіться комісію в кабінеті |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело «Епіцентр», поля `epicentrk_order_id`, `epicentrk_status`, `epicentr_*` (таблиця розділу 5: ТТН `epicentr_ttn`, адреса `epicentr_delivery_address`, історія `epicentr_status_history` тощо) і акаунт, з якого прийшла угода (`crm_integration`). Ці поля заповнює приймання — ШІ їх не редагує. Статтю ШІ читає інструментом `help("int-epicentr")`.

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