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

# Monobank

Інтеграція з Monobank тягне виписку рахунку ФОП чи картки через особистий API банку в «Фінанси»: кожна операція проходить правила імпорту, надходження з номером угоди в призначенні саме стає оплатою по угоді, а решта чекає перевірки у «Вхідних». Рахунків може бути скільки завгодно — кожен підключається окремим акаунтом зі своїм токеном, гаманцем і налаштуваннями, а з увімкненими миттєвими операціями платіж з'являється у «Фінансах» за хвилину. Повторний імпорт дублів не створює.

## Можливості
- Скільки завгодно акаунтів Monobank: свій токен, свій рахунок банку, свій гаманець, свій журнал подій.
- Налаштування кожного акаунта мишкою, без розробника: рахунок, гаманець, хто бачить операції, вікно імпорту, холди, прив'язка до угод, миттєві операції.
- Імпорт кнопкою за період (до 31 доби за раз) і автоматично кроком ШІ Марії Йосипівни.
- Миттєві операції: банк повідомляє про кожен платіж, CRM одразу перечитує виписку.
- Надходження з «№50000123», «sg-50000123», номером рахунку чи ТТН у призначенні — оплата по несплаченій угоді без ручної роботи.
- Правила імпорту, звірка з уже внесеними операціями, «Вхідні» для решти — той самий шлях, що в ПриватБанку й NovaPay.
- Без дублів: повтор за id операції банку пропускається, хоч би звідки прийшов рядок (кнопка, Марія, вебхук).

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

**Токен.** Вкладка «Підключення» → рядок «Токен» → «Ввести» → вставте особистий токен → «Зберегти ключ» → «Перевірити» (успіх — «рахунків: N»). Токен береться на сайті api.monobank.ua (вхід через застосунок monobank). Він зберігається зашифрованим і більше ніде не показується — лише останні символи.

**Акаунти.** Основна картка — теж акаунт («Основний»; назву можна змінити в рядку «Назва акаунта»). Ще один рахунок — «+» у правому нижньому куті картки («Додати ще один Monobank») → «Назва» і токен → «Додати акаунт». Акаунти перемикаються під шапкою картки. Один акаунт — один токен і один рахунок банку: другий рахунок того самого клієнта (наприклад, ФОП і чорна картка) — це другий акаунт з тим самим токеном. Акаунт без токена нічого не імпортує: токен основної картки чи сервера він не позичає. Токен читається з картки в будь-якій організації Helomi, не лише в першій.

**Вкладка «Налаштування»** акаунта. Угорі — «Стан акаунта» (рахунок банку з балансом, гаманець, миттєві операції з адресою, останній імпорт) і кнопка «Оновити рахунки» (список рахунків з банку оновлюється сам раз на 10 хвилин). Нижче — форма; змінює її адміністратор, решта бачить без збереження. Зберегли — імпорт, Марія і вебхук беруть нове одразу.

| Поле | Що робить | Типово |
| --- | --- | --- |
| «Рахунок у банку (картка чи ФОП)» | з якого рахунку береться виписка; у підписі — вид, валюта, кінець IBAN і залишок | ФОП у гривні з найбільшим залишком, інакше гривневий із залишком, інакше перший |
| «Гаманець у «Фінансах»» | куди лягають операції | гаманець акаунта (створиться з назвою акаунта; для основної картки — «Монобанк») |
| «Хто бачить операції рахунку» | розділ 5 | усі з доступом до «Фінансів» |
| «Тягнути виписку автоматично (крок ШІ Марії)» | автоімпорт цього акаунта | так |
| «Скільки останніх днів виписки перечитувати щоразу» | вікно автоімпорту, 1–31 | 3 |
| «Не заносити операції, старші за дату» | нижня межа автоімпорту | без межі |
| «Заносити холди… в автоматичному імпорті» | незавершені операції карткою | ні |
| «Прив'язувати надходження до угоди за призначенням платежу» | розділ 4 | «номер угоди у призначенні» |
| «Миттєві операції» → «Вебхук банку» | розділ 3 | вимкнено |

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

## 2. Імпорт виписки
1. «Фінанси» → «Операції» → «Імпорт виписки» (кнопку бачать ті, хто може проводити платежі).
2. Блок «Monobank»: «Акаунт» (поле є, коли акаунтів більше одного), «Рахунок» і «Гаманець» — «з налаштувань акаунта» або
   інший («Показати рахунки»), «Від» і «До».
3. «Імпортувати з Monobank». Під кнопкою — підсумок: «нових N, за правилами N, прив'язано до угод N, звірено з внесеними N,
   у «Вхідні» N, пропущено N».

Кнопка заносить і холди (як раніше); поле «Заносити холди» діє на автоімпорт Марії й вебхук. Автоматично виписку тягне крок ШІ Марії Йосипівни по кожному увімкненому акаунту з «Тягнути виписку автоматично»; загальний вимикач — пульт Марії → «Налаштування» → «Виписки банків» → «Заносити виписку Monobank у «Фінанси»». Пропустив імпорт якісь дні (сервер стояв, банк не відповідав) — наступний крок сам перечитує виписку від останнього вдалого імпорту мінус 5 хв, не далі 31 доби (22.10). Кожен рядок проходить правила імпорту («Налаштування → Фінанси → Правила імпорту»), звіряється з уже внесеними операціями (та сама сума й напрямок за ±3 дні), а без правила й угоди — потрапляє у «Фінанси → Звірка → Вхідні» з підказкою категорії. Докладно — стаття [Фінанси](finance.md), розділ 7. Операції акаунта підписані ним: журнал подій картки показує, хто й коли імпортував.

## 3. Миттєві операції (вебхук)
Вкладка «Налаштування» → «Вебхук банку…» → «Зберегти». CRM реєструє в банку свою адресу `…/api/crm/finance/bank/webhook/monobank/<секрет акаунта>` (у кількох організаціях — ще й `?org=<компанія>`). Банк перевіряє її запитом і далі на кожну операцію надсилає подію; CRM відповідає одразу, а виписку акаунта за останні хвилини перечитує у тлі — тілу події не вірить, джерело правди лише виписка. Стан видно в «Стані акаунта» і в «Стан роботи» → «Миттєві операції» («увімкнено · останнє надходження …», адреса з кнопкою «Скопіювати»).

- Банк тримає одну адресу на токен, і ліміт виписки (1 запит на хвилину) теж на токен: два акаунти з одним токеном ділять
  ліміт, а подія для одного перечитує всі увімкнені акаунти з цим токеном.
- Для рахунків ФОП, до яких вас додали «бухгалтером» (доступ до чужого рахунку), банк подій не надсилає — такі рахунки
  тягнуться лише імпортом.
- Адреса містить секрет: не публікуйте її. Чужий секрет — «не знайдено»; частіше 60 запитів на хвилину — відмова.
- Банк не прийняв адресу — «Вебхук не ввімкнено: … Інші налаштування збережено»: решту форми записано, вебхук лишився вимкненим.

## 4. Прив'язка надходжень до угоди
Поле «Прив'язувати надходження до угоди за призначенням платежу» (лише доходи, лише **несплачена** угода):
- «номер угоди у призначенні» — «№50000123», «#50000123», «sg-50000123», «угода 50000123», «замовлення 50000123»;
- «номер рахунку (документа)» — номер документа угоди, напр. «РФ-ZK-2026-0012»;
- «ТТН» — номер накладної доставки угоди;
- «усе разом» або «не прив'язувати».

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

## 5. Хто бачить операції рахунку
Доступ іде через гаманець акаунта: поле «Хто бачить операції рахунку» — це «Доступ до гаманця» у «Фінансах» (порожньо — усі з доступом до розділу). Хто не має гаманця, не бачить ні його операцій, ні балансу. На відміну від KeepinCRM, окремого «лише доходи / лише витрати» нема: людина бачить усі операції рахунку або жодної.

## Особисті картки окремими акаунтами («Картки цього токена»)
Один токен Monobank бачить усі рахунки й картки власника: ФОП, білу, чорну, валютні. У «Налаштуваннях» акаунта є блок **«Картки цього токена»**: біля кожної — залишок (у кредитки ще кредитний ліміт) і позначка: «рахунок цього акаунта», «акаунт «…»» (уже підключена) або кнопка **«Підключити як акаунт»** (лише адміністратору).
1. Відкрийте «Інтеграції → Monobank → Налаштування» основного акаунта (того, чий токен бачить картку).
2. Біля потрібної картки натисніть «Підключити як акаунт».
3. CRM створює акаунт «Біла картка Monobank …3229» з тим самим токеном. Його «Рахунок банку» — ця картка, «Тягнути виписку
   автоматично» увімкнено, «Не заносити операції, старші за дату» — сьогодні, щоб старі особисті покупки не потрапили в журнал.
4. Гаманець — виду **«Особистий»**: наявний особистий гаманець з кінцем номера картки в назві (наприклад, заведений раніше
   вручну «Біла картка Monobank …3229»), а якщо такого немає — новий. Він показується у «Фінанси → Гаманці → Картки фізосіб»
   і в «гроші бізнесу» не входить. Виписку тягне крок Марії звичайними правилами імпорту.
5. Баланс гаманця одразу дорівнює залишку картки в банку: CRM ставить **звірену точку** із залишку картки на момент підключення
   (подія «Звірена точка … залишок картки на момент підключення» в журналі акаунта). Витрати, внесені вручну до підключення, у
   баланс уже не входять — вони сидять у залишку банку; стартовий залишок вгадувати не треба. Докладно — стаття
   [Фінанси](finance.md), розділ «6а. Звірка з банком».
Підключену картку вдруге не підключити («Цю картку вже підключено як акаунт …»). Вимкнути — перемикачем акаунта.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Monobank не налаштовано: додайте токен (MONOBANK_TOKEN) у картці «Інтеграції → Monobank»» | в акаунта нема токена | «Підключення» → «Токен» → «Ввести» |
| «Monobank: токен не прийнято (403) — перевірте MONOBANK_TOKEN» | токен відкликано чи з помилкою | новий токен на api.monobank.ua |
| «Monobank: не частіше 1 запиту на хвилину — зачекайте хвилину і повторіть» | ліміт банку на токен | повторіть за хвилину |
| «Monobank: за один запит банк віддає не більше 31 доби — зменште період» | вікно більше 31 доби | імпортуйте частинами |
| «Monobank: рахунок із налаштувань акаунта банк не показує — оберіть інший» | рахунок закрито чи це інший токен | «Оновити рахунки», оберіть рахунок |
| «Вебхук не ввімкнено: … Інші налаштування збережено» | банк не зміг відкрити адресу CRM | перевірте, що сайт доступний ззовні, збережіть ще раз |
| Миттєві операції увімкнено, а подій нема | рахунок «бухгалтера» або банк вимкнув вебхук після трьох невдач | імпорт кнопкою; вимкніть і знову ввімкніть вебхук |
| Надходження не прив'язалось до угоди | угоду вже сплачено, номера нема в призначенні або вибрано «не прив'язувати» | «Вхідні» → «Угода (№)» |
| «Імпорт виписки …: нових 0 (за N дн. по рахунку … операцій нема…)», у журналі акаунта червона подія «Увага: …» раз на добу | у «Налаштуваннях» обрано рахунок без руху (другий ФОП, закрита картка) — виписка читається з нього | «Оновити рахунки», оберіть у «Рахунок у банку» той, де є залишок (він у підписі), «Імпорт виписки» за потрібні дні |
| У журналі акаунта «Звірка залишку: у банку … у гаманці … різниця …; холди …; нез'ясовано …» | нез'ясована різниця з банком тримається довше, ніж «Через скільки днів» у «Налаштування → Фінанси → Звірка з банком» (типово 2; раз на добу, від 100 ₴ — червоним) | «Фінанси → Гаманці» → «Розібрати» на картці гаманця: холди, внесені вручну без пари в банку; якщо банк правий — «Прийняти залишок банку» |
| Автоімпорт не тягне акаунт | акаунт вимкнено, без токена або вимкнено «Тягнути виписку автоматично» | увімкніть у картці |

## Для ШІ-співробітників
Картка `describe_section("int-monobank")` — поля імпорту, дії, приклади і довідники (`monobank_accounts` — акаунти, `purses` — гаманці); доступ — розділ «Фінанси» у «Доступах» ШІ, імпорт — ще й «Фінанси: проводити й змінювати платежі». Ті самі маршрути й перевірки, що в людини; у журналі подій акаунта імпорт підписано ШІ.
- `monobank_accounts` (`kind`) — рахунки й банки акаунта з банку: id, тип, валюта, баланс, IBAN (для `account`).
- `monobank_import` (`values`: `kind`, `from`, `to`; `account`, `purse_id`, `holds` — за потреби) — імпорт виписки;
  **чекає підтвердження людини** (вид `bulk`), повтор дублів не створює.
- Що не прив'язалось — `finance_inbox`; прив'язати дохід до угоди — `finance_review` з `values={action: ok, deal_id: …}`
  (картка `finance`, вид `payments`).

ШІ **не може** змінювати налаштування акаунтів, вмикати вебхук, вводити чи читати токени — інструментів для цього нема, маршрут налаштувань ШІ відмовляє; це робить адміністратор у картці. Не імпортуйте без прохання людини, не повторюйте дію з `pending_id` і не вигадуйте `kind` — беріть з `monobank_accounts` у картці.