Invoice Matcher for AbraFlexi

Package installation after running (creates necessary labels UNIDENTIFIED and MISSINGINVOICE)

There are three scripts available for invoice matching:

ParujFakturyNew2Old.php - matches invoices day by day up to 3 months back. ParujVydaneFaktury.php - attempts to match all unmatched issued documents. ParujPrijateFaktury.php - attempts to match all unmatched received documents. ParujPrijatouBanku.php - attempts to match suitable invoices to the given incoming payment.

The algorithm is as follows:

• Download bank statements to abraflexi.
• All unmatched receipts in the bank are processed ( /c/company_ltd_/bank/(matched eq false AND movementType eq 'movementType.receipt' AND cancellation eq false AND issueDate eq '2018-03-07' )?limit=0&order=issueDate@A&detail=custom:id,code,varSym,specSym,totalSum,issueDate ).
• Payments are then processed one by one in a loop.
• For each incoming payment, the program tries to find a suitable (unpaid and uncanceled) document to match. First by variable symbol. Finally by simple specific symbol.
• Results are unified by bank movement number in abraflexi to avoid duplicates when an invoice meets multiple search criteria.
• Payments that do not have a counterpart found by any condition are labeled UNIDENTIFIED.
• If an invoice is not found for the payment, the payment is labeled MISSINGINVOICE.

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.

Debian/Ubuntu

For Linux, .deb packages are available. Please use the repo:

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-matcher

After installing the package, the following new commands are available in the system:

• abraflexi-matcher - matches all capable invoices.
• abraflexi-matcher-in - matches all capable received invoices.
• abraflexi-matcher-out - matches all capable issued invoices.
• abraflexi-matcher-new2old - matches incoming payments day by day from the newest to the oldest.
• abraflexi-pull-bank - only downloads bank statements.
• abraflexi-match-bank - matches incoming payments.
• abraflexi-transaction-report - generates bank transaction reports in JSON format.

Dependencies

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.

Testing:

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.

Configuration

• /etc/abraflexi/client.json - common configuration for connecting to the AbraFlexi server.
• /etc/abraflexi/matcher.json - matcher settings:

   "APP_NAME": "InvoiceMatcher",             - application name
   "EASE_MAILTO": "info@yourdomain.net",     - where to send reports
   "EASE_LOGGER": "syslog|mail|console",     - how to log
   "PULL_BANK": "false",                     - download bank before matching
   "DAYS_BACK": "7"                          - 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" -
   "ABRAFLEXI_OVERPAY": 'OST. ZÁVAZKY'       - code of document type for overpayment

Other software for AbraFlexi

• 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

Acknowledgements

This software would not have been created without the support of:

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.

Exit Codes

Applications in this package use the following exit codes:

Transaction Report (abraflexi-transaction-report)

• 0: Success - transactions report generated successfully
• 1: 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

Other Applications

• 0: Success
• 400: Bad request - invalid data or parameters

Error Handling

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.