Фінансовий контроль у KeepinCRM: оплати, борги, каса

1. Огляд проєкту

Клієнт — торгово-будівельний бізнес, який вів продажі, клієнтів, угоди й оплати в KeepinCRM, але фінансова логіка фактично жила поруч із CRM: у ручних перевірках, домовленостях менеджерів, касових діях, боргах, авансах і контролі керівника

CRM була зручною як операційний інтерфейс, але не була фінансовим двигуном. Система не могла самостійно рознести оплату по старих боргах, порахувати прострочку, відрізнити нормального клієнта від ризикового, заблокувати небезпечну відвантажувальну дію або дати керівнику зрозумілу картину взаєморозрахунків

Моя роль була побудувати навколо CRM фінансовий контур: middleware, який читає KeepinCRM через API, застосовує бізнес-правила, веде власний журнал, повертає результат у CRM, контролює борги, готує звітність і зв'язує касову операцію з фізичним фіскальним обладнанням

Це був не “інтегрувати API”. Це був випадок, де треба було взяти живий бізнес-процес із грошима, боргами, касою, менеджерами й керівником — і зробити його контрольованим

2. З чим прийшов клієнт

•Оплати не мали автоматичного рознесення: клієнт міг внести оплату “на себе”, але бізнесу потрібно було автоматично гасити найстаріші відкриті угоди, а не вручну розкидати суму по кожному замовленню

•Борг і аванс рахувались не як система: поточна заборгованість, переплата, залишок по угодах і прострочка мали бути видимими в CRM, але їх треба було обчислювати за правилами, яких у CRM не було з коробки

•Кредитний контроль був ручним: якщо клієнт перевищив ліміт або давно не оплатив відвантаження, менеджер все одно міг рухати процес далі без системного стоп-сигналу

•Керівнику потрібна була управлінська ОСВ: не бухгалтерський звіт “як у 1С”, а практична картина взаєморозрахунків: сальдо, відвантаження, оплати, кінцевий борг, аванс, прострочка і статус

•Каса була фізичною і старою: касовий комп'ютер працював на Windows 7, касовий апарат підключався локально, а CRM і middleware жили окремо від цього обладнання

•1С і каса не мали заважати одне одному: касир міг працювати з касою через старе ПЗ або RDP, тому агент мав захоплювати пристрій тільки на момент друку і одразу звільняти порт

•Подвійні дії були небезпечні: повторна обробка платежу або повторний друк чека могли створити реальні фінансові помилки, тому потрібні були ідемпотентність, журнал і контроль станів

3. Поставлені завдання

•Спроєктувати middleware між KeepinCRM і фінансовою логікою бізнесу

•Реалізувати FIFO-рознесення оплат: найстаріші борги закриваються першими

•Обробити часткові оплати, переплати, аванси й ситуації без відкритих угод

•Зробити перерахунок боргу, авансу, прострочки, статусу клієнта й utilization кредитного ліміту

•Реалізувати статуси OK / RISK / BLOCK і правила блокування ризикових клієнтів

•Блокувати критичні бізнес-дії, зокрема рух до відвантаження, якщо клієнт перевищив кредитний ліміт або має прострочку

•Дати керівнику ручне розблокування з логуванням: хто, коли, чому і яку угоду розблокував

•Побудувати звіт по взаєморозрахунках з фільтрами та Excel-експортом

•Підготувати касовий сценарій: створення чека, черга, друк, повернення статусу, фіскальний номер або помилка

•Написати локальний Windows-агент для касового ПК, який працює з фізичним фіскальним принтером

•Додати фонового “радар”: моніторинг нових оплат і змін угод без ручного запуску

4. Рішення та хід роботи

Financial Middleware Architecture

Анонімізована угода KeepinCRM з фінансовими етапами, оплатою і блокуванням

•KeepinCRM залишилась основним інтерфейсом для менеджерів, але складна фінансова логіка була винесена в окремий FastAPI middleware

•Middleware отримував дані через KeepinCRM API, нормалізував їх до власної фінансової моделі й повертав результат назад у CRM

•Усередині сервісу були розділені модулі: API-клієнт CRM, allocation engine, debt calculator, blocker, receivables reporter, receipt queue, local-agent endpoints і SQLite journal

•SQLite використовувалась не як “велика база”, а як контрольний журнал: allocations, recalculations, block_log, receipts, processed_payments, agent_status і agent_logs

•Архітектура була зроблена так, щоб бізнес міг і далі працювати в CRM, а не переходити в окрему фінансову систему

FIFO Payment Allocation

•Реалізовано endpoint для рознесення оплат по клієнту

•Система отримує відкриті угоди клієнта, бере тільки угоди з боргом, сортує їх за датою і гасить найстаріші першими

•Якщо оплата покриває угоду повністю — борг по ній закривається

•Якщо оплата менша за борг — угода залишається частково оплаченою

•Якщо оплата більша за всі відкриті борги — залишок переходить в аванс клієнта

•Якщо відкритих угод немає — вся сума стає авансом, а не губиться в ручному коментарі

•Для повторної обробки одного платежу додано ідемпотентність: платіж не розноситься вдруге, якщо вже є запис у журналі

Debt, Advance & Overdue Control

Анонімізована картка клієнта KeepinCRM з оплатою, задачами і автоматизацією

•Реалізовано перерахунок фінансового стану клієнта: борг, аванс, прострочка, кредитний ліміт, utilization і статус

•Прострочка рахується по відкритих угодах, де є залишок до оплати

•Статус клієнта визначається правилами:

•OK — борг і прострочка в межах норми

•RISK — борг наближається до ліміту або прострочка вже стала небезпечною

•BLOCK — перевищено кредитний ліміт або прострочка вийшла за допустимий поріг

•Система не просто показує цифри, а перетворює їх на управлінську дію: кого можна обслуговувати далі, кого треба перевірити, кого треба заблокувати

Blocking Rules & Manager Guardrails

•Реалізовано автоматичну перевірку клієнта перед критичною дією

•Якщо клієнт у статусі BLOCK, middleware повертає контрольований block response і не дозволяє рухати процес у ризиковому напрямку

•Для різних воронок передбачено налаштування “blocked stage”, щоб угода переходила на правильний етап блокування

•VIP/exceptions обробляються окремо: бізнес може мати ручні винятки, але вони не ламають загальну логіку

•Ручне розблокування дозволено тільки керівній ролі і записується в block_log з причиною

•Це важливо: система не відбирає контроль у керівника, але забирає у менеджера можливість непомітно проштовхнути ризикову відвантажувальну дію

Receivables Reporting

•Реалізовано управлінський звіт по взаєморозрахунках

•Звіт рахує opening balance, charges, payments, closing balance, advance, overdue days і debt status

•Додано фільтри за періодом, клієнтом, менеджером і статусом боргу

•Реалізовано Excel-експорт, щоб керівник міг отримати звичний файл для аналізу, наради або ручної перевірки

•Окремо було важливо не називати це бухгалтерською ОСВ: це управлінський контрольний звіт, який допомагає бачити ризики й гроші в операційному контурі CRM

Receipt Queue & Cash Register Flow

Журнал активності KeepinCRM з автоматизацією чеків і фіскальними статусами

•Для каси реалізовано receipt queue: CRM або middleware створює запит на чек зі статусом pending

•Локальний агент касира забирає найстаріший pending-чек, друкує його на фізичному пристрої і повертає результат у middleware

•Після успішного друку чек переходить у completed і зберігає fiscal number

•Якщо друк не вдався — чек переходить у failed з error message, а не губиться в ручному процесі

•Підтримано cash/card payment types, позиції чека, tax groups і refund-сценарії

Local Kassa Agent

Фізичні тестові чеки, надруковані через інтеграцію KeepinCRM з касою

•Окремо написано локальний агент для Windows 7 касового ПК

•Агент працює як маленький edge-service: polling middleware кожні кілька секунд, отримання pending-чека, підключення до каси, друк, повернення результату

•Для фізичного апарата реалізовано роботу через OLE/WinUSB driver

•Агент захоплює касу тільки на час друку і одразу відключається, щоб не конфліктувати зі старим касовим ПЗ або 1С/RDP

•Додано heartbeat, agent status, agent logs і endpoint для завантаження актуальної версії агента

•Для операційної надійності передбачено запуск через bat/vbs, прихований режим і автозапуск разом із Windows

Radar & Background Processing

•Реалізовано фоновий radar-процес, який перевіряє нові платежі та зміни угод

•Нові платежі автоматично проходять allocation flow і запускають перевірку блокування

•Зміни угод запускають повторну перевірку клієнта, щоб система не чекала ручного перерахунку

•При першому запуску radar seed-ить історичні записи як baseline, щоб не обробити старі платежі як нові

•Додано щоденний перерахунок боргів, щоб система відловлювала прострочку навіть без активних дій менеджера

5. Що отримав клієнт

•CRM стала не просто місцем, де лежать угоди, а інтерфейсом до контрольованого фінансового контуру

•Оплати почали розноситись за зрозумілим FIFO-правилом, а не ручним рішенням менеджера

•Борг, аванс, прострочка і статус клієнта стали обчислюваними сутностями, а не “відчуттям у голові”

•Ризикові клієнти отримали автоматичний стоп перед критичними діями

•Керівник отримав контрольований механізм override з журналом, а не хаотичне “ну ми домовились”

•Звітність стала доступною через API/UI та Excel, без ручного складання таблиць з різних місць

•Касова операція була з'єднана з CRM через чергу, статуси й локального агента

•Стара Windows 7 каса і фізичний пристрій були інтегровані без повної заміни робочого місця касира

•Система отримала запобіжники: idempotency, processed markers, block logs, receipt statuses, heartbeat і error messages

6. Технічний результат

У результаті з'явився повноцінний financial control layer для CRM:

•FastAPI middleware як центральний backend-контур

•KeepinCRM API integration для клієнтів, угод, оплат і кастомних полів

•FIFO allocation engine для автоматичного погашення найстаріших боргів

•Debt calculator для боргу, авансу, прострочки, utilization і OK/RISK/BLOCK статусів

•Blocking engine для автоматичного стопу ризикових угод і керівного ручного override

•Receivables reporter з Excel-експортом

•Receipt queue для касових чеків

•Windows kassa-agent для фізичного фіскального обладнання

•Radar background worker для нових платежів і змін угод

•SQLite audit journal для allocations, recalculations, block events, processed payments, receipts і agent logs

7. Чому це складний кейс

Цей проєкт був складний не через один API. Він був складний через межу між трьома світами:

•CRM, де працюють менеджери

•фінансові правила, де помилка означає реальні гроші

•фізична каса на старому Windows-комп'ютері, яку не можна просто “задеплоїти”

Треба було зробити так, щоб менеджери не змінювали звичний інтерфейс, керівник отримав контроль, платежі не дублювались, чеки не друкувались двічі, борги не ховались у коментарях, а фізична каса не конфліктувала з існуючим робочим місцем

Саме тут і була цінність роботи: я не просто написав інтеграцію, а зібрав контрольований операційний контур навколо CRM, який тримає гроші, борги, касу й управлінські рішення в одній логіці