Financial Control Layer for KeepinCRM: Payments, Debt and Ca

1. Project Overview

The client is a trade and construction business running customers, deals, payments and daily sales work in KeepinCRM. The CRM worked well as an operational interface, but the real financial logic lived around it: manual checks, manager decisions, cash desk routines, debts, advances and owner-level approvals

The CRM could not automatically allocate a payment across older open debts, calculate overdue exposure, separate a healthy customer from a risky one, block a dangerous shipment step or give management a clean receivables view

My role was to build a financial control layer around the CRM: middleware that reads KeepinCRM through API, applies business rules, keeps its own audit journal, writes results back, controls debt, generates management reporting and connects cash operations to physical fiscal hardware

This was not “just an API integration”. It was a live money process with payments, debts, cash desk work, managers and owner decisions that had to become controlled

2. What The Client Had

•Payments were not allocated automatically: a customer could pay at client level, but the business needed the system to close the oldest open deals first instead of manually splitting the amount across orders

•Debt and advance were not systemic: current debt, overpayment, remaining deal balances and overdue days had to become visible in CRM, but CRM did not provide that logic out of the box

•Credit control was manual: a manager could keep moving a deal even when the customer exceeded the credit limit or had overdue shipment debt

•Management needed a practical receivables report: not a strict accounting ledger, but a useful operating view: opening balance, shipments, payments, closing debt, advance, overdue days and status

•The cash register was physical and old: the cashier workstation ran Windows 7, the fiscal device was local, and the CRM/middleware lived far away from that hardware

•1C/RDP and the register had to coexist: the agent could not permanently capture the device. It had to take control only for the print action and release it immediately

•Duplicate actions were dangerous: processing one payment twice or printing a receipt twice would create real financial errors, so idempotency and audit state were mandatory

3. Scope

•Design middleware between KeepinCRM and the business financial rules

•Implement FIFO payment allocation: oldest debts are paid first

•Handle partial payments, overpayments, advances and clients without open deals

•Recalculate debt, advance, overdue days, customer status and credit-limit utilization

•Implement OK / RISK / BLOCK statuses and blocking rules

•Block critical business actions, especially shipment flow, when credit limit or overdue thresholds are violated

•Give management a manual unblock mechanism with a clear log

•Build a receivables report with filters and Excel export

•Implement cash-register flow: receipt creation, queue, printing, result status, fiscal number or error

•Write a local Windows agent for the cashier PC and physical fiscal device

•Add background monitoring for new payments and changed deals

4. Solution

Financial Middleware Architecture

Anonymized KeepinCRM deal with financial stages, payment status and blocking flow

•KeepinCRM remained the interface for the team, while financial logic moved into a FastAPI middleware service

•The middleware reads CRM data through API, maps it into a financial model and writes controlled results back to CRM

•The service is split into focused modules: CRM client, allocation engine, debt calculator, blocker, receivables reporter, receipt queue, local-agent endpoints and SQLite journal

•SQLite acts as a control journal for allocations, recalculations, block events, receipts, processed payments, agent status and agent logs

•The business kept working in CRM instead of adopting a separate financial tool

FIFO Payment Allocation

•Implemented a payment allocation endpoint at customer level

•The system fetches open customer deals, selects deals with outstanding debt, sorts them by date and closes the oldest debt first

•Full payments close a deal; partial payments leave a clear remaining amount

•Overpayment becomes customer advance instead of getting lost in comments

•If there are no open deals, the whole amount becomes advance

•Reprocessing the same payment is blocked by idempotency checks and allocation journal records

Debt, Advance & Overdue Control

Anonymized KeepinCRM customer card with payment, tasks and automation activity

•Implemented recalculation of customer debt, advance, overdue exposure, credit utilization and status

•Overdue days are calculated from open deals with remaining debt

•Customer status follows deterministic rules:

•OK — debt and overdue exposure are within allowed limits

•RISK — debt or overdue days are approaching a dangerous level

•BLOCK — credit limit or overdue threshold is violated

•The system turns numbers into operating action: who can keep moving, who needs attention and who must be blocked

Blocking Rules & Manager Guardrails

•Implemented automatic customer checks before critical actions

•If a customer is in BLOCK status, middleware returns a controlled block response instead of allowing risky movement

•Different funnels can have different blocked-stage mappings

•VIP exceptions are handled explicitly without breaking the standard rule set

•Manual unblock is available only for a management role and is written to block_log with reason and actor

•The point was not to remove human control, but to stop invisible risky movement by regular managers

Receivables Reporting

•Built an operating receivables report

•The report calculates opening balance, charges, payments, closing balance, advance, overdue days and debt status

•Added filters by period, customer, manager and debt status

•Implemented Excel export so management can use the data in meetings, reviews and manual audits

•The report was intentionally positioned as management control, not formal accounting replacement

Receipt Queue & Cash Register Flow

KeepinCRM activity log with receipt automation and fiscal status updates

•Implemented a receipt queue: CRM or middleware creates a pending receipt

•The local cashier agent pulls the oldest pending receipt, prints it on the physical device and sends the result back

•Successful receipts move to completed and store fiscal number

•Failed receipts keep a failure state and error message

•The flow supports cash/card payments, receipt items, tax groups and refund scenarios

Local Kassa Agent

Physical test receipts printed through the KeepinCRM cash-register integration

•Built a local Windows 7 agent for the cashier workstation

•The agent polls middleware, receives pending receipts, connects to the fiscal device, prints and returns the result

•The fiscal printer integration works through OLE/WinUSB driver

•The agent captures the device only during printing and releases it immediately to avoid conflicts with legacy cashier software and 1C/RDP

•Added heartbeat, agent status, agent logs and downloadable agent endpoint

•Added operational launch options: bat/vbs start, hidden mode and Windows startup

Radar & Background Processing

•Implemented a background radar process for new payments and changed deals

•New payments trigger allocation and blocking checks

•Changed deals trigger customer risk recalculation

•On first start, historical payments and deals are seeded as baseline to avoid accidental reprocessing

•A daily recalculation job catches overdue changes even when no manager action happened

5. What The Client Got

•CRM became an interface for a controlled financial workflow, not just a place where deals are stored

•Payments became allocated by a clear FIFO rule instead of manager discretion

•Debt, advance, overdue exposure and status became calculated entities

•Risky customers received automatic stop-points before critical actions

•Management got controlled override with audit log

•Receivables reporting became available through API/UI and Excel export

•Cash desk operations were connected to CRM through queue, statuses and a local agent

•Legacy Windows 7 and physical fiscal hardware were integrated without replacing the cashier workplace

•The system gained safety rails: idempotency, processed markers, block logs, receipt states, heartbeat and error messages

6. Technical Result

The result was a financial control layer around KeepinCRM:

•FastAPI middleware as the central backend

•KeepinCRM API integration for customers, deals, payments and custom fields

•FIFO allocation engine for oldest-debt-first payment allocation

•Debt calculator for debt, advance, overdue days, utilization and OK/RISK/BLOCK states

•Blocking engine for automatic risk stops and management override

•Receivables reporter with Excel export

•Receipt queue for fiscal receipts

•Windows kassa-agent for physical fiscal hardware

•Radar background worker for new payments and deal changes

•SQLite audit journal for allocations, recalculations, block events, processed payments, receipts and agent logs

7. Why This Case Was Hard

The hard part was not one API. It was the border between three worlds:

•CRM, where managers do daily work

•financial rules, where mistakes mean real money

•a physical fiscal device on an old Windows workstation

The solution had to keep the familiar CRM interface, give management control, avoid duplicate payments and duplicate receipts, expose debts instead of hiding them in comments, and print through local hardware without breaking the cashier workstation

That is the value of this work: not a generic integration, but a controlled operating layer around CRM that keeps money, debt, cash desk flow and management decisions in one logic