Advanced Matching in FlexiBee

TL;DR ✨

The author presents one of the genuinely useful pieces of work created by Vitex Software for ABRA FlexiBee.

The problem is simple: payment matching in standard FlexiBee tends to be too weak for messy real-world accounting.

🎯 The Problem

The author presents one of the genuinely useful pieces of work created by Vitex Software for ABRA FlexiBee.

The problem is simple: payment matching in standard FlexiBee tends to be too weak for messy real-world accounting.

The built-in options are limited:

Very often you end up in one of two states:

• either the built-in matching simply does not work well enough
• or it works so vaguely that you still finish the job manually

That is where php-flexibee-matcher becomes interesting.

Project: https://github.com/VitexSoftware/php-flexibee-matcher

🧠 What the Matcher Does

The package creates helper labels such as NEIDENTIFIKOVANO and CHYBIFAKTURA and provides two main scripts:

[ParujFakturyNew2Old.php](src/ParujFakturyNew2Old.php) - matches invoices day by day, going backwards for up to 3 months
[ParujFaktury.php](src/ParujFaktury.php)               - tries to match all unmatched documents

The algorithm roughly works like this:

• bank statements are pulled into FlexiBee
• all unmatched incoming bank items are processed
• payments are handled one by one
• the program first tries to find a matching unpaid, non-cancelled document by variable symbol
• then it falls back to specific symbol logic
• duplicates are normalized against the bank movement number
• items without a valid counterpart are labeled accordingly

The handling then differs by document type:

FAKTURA - payment is matched with the invoice and the paid invoice is emailed to the client
ZALOHA  - advance invoice is matched and the corresponding tax document is created
DOBR    - credit note deduction is processed
Other   - a warning is logged with a link to the FlexiBee web UI

🐧 Debian and Ubuntu Installation

The original project offered .deb packages via a repository:

wget -O - http://v.s.cz/info@vitexsoftware.cz.gpg.key|sudo apt-key add -
echo deb http://v.s.cz/ stable main > /etc/apt/sources.list.d/ease.list
apt update
apt install php-flexibee-matcher

After installation, two commands should be available:

• php-flexibee-matcher - matches everything that can be matched
• php-flexibee-matcher-new2old - processes day by day from newer payments towards older ones

⚙️ Configuration

The key config files were:

• /etc/flexibee/client.json - shared connection settings to the FlexiBee server
• /etc/flexibee/matcher.json - matcher behavior

Example settings:

"EASE_APPNAME": "InvoiceMatcher",
"EASE_MAILTO": "info@yourdomain.net",
"EASE_LOGGER": "syslog|mail|console",
"PULL_BANK": "false",
"DAYS_BACK": "7"

🧪 What the Author Wanted from It

For the author's testing, the main expectation was simple: let documents be matched according to more useful criteria than the default built-in path.

Typical matching goals:

1. Match by variable symbol.
2. Match by variable symbol + specific symbol.
3. Match by specific symbol only.
4. Match inside a chosen date tolerance, for example +/- 20 days.

That is the practical value here. Not "automation for the sake of automation", but less manual accounting pain.

🧰 Local Test Lab Recipe

For testing at home, the author used this rough process:

1. Download the source ZIP from GitHub: https://github.com/VitexSoftware/php-flexibee-matcher/archive/master.zip
2. Install Vagrant: https://www.vagrantup.com/downloads.html
3. Install VirtualBox: https://www.virtualbox.org/wiki/Downloads
4. Unzip the source, enter the project directory, and run:

vagrant up

5. Wait for the Debian VM to build, then connect with:

vagrant ssh

6. Edit client.json in /vagrant so it contains your FlexiBee URL, login, password, and company name.

Example:

{
  "FLEXIBEE_URL": "https://MyCompany.flexibee.eu:5434",
  "FLEXIBEE_LOGIN": "flexiuser",
  "FLEXIBEE_PASSWORD": "secretPassword",
  "FLEXIBEE_COMPANY": "demo"
}

7. Edit matcher.json, for example:

{
  "EASE_APPNAME": "InvoiceMatcher",
  "EASE_MAILTO": "yourMail@connectica.cz",
  "EASE_LOGGER": "mail|console",
  "PULL_BANK": "false",
  "DAYS_BACK": "14"
}

8. Start the matcher:

/usr/bin/php-flexibee-matcher

Then watch what happens and start tuning.

🔧 Reality Check

Once you do all this, the real phase begins: adjustment and debugging.

Every business has its own document habits, bank formats, payment symbols, and exceptions. A matcher can save a lot of time, but only after you teach it enough of your operational reality.

And yes, if you get stuck badly enough, contacting Víťa was part of the original survival strategy.

If you already have this working and want to continue, the next level mentioned in the original article was the reminder tool: https://github.com/VitexSoftware/php-flexibee-reminder