diff --git a/account_ebics/README.rst b/account_ebics/README.rst index bd4afa3..c483521 100644 --- a/account_ebics/README.rst +++ b/account_ebics/README.rst @@ -1,219 +1,259 @@ -.. image:: https://img.shields.io/badge/license-LGPL--3-blue.png - :target: https://www.gnu.org/licenses/lgpl - :alt: License: LGPL-3 - ====================== -EBICS banking protocol +EBICS Banking Protocol ====================== -Implementation of the EBICS banking protocol. +**Exchange files directly with your banks from Odoo, with no portal and nobody logging in.** -This module facilitates the exchange of files with banks via the EBICS protocol. +EBICS, the Electronic Banking Internet Communication Standard, is the channel European +banks open to companies that want their software to talk to the bank. Bank statements are +downloaded on a schedule and payment files are uploaded from Odoo, authenticated by your +own cryptographic keys instead of a login page. -| +This module implements that protocol in Odoo. It is developed and maintained by +Noviat, and follows each new version of Odoo, which matters when a bank connection has to +survive your next migration. -Installation +If you are still working out whether EBICS is the right channel for you, we explain it +without the jargon, with screen recordings of the flow in Odoo, on +`noviat.com/ebics `_. + +.. image:: https://raw.githubusercontent.com/Noviat/account_ebics/19.0/account_ebics/static/description/ebics_flow.png + :alt: Statements come down as camt.053 or camt.052 files, payment files go up as pain.001 or pain.008, and your keys stay on your own server + :width: 100% + +What you get ============ -The module depends upon +- **Statements that arrive on their own.** A scheduled task collects the files your bank + publishes, for every account, and processes them into bank statements. +- **Payments that leave the same way.** A payment batch or a payment order is uploaded to + the bank in the format the bank expects, without exporting a file and re-uploading it + somewhere else. +- **Several companies, one connection.** Keys are held per bank rather than per company: + when fifteen entities bank with the same institution, the bank sends a single daily file + carrying fifteen statements and the module puts each statement in the right company. +- **No bank credentials in Odoo.** The connection uses your own company keys, generated on + your side and kept on your server. Access to the EBICS configuration is a permission of + its own ('EBICS Manager'), separate from ordinary accounting rights. +- **A test mode, where your bank offers one.** French banks accept a test flag, so a file + can be submitted and validated before anything is switched to production. German and + Swiss banks generally do not: there the first payment is a real one, kept small and sent + to an account you control. +- **A trace of every exchange.** Each download and each upload is a record, with the file + it carried, the moment it happened and the user behind it. -- https://pypi.python.org/pypi/fintech -- https://pypi.python.org/pypi/cryptography +**EBICS 2.4**, **EBICS 2.5** and **EBICS 3.0** are supported. EBICS 3.0, the current +specification since December 2022, names what is exchanged with BTF instead of the +country-specific order type codes of EBICS 2.x. Many banks still run 2.4 or 2.5 in parallel. -Remark: +What travels over the link +========================== -The EBICS 'Test Mode' for uploading orders requires fintech 4.3.4 or higher for EBICS 2.x -and fintech 7.2.7 or higher for EBICS 3.0. +- **Coming in:** camt.053 for the end of day statement, camt.052 for intraday movements + where the bank offers them, and national formats such as the French CFONB. +- **Going out:** pain.001 for credit transfers and pain.008 for direct debits, generated by + Odoo from your payment batches. -SWIFT 3SKey support requires fintech 6.4 or higher. +We do not process MT940 statements: the format carries bank and country specific variations, +and the Odoo community stopped maintaining a general parser for it after Odoo 10. Where a +bank publishes camt.053 alongside it, which is now the usual case, that is the format to use. -| +Which banks +=========== -We also recommend to consider the installation of the following modules: +Any bank that publishes an EBICS access point can be connected. The standard is maintained by +EBICS SC, a company held by the German, French, Swiss and Austrian banking bodies +(DK, CFONB, SIX and PSA), and it is the standard corporate channel in those countries. -| +To check a specific bank before you start, joonis publishes a public directory at +`joonis.de/en/fintech/banks `_. Enter a BIC and it +returns the SEPA services the bank offers, the EBICS versions it supports and its Host-ID. -- account_ebics_oe +A bank missing from that directory is not a no: it is joonis' own list, not an official +register. Ask your bank whether it publishes an EBICS access point. - Required if you are running Odoo Enterprise +What it costs +============= - Cf. https://github.com/Noviat/account_ebics +**This module is free software**, published under LGPL-3. There is no licence fee, no +subscription and no per-connection charge from Noviat. -| +It does however rely on the `fintech `_ library from +joonis, and that library requires a **commercial licence for production use**: as soon as +you upload SEPA files with more than five transactions, retrieve statements older than the +last three days, or use the distributed signature. The licence is contracted directly with +joonis, not with Noviat. -- account_ebics_batch +joonis charges a one-off setup fee plus a monthly fee per EBICS user id. Current pricing is +published on +`joonis.de `_. - This module adds a cron job for the automated import of EBICS files. +Your bank may also charge a subscription for the EBICS channel itself. It varies from one +bank to another and is billed by the bank, separately from anything on the Odoo side. - Cf. https://github.com/Noviat/account_ebics +Requirements +============ -| +The module depends on two Python libraries: -- account_ebics_batch_payment +- `fintech `_ +- `cryptography `_ - Recommended if you are using the Odoo Enterprise account_batch_payment module +Because the connection needs a Python library and your key files on the server, it runs on +**Odoo.sh** or on an **on-premise** installation. - Cf. https://github.com/Noviat/account_ebics +The EBICS test mode for uploads requires fintech 4.3.4 or higher for EBICS 2.x and fintech +7.2.7 or higher for EBICS 3.0. SWIFT 3SKey support requires fintech 6.4 or higher. -| - -- account_usability - - Recommended if you have multiple financial journals. - This module adds a number of accounting menu entries such as bank statement list view - which allows to see all statements downloaded via the ir.cron automated EBICS download. - - Cf. https://github.com/OCA/account-financial-tools - -| - -- account_ebics_payment_order - - Required if you are using the OCA account_payment_order module. - - Cf. https://github.com/OCA/bank-payment - -| - -- account_ebics_oca_statement_import - - Required if you are using the OCA Bank Statement import modules. - - https://github.com/OCA/bank-statement-import - -| - -- account_statement_import_fr_cfonb - - Required to handle french CFONB files. - - Cf. https://github.com/OCA/l10n_france - -| - -- account_statement_import_camt - - Required to handle camt.052 and camt.054 files. - - Cf. https://github.com/OCA/bank-statement-import - -| - - -Fintech license +Fintech licence --------------- -If you have a valid fintech.ebics license, you should add the following -licensing parameters to the [options] section of the odoo server configuration file: +With a fintech licence, add its parameters to the ``[options]`` section of the Odoo server +configuration file: +- ``fintech_register_name``: the name of the licensee; +- ``fintech_register_keycode``: the keycode of the licensed version. -- fintech_register_name - -The name of the licensee. - -- fintech_register_keycode - -The keycode of the licensed version. - -| -| Example: -| - -:: +Example:: ; fintech fintech_register_name = MyCompany fintech_register_keycode = AB1CD-E2FG-3H-IJ4K-5L -| +Companion modules +================= -Cf. https://www.joonis.de/en/fintech/prices/ +From this repository: -| +- **EBICS - Odoo Enterprise Integration** (``account_ebics_oe``): required on Odoo + Enterprise; installed automatically. +- **EBICS - Scheduled File Import** (``account_ebics_batch``): downloads and processes the + files of every connection on a schedule. +- **EBICS - Batch Payments (Odoo Enterprise)** (``account_ebics_batch_payment``): uploads + the batch payments of the Odoo Enterprise ``account_batch_payment`` module. +- **EBICS - Payment Orders (OCA)** (``account_ebics_payment_order``): uploads the payment + orders of the OCA ``account_payment_order`` module + (`OCA/bank-payment `_). + +To process the downloaded statements, install the module of each format you receive: + +- **camt.053, camt.052 and camt.054**: ``account_statement_import_camt`` + (`OCA/bank-statement-import `_). For + camt.053, the Odoo Enterprise ``account_bank_statement_import_camt`` works too. +- **French CFONB**: ``account_statement_import_fr_cfonb`` + (`OCA/l10n-france `_). + +Recommended with several financial journals: ``account_usability`` +(`OCA/account-financial-tools `_), which adds +accounting menus such as a list of all bank statements, including those downloaded by the +scheduled import. + +Getting your bank online +======================== + +The configuration on the Odoo side takes fifteen to thirty minutes. What sets the pace of a +project is the bank, and it is almost never for a technical reason: + +- **The bank opens the access.** You receive the host ID, the address of the access point, + your partner and user identifiers, and a letter carrying the hash values of the bank's keys. +- **INI and HIA.** Odoo generates your key pairs for signature, authentication and encryption, + sends the public keys to the bank and produces the initialisation letters, which you print, + sign and send. The bank compares them by hand with the keys it received online. +- **HPB.** Once the bank has activated your access, you retrieve its public keys and compare + their hash values with the letter it sent you. That comparison is what makes the channel + trustworthy. +- **The first exchange.** Statements come down first. Payments follow, as a test file where + the bank supports the test flag, otherwise as a real transfer of a small amount. + +Count in weeks per bank rather than days, and start the contract and the paperwork early. Configuration ============= -Go to **Settings > Users** +**Who may configure.** In *Settings > Users*, add the users who maintain the EBICS +configuration to the **EBICS Manager** group. -Add the users that are authorised to maintain the EBICS configuration to the 'EBICS Manager' Group. +**File formats.** In *Accounting > Configuration > EBICS > EBICS File Formats*, check that the +formats you exchange with your banks are defined; the common ones are created at +installation. A missing format can be reported on +`GitHub `_. -| +A download format can carry a **Download Process Method**, run by the *Process* button of a +downloaded file: ``camt.053``, ``camt.052``, ``camt.054``, ``cfonb120`` and ``pain.002`` (the +payment status report returned by the bank). Each needs the module of its format (see +Companion modules); Odoo tells you which one when it is missing. -Go to **Accounting > Configuration > Miscellaneous > EBICS > EBICS File Formats** +**Bank connections.** In *Accounting > Configuration > EBICS > EBICS Configuration*, create one +connection per bank contract, with the identifiers your bank sent you. -Check if the EBICS File formats that you want to process in Odoo are defined. - -Most commonly used formats for which support is available in Odoo should be there already. - -Please open an issue on https://github.com/Noviat/account_ebics to report missing EBICS File Formats. - -For File Formats of type 'Downloads' you can also specify a 'Download Process Method'. - -This is the method that will be executed when hitting the 'Process' button on the downloaded file. - -The following methods are currently available: - -- cfonb120 -- camt.053 -- camt.052 -- camt.054 - -All these methods require complimentary modules to be installed (cf. Installation section supra). - -You'll get an error message when the required module is not installed on your Odoo instance. - -| - -Go to **Accounting > Configuration > Miscellaneous > EBICS > EBICS Configuration** - -Configure your EBICS configuration according to the contract with your bank. - -| +.. image:: https://raw.githubusercontent.com/Noviat/account_ebics/19.0/account_ebics/static/description/ebics_download.png + :alt: A downloaded camt.053 statement file in Odoo, before processing + :width: 100% Usage ===== -Go to **Accounting > Bank and Cash > EBICS Processing** +The **EBICS Processing** menu of the accounting application lists the downloaded and uploaded +files, and offers manual downloads and uploads. With Odoo Enterprise it sits under +*Accounting > Accounting*. -| +Downloaded files are processed into bank statements. Uploads are launched from the payment +batch or the payment order: the file, its format and the order type come from the +configuration, not from the person clicking. + +.. image:: https://raw.githubusercontent.com/Noviat/account_ebics/19.0/account_ebics/static/description/ebics_upload.png + :alt: Uploading a pain.001 SEPA credit transfer file over EBICS 3.0, with the test mode option + :width: 100% Diagnostics =========== -Add the following to your Odoo config file in order to diagnose -issues with the EBICS connection with your bank: +To diagnose the connection with your bank, add this line to the Odoo server configuration +file:: -log_handler = fintech.ebics:DEBUG + log_handler = fintech.ebics:DEBUG -| - -EBICS Return Codes +EBICS return codes ------------------ -During the processing of your EBICS upload/download, your bank may return an Error Code, e.g. +During an upload or a download, your bank may return an error code, for example:: -EBICS Functional Error: -EBICS_NO_DOWNLOAD_DATA_AVAILABLE (code: 90005) + EBICS Functional Error: + EBICS_NO_DOWNLOAD_DATA_AVAILABLE (code: 90005) -A detailed explanation of the codes can be found on http://www.ebics.org. -You can also find this information in the doc folder of this module (file EBICS_Annex1_ReturnCodes). - -| +The codes are explained on `ebics.org `_ and in the ``doc`` folder of +this module (``EBICS_Annex1_ReturnCodes``). Electronic Distributed Signature (EDS) -------------------------------------- -This is supported via external signing apps, e.g. BankingVEU: +Where your bank supports EBICS T, Odoo prepares the file and holds no signing credentials +at all: the payment is approved in your own signing application, which is what a segregation +of duties policy usually demands. Where it does not, which happens with German and Swiss +banks, the signing key sits on your Odoo server, and you can protect it with a separate +signature passphrase that is never stored and is asked for every signed transaction. -- https://play.google.com/store/apps/details?id=subsembly.bankingveu -- https://apps.apple.com/de/app/bankingveu/id1578694190 +External signing apps include BankingVEU +(`Android `_, +`iOS `_). +Roadmap +======= -Known Issues / Roadmap -====================== +- Import externally generated keys and certificates (today only the 3SKey signature + certificate). +- Support the SWIFT 3SKey signing JavaScript library + (`SConnect `_). -- The end user is currently not able to change his passphrases (only the users with 'EBICS Manager' rights can do so). -- Add support to import externally generated keys & certificates (currently only 3SKey signature certificate). -- Add support for SWIFT 3SKey signing javascript lib (SConnect, cf https://www2.swift.com/3skey/help/sconnect.html). +Issues and pull requests are welcome on +`GitHub `_. +Credits +======= + +This module is developed and maintained by `Noviat `_, Odoo +integrator in Belgium, specialised in accounting and finance since 2009. + +We implement it, we configure the connection with your banks and we support you through the +first cycles. If you want help getting a bank online, tell us which banks you use: +https://www.noviat.com/ebics diff --git a/account_ebics/__manifest__.py b/account_ebics/__manifest__.py index 2038fb9..749a710 100644 --- a/account_ebics/__manifest__.py +++ b/account_ebics/__manifest__.py @@ -2,7 +2,9 @@ # License LGPL-3 or later (https://www.gnu.org/licenses/lgpl). { - "name": "EBICS banking protocol", + "name": "EBICS Banking Protocol", + "summary": "Download bank statements and upload payment " + "files directly from Odoo, using the European EBICS standard", "version": "19.0.1.2.0", "license": "LGPL-3", "author": "Noviat", @@ -29,5 +31,5 @@ "cryptography", ] }, - "images": ["static/description/cover.png"], + "images": ["static/description/banner.png"], } diff --git a/account_ebics/static/description/banner.png b/account_ebics/static/description/banner.png new file mode 100644 index 0000000..be293e3 Binary files /dev/null and b/account_ebics/static/description/banner.png differ diff --git a/account_ebics/static/description/cover.png b/account_ebics/static/description/cover.png deleted file mode 100644 index 41c4cec..0000000 Binary files a/account_ebics/static/description/cover.png and /dev/null differ diff --git a/account_ebics/static/description/ebics_download.png b/account_ebics/static/description/ebics_download.png new file mode 100644 index 0000000..fd3e953 Binary files /dev/null and b/account_ebics/static/description/ebics_download.png differ diff --git a/account_ebics/static/description/ebics_flow.png b/account_ebics/static/description/ebics_flow.png new file mode 100644 index 0000000..5132ec0 Binary files /dev/null and b/account_ebics/static/description/ebics_flow.png differ diff --git a/account_ebics/static/description/ebics_upload.png b/account_ebics/static/description/ebics_upload.png new file mode 100644 index 0000000..5b35920 Binary files /dev/null and b/account_ebics/static/description/ebics_upload.png differ diff --git a/account_ebics/static/description/icon.png b/account_ebics/static/description/icon.png index 889d129..a2bfe03 100644 Binary files a/account_ebics/static/description/icon.png and b/account_ebics/static/description/icon.png differ diff --git a/account_ebics/static/description/index.html b/account_ebics/static/description/index.html index c3d38ab..5e6995e 100644 --- a/account_ebics/static/description/index.html +++ b/account_ebics/static/description/index.html @@ -1,573 +1,225 @@ - - - - - -README.rst - - - -
- - -License: LGPL-3 +
-

EBICS banking protocol

-

Implementation of the EBICS banking protocol.

-

This module facilitates the exchange of files with banks via the EBICS protocol.

-
-

-
-
-

Installation

-

The module depends upon

+

EBICS Banking Protocol

+

Exchange files directly with your banks from Odoo, with no portal and nobody logging in.

+

EBICS, the Electronic Banking Internet Communication Standard, is the channel European +banks open to companies that want their software to talk to the bank. Bank statements are +downloaded on a schedule and payment files are uploaded from Odoo, authenticated by your +own cryptographic keys instead of a login page.

+

This module implements that protocol in Odoo. It is developed and maintained by +Noviat, and follows each new version of Odoo, which matters when a bank connection has to +survive your next migration.

+

If you are still working out whether EBICS is the right channel for you, we explain it +without the jargon, with screen recordings of the flow in Odoo, on +noviat.com/ebics.

+Statements come down as camt.053 or camt.052 files, payment files go up as pain.001 or pain.008, and your keys stay on your own server +
+

What you get

    -
  • https://pypi.python.org/pypi/fintech
    • -
  • https://pypi.python.org/pypi/cryptography
    • +
  • Statements that arrive on their own. A scheduled task collects the files your bank +publishes, for every account, and processes them into bank statements.
    • +
  • Payments that leave the same way. A payment batch or a payment order is uploaded to +the bank in the format the bank expects, without exporting a file and re-uploading it +somewhere else.
    • +
  • Several companies, one connection. Keys are held per bank rather than per company: +when fifteen entities bank with the same institution, the bank sends a single daily file +carrying fifteen statements and the module puts each statement in the right company.
    • +
  • No bank credentials in Odoo. The connection uses your own company keys, generated on +your side and kept on your server. Access to the EBICS configuration is a permission of +its own ('EBICS Manager'), separate from ordinary accounting rights.
    • +
  • A test mode, where your bank offers one. French banks accept a test flag, so a file +can be submitted and validated before anything is switched to production. German and +Swiss banks generally do not: there the first payment is a real one, kept small and sent +to an account you control.
    • +
  • A trace of every exchange. Each download and each upload is a record, with the file +it carried, the moment it happened and the user behind it.
-

Remark:

-

The EBICS 'Test Mode' for uploading orders requires fintech 4.3.4 or higher for EBICS 2.x -and fintech 7.2.7 or higher for EBICS 3.0.

-

SWIFT 3SKey support requires fintech 6.4 or higher.

-
-

+

EBICS 2.4, EBICS 2.5 and EBICS 3.0 are supported. EBICS 3.0, the current +specification since December 2022, names what is exchanged with BTF instead of the +country-specific order type codes of EBICS 2.x. Many banks still run 2.4 or 2.5 in parallel.

-

We also recommend to consider the installation of the following modules:

-
-

-
- -
-

-
- -
-

-
- -
-

-
-
    -

  • account_usability

    -

    Recommended if you have multiple financial journals. -This module adds a number of accounting menu entries such as bank statement list view -which allows to see all statements downloaded via the ir.cron automated EBICS download.

    -

    Cf. https://github.com/OCA/account-financial-tools

    -
    • -
-
-

-
- -
-

-
- -
-

-
- -
-

-
- -
-

-
-
-

Fintech license

-

If you have a valid fintech.ebics license, you should add the following -licensing parameters to the [options] section of the odoo server configuration file:

+ -
- -