Matches AbraFlexi bank payments to issued/received invoices, by variable symbol, specific symbol, bank account number/IBAN, or all combined - as standalone CLI scripts, cron jobs, or MultiFlexi applications.
- How it works
- Installation (Debian/Ubuntu)
- Commands
- Configuration
- Languages
- MultiFlexi
- Flowcharts
- Exit Codes
- Error Handling
- Dependencies
- Testing
- Other software for AbraFlexi
- Acknowledgements
For each unmatched incoming payment, the matcher looks for a suitable (unpaid, uncanceled) invoice - by variable symbol, specific symbol, or the sender's bank account number/IBAN, depending on which script is run. Results are unified by bank movement number to avoid duplicates when an invoice satisfies more than one search criterion.
- Payments with no matching invoice found by any condition are labeled MISSINGINVOICE (or reported as
unmatched). - Payments that could not be identified at all are labeled UNIDENTIFIED.
- An account number/IBAN registered to more than one company in AbraFlexi's address book is reported as
duplicate_bucinstead of being guessed at.
Matched documents are then paired as follows:
- INVOICE - the payment is matched with the invoice + the paid invoice is sent from AbraFlexi to the client's email.
- ADVANCE - the advance invoice is matched with the payment + a tax document with the same variable symbol is created, from which this advance is deducted.
- CREDIT - the credit note is deducted.
- Others - a warning is logged in the protocol along with a link to the web AbraFlexi.
Overpayments and underpayments are never settled automatically by abraflexi-match-varsym, abraflexi-match-specsym, abraflexi-match-accountno, abraflexi-matcher-out, abraflexi-match-received-payment, or abraflexi-matcher-in - a mismatch between the paid amount and the invoice amount is only logged and reported (overpaid/underpaid in the JSON report), and the invoice is left open for manual review by accounting staff. Set ABRAFLEXI_OVERPAY / ABRAFLEXI_PARTIAL_MATCH to opt back into automatic settlement of overpayments/underpayments.
.deb packages are available from two repositories, depending on how up to date vs. how stable you need the package to be:
- repo.vitexsoftware.com - test/nightly channel. Publishes automatically on every merge to
main; newest features and fixes land here first, but it hasn't been through a formal release. - repo.multiflexi.eu - production channel (release/security). Only tagged releases are published here; use this for production deployments.
Test/nightly (repo.vitexsoftware.com):
wget -qO- https://repo.vitexsoftware.com/keyring.gpg | sudo tee /etc/apt/trusted.gpg.d/vitexsoftware.gpg
echo "deb [signed-by=/etc/apt/trusted.gpg.d/vitexsoftware.gpg] https://repo.vitexsoftware.com $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo apt update
sudo apt install abraflexi-matcherProduction (repo.multiflexi.eu):
wget -qO- https://repo.multiflexi.eu/KEY.gpg | sudo tee /etc/apt/trusted.gpg.d/multiflexi.gpg
echo "deb [signed-by=/etc/apt/trusted.gpg.d/multiflexi.gpg] https://repo.multiflexi.eu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/multiflexi.list
sudo apt update
sudo apt install abraflexi-matcherAfter installing the package, run abraflexi-matcher-init once per AbraFlexi company (creates the labels/document types the other scripts rely on).
- abraflexi-matcher - matches all capable invoices.
- abraflexi-matcher-in - matches all capable received invoices.
- abraflexi-matcher-out - matches all capable issued invoices (all matching methods combined).
- abraflexi-matcher-new2old - matches incoming payments day by day from the newest to the oldest.
- abraflexi-matcher-init - creates the AbraFlexi labels/document types required by the matcher scripts.
- abraflexi-pull-bank - only downloads bank statements.
- abraflexi-match-bank - matches incoming payments.
- abraflexi-match-cash - legacy variant matching issued invoices via AbraFlexi's own bank-matching logic.
- abraflexi-match-received-payment - matches one specific incoming payment on demand.
- abraflexi-match-varsym - matches issued invoices against received payments by variable symbol only.
- abraflexi-match-specsym - matches issued invoices against received payments by specific symbol only.
- abraflexi-match-accountno - matches issued invoices against received payments by the sender's bank account number/IBAN only.
- abraflexi-transaction-report - generates bank transaction reports in JSON format.
Configuration is read from environment variables (or a .env file next to the scripts - see example.env; /etc/abraflexi/client.json / /etc/abraflexi/matcher.json are no longer used):
APP_NAME=InvoiceMatcher - application name
EASE_MAILTO=your@email.tld - where to send reports
EASE_LOGGER=console|syslog - how to log
MATCHER_DAYS_BACK=300 - how many days back to match
MATCHER_LABEL_PREPLATEK=OVERPAYMENT - label for marking more than the required amount for the paid invoice
MATCHER_LABEL_CHYBIFAKTURA=MISSINGINVOICE - label for marking payment for which no invoice was found
MATCHER_LABEL_NEIDENTIFIKOVANO=UNIDENTIFIED - label for marking payments that could not be identified at all
ABRAFLEXI_OVERPAY='OST. ZÁVAZKY' - code of document type for overpayment, empty (default) = do not settle overpayments automatically
ABRAFLEXI_PARTIAL_MATCH=false - settle underpayments (partial payments) automatically, default false = do not settle automatically
MATCHER_LOCALIZE=en_US - language for messages and logs, default en_US, available en_US|cs_CZ|sk_SK
The source language of messages and logs is English (en_US); translations are available for Czech (cs_CZ) and Slovak (sk_SK) - see i18n. The language is set via the MATCHER_LOCALIZE variable (available as a select field on each application in MultiFlexi).
AbraFlexi Matcher is ready to run as a MultiFlexi application. See the full list of ready-to-run applications within the MultiFlexi platform on the application list page.
| Application | Command | |
|---|---|---|
 |
Bank Statements Puller | abraflexi-pull-bank |
 |
Transaction Report | abraflexi-transaction-report |
 |
Received Invoices Matcher | abraflexi-matcher-in |
 |
Issued Invoices Matcher | abraflexi-matcher-out |
 |
Payment Matcher (single payment) | abraflexi-match-received-payment |
 |
Match Received Payments by Variable Symbol | abraflexi-match-varsym |
 |
Match Received Payments by Specific Symbol | abraflexi-match-specsym |
 |
Match Received Payments by Bank Account Number | abraflexi-match-accountno |
Decision flow of the three split payment matchers (what parameters they read and how they branch):
Matches domestic payments by account number + bank code (buc/smerKod) and foreign payments by IBAN, flagging ambiguous account numbers found registered to more than one company as duplicate_buc in the report.
0: Success - transactions report generated successfully1: General error - unexpected error occurred (retryable)2: Connection error - unable to connect to AbraFlexi server (critical, retryable)3: I/O error - failed to write output file
0: Success400: Bad request - invalid data or parameters
The transaction report application includes robust error handling:
- Connection failures: When the AbraFlexi server is unreachable, the application logs a detailed error message and exits with code 2, allowing for automatic retry.
- MultiFlexi compliance: Generates reports in MultiFlexi-compliant JSON format with status, timestamp, metrics, and artifacts.
- Graceful degradation: All errors are properly caught, logged, and reported with appropriate exit codes.
This tool uses the following libraries for its functionality:
- EasePHP Framework - helper functions such as logging.
- AbraFlexi - communication with AbraFlexi.
- AbraFlexi Bricks - classes for Customer, Reminders, and Reminder.
Basic functionality testing is available and can be run with the command make test in the project's source folder.
Test invoices and payments can be created with the command make pretest.
Package build + package installation test + package function test is handled by Vagrant.
- Regular reports from AbraFlexi
- Reminder sender
- Client Zone for AbraFlexi
- Tools for testing and managing AbraFlexi
- Monitoring AbraFlexi server function
- AbraFlexi server without graphical dependencies
This software would not have been created without the support of:
