3 |
3 | ALYF Banking is a seamless solution for connecting your bank accounts with ERPNext.
8 | 9 |This app is designed to simplify your financial management by effortlessly fetching transactions from thousands of banks and integrating them directly into your ERPNext system. Say goodbye to manual data entry and time-consuming reconciliations ✨
10 | 11 |Experience the ease of automation and gain better control over your finances with the ultimate banking integration app for ERPNext users.
12 |
24 |
25 | We use the EBICS protocol which is widely supported by banks in the following countries:
26 |
27 | - 🇦🇹 Austria
28 | - 🇫🇷 France
29 | - 🇩🇪 Germany
30 | - 🇨🇭 Switzerland
31 |
32 | ## Installation
33 |
34 | Install [via Frappe Cloud](https://frappecloud.com/marketplace/apps/banking) or on your local bench:
35 |
36 | ```bash
37 | bench get-app https://github.com/alyf-de/banking.git
38 | bench --site ${message}
93 |${bank_keys}`,
94 | async () => {
95 | await confirm_bank_keys(frm.doc.name, passphrase);
96 | frm.reload_doc();
97 | }
98 | );
99 | },
100 | frm.doc.bank_keys_activated ? __("Actions") : null
101 | );
102 | }
103 |
104 | if (frm.doc.initialized && frm.doc.bank_keys_activated) {
105 | frm.add_custom_button(__("Download Bank Statements"), () => {
106 | download_bank_statements(frm.doc.name, !frm.doc.passphrase);
107 | });
108 | }
109 | },
110 | });
111 |
112 | function ask_for_passphrase() {
113 | return new Promise((resolve) => {
114 | frappe.prompt(
115 | [
116 | {
117 | fieldname: "passphrase",
118 | label: __("Passphrase"),
119 | fieldtype: "Password",
120 | reqd: true,
121 | },
122 | ],
123 | (values) => {
124 | resolve(values.passphrase);
125 | },
126 | __("Enter Passphrase"),
127 | __("Continue")
128 | );
129 | });
130 | }
131 |
132 | async function get_bank_keys(ebics_user, passphrase) {
133 | try {
134 | return await frappe.xcall(
135 | "banking.ebics.doctype.ebics_user.ebics_user.download_bank_keys",
136 | { ebics_user: ebics_user, passphrase: passphrase }
137 | );
138 | } catch (e) {
139 | frappe.show_alert({
140 | message: e || __("An error occurred"),
141 | indicator: "red",
142 | });
143 | }
144 | }
145 |
146 | async function confirm_bank_keys(ebics_user, passphrase) {
147 | try {
148 | await frappe.xcall(
149 | "banking.ebics.doctype.ebics_user.ebics_user.confirm_bank_keys",
150 | { ebics_user: ebics_user, passphrase: passphrase }
151 | );
152 | frappe.show_alert({
153 | message: __("Bank keys confirmed"),
154 | indicator: "green",
155 | });
156 | } catch (e) {
157 | frappe.show_alert({
158 | message: e || __("An error occurred"),
159 | indicator: "red",
160 | });
161 | }
162 | }
163 |
164 | function download_bank_statements(ebics_user, needs_passphrase) {
165 | const dialog = frappe.prompt(
166 | [
167 | {
168 | fieldname: "from_date",
169 | label: __("From Date"),
170 | fieldtype: "Date",
171 | default: frappe.datetime.now_date(),
172 | onchange: () => {
173 | const from_date = dialog.get_value("from_date");
174 | const empty_disclaimer = __(
175 | "If no Bank Transactions are created, please check the Error Logs. If there are no errors, the bank likely did not provide any (new) bank statements for this period."
176 | );
177 | if (from_date == frappe.datetime.now_date()) {
178 | dialog.set_df_property(
179 | "note",
180 | "options",
181 | __(
182 | "We'll try to download new transactions from today, using camt.052."
183 | ) + `camt.053."
191 | ) + `camt.052 transactions are downloaded four times a day. Otherwise camt.053 transactions are downloaded once a day.",
128 | "fieldname": "intraday_sync",
129 | "fieldtype": "Check",
130 | "label": "Intraday Sync"
131 | },
132 | {
133 | "default": "1",
134 | "description": "If enabled, a separate Bank Transaction will be created for each sub-transaction in a batch.",
135 | "fieldname": "split_batch_transactions",
136 | "fieldtype": "Check",
137 | "label": "Split Batch Transactions"
138 | }
139 | ],
140 | "links": [
141 | {
142 | "link_doctype": "EBICS Request",
143 | "link_fieldname": "ebics_user"
144 | }
145 | ],
146 | "modified": "2025-03-12 17:59:35.346499",
147 | "modified_by": "Administrator",
148 | "module": "EBICS",
149 | "name": "EBICS User",
150 | "owner": "Administrator",
151 | "permissions": [
152 | {
153 | "create": 1,
154 | "delete": 1,
155 | "email": 1,
156 | "export": 1,
157 | "print": 1,
158 | "read": 1,
159 | "report": 1,
160 | "role": "System Manager",
161 | "share": 1,
162 | "write": 1
163 | },
164 | {
165 | "create": 1,
166 | "delete": 1,
167 | "email": 1,
168 | "export": 1,
169 | "print": 1,
170 | "read": 1,
171 | "report": 1,
172 | "role": "Accounts Manager",
173 | "share": 1,
174 | "write": 1
175 | }
176 | ],
177 | "search_fields": "full_name,bank,company",
178 | "sort_field": "modified",
179 | "sort_order": "DESC",
180 | "states": [],
181 | "title_field": "full_name"
182 | }
--------------------------------------------------------------------------------
/banking/ebics/doctype/ebics_user/ebics_user.py:
--------------------------------------------------------------------------------
1 | # Copyright (c) 2024, ALYF GmbH and contributors
2 | # For license information, please see license.txt
3 | import json
4 |
5 | import frappe
6 | from frappe import _
7 | from frappe.model.document import Document
8 | from frappe.utils import get_link_to_form
9 | from frappe.utils.data import getdate
10 | from requests import HTTPError
11 |
12 | from banking.ebics.utils import get_ebics_manager, sync_ebics_transactions
13 | from banking.klarna_kosma_integration.admin import Admin
14 |
15 |
16 | class EBICSUser(Document):
17 | def validate(self):
18 | if self.country:
19 | self.validate_country_code()
20 |
21 | if self.bank:
22 | self.validate_bank()
23 |
24 | def before_insert(self):
25 | self.register_user()
26 |
27 | def on_update(self):
28 | self.register_user()
29 |
30 | def on_trash(self):
31 | self.remove_user()
32 |
33 | def register_user(self):
34 | """Indempotent method to register the user with the admin backend."""
35 | host_id = frappe.db.get_value("Bank", self.bank, "ebics_host_id")
36 | try:
37 | r = Admin().request.register_ebics_user(host_id, self.partner_id, self.user_id)
38 | r.raise_for_status()
39 | except HTTPError as e:
40 | if e.response.status_code == 402:
41 | # User already exists for this customer
42 | return
43 | elif e.response.status_code == 403:
44 | title = _("Banking Error")
45 | msg = _("EBICS User limit exceeded.")
46 | frappe.log_error(
47 | title=_("Banking Error"),
48 | message=msg,
49 | reference_doctype="EBICS User",
50 | reference_name=self.name,
51 | )
52 | frappe.throw(title=title, msg=msg)
53 | elif e.response.status_code == 409:
54 | title = _("Banking Error")
55 | msg = _("User ID not available.")
56 | frappe.log_error(
57 | title=_("Banking Error"),
58 | message=msg,
59 | reference_doctype="EBICS User",
60 | reference_name=self.name,
61 | )
62 | frappe.throw(title=title, msg=msg)
63 |
64 | def remove_user(self):
65 | """Indempotent method to remove the user from the admin backend."""
66 | host_id = frappe.db.get_value("Bank", self.bank, "ebics_host_id")
67 | try:
68 | r = Admin().request.register_ebics_user(host_id, self.partner_id, self.user_id, remove=True)
69 | r.raise_for_status()
70 | except HTTPError:
71 | title = _("Failed to remove EBICS user registration.")
72 | frappe.log_error(
73 | title=title,
74 | reference_doctype="EBICS User",
75 | reference_name=self.name,
76 | )
77 | frappe.throw(title)
78 |
79 | def validate_country_code(self):
80 | country_code = frappe.db.get_value("Country", self.country, "code")
81 | if not country_code or len(country_code) != 2:
82 | frappe.throw(
83 | _("Please add a two-letter country code to country {0}").format(
84 | get_link_to_form("Country", self.country)
85 | )
86 | )
87 |
88 | def validate_bank(self):
89 | host_id, url = frappe.db.get_value("Bank", self.bank, ["ebics_host_id", "ebics_url"])
90 | if not host_id or not url:
91 | frappe.throw(
92 | _("Please add EBICS Host ID and URL to bank {0}").format(get_link_to_form("Bank", self.bank))
93 | )
94 |
95 | def attach_ini_letter(self, pdf_bytes: bytes):
96 | file = frappe.new_doc("File")
97 | file.file_name = f"ini_letter_{self.name}.pdf"
98 | file.attached_to_doctype = self.doctype
99 | file.attached_to_name = self.name
100 | file.is_private = 1
101 | file.content = pdf_bytes
102 | file.save()
103 |
104 | def store_keyring(self, keys: dict):
105 | self.db_set("keyring", json.dumps(keys, indent=2))
106 |
107 | def get_keyring(self) -> dict:
108 | return json.loads(self.keyring) if self.keyring else {}
109 |
110 |
111 | def on_doctype_update():
112 | frappe.db.add_unique("EBICS User", ["bank", "partner_id", "user_id"], constraint_name="unique_ebics_user")
113 |
114 |
115 | @frappe.whitelist()
116 | def initialize(ebics_user: str, passphrase: str, signature_passphrase: str, store_passphrase: int):
117 | ensure_ebics_is_enabled()
118 |
119 | user = frappe.get_doc("EBICS User", ebics_user)
120 | user.check_permission("write")
121 |
122 | if store_passphrase:
123 | user.passphrase = passphrase
124 | user.save()
125 |
126 | manager = get_ebics_manager(ebics_user=user, passphrase=passphrase, sig_passphrase=signature_passphrase)
127 |
128 | try:
129 | manager.create_user_keys()
130 | except RuntimeError as e:
131 | if e.args[0] != "keys already present":
132 | raise e
133 |
134 | if user.needs_certificates:
135 | country_code = frappe.db.get_value("Country", user.country, "code")
136 | manager.create_user_certificates(user.full_name, user.company, country_code.upper())
137 |
138 | manager.send_keys_to_bank()
139 |
140 | bank_name = frappe.db.get_value("Bank", user.bank, "bank_name")
141 | ini_bytes = manager.create_ini_letter(bank_name, language=frappe.local.lang)
142 | user.attach_ini_letter(ini_bytes)
143 | user.db_set("initialized", 1)
144 |
145 |
146 | @frappe.whitelist()
147 | def download_bank_keys(ebics_user: str, passphrase: str | None = None):
148 | ensure_ebics_is_enabled()
149 |
150 | user = frappe.get_doc("EBICS User", ebics_user)
151 | user.check_permission("write")
152 |
153 | manager = get_ebics_manager(user, passphrase=passphrase)
154 |
155 | return manager.download_bank_keys()
156 |
157 |
158 | @frappe.whitelist()
159 | def confirm_bank_keys(ebics_user: str, passphrase: str | None = None):
160 | ensure_ebics_is_enabled()
161 |
162 | user = frappe.get_doc("EBICS User", ebics_user)
163 | user.check_permission("write")
164 |
165 | manager = get_ebics_manager(user, passphrase=passphrase)
166 | manager.activate_bank_keys()
167 | user.db_set("bank_keys_activated", 1)
168 |
169 |
170 | @frappe.whitelist()
171 | def download_bank_statements(
172 | ebics_user: str,
173 | from_date: str | None = None,
174 | to_date: str | None = None,
175 | passphrase: str | None = None,
176 | ):
177 | ensure_ebics_is_enabled()
178 |
179 | frappe.has_permission("Bank Transaction", "create", throw=True)
180 |
181 | user = frappe.get_doc("EBICS User", ebics_user)
182 | user.check_permission("read")
183 |
184 | frappe.enqueue(
185 | sync_ebics_transactions,
186 | requested_by="User",
187 | ebics_user=ebics_user,
188 | start_date=from_date,
189 | end_date=to_date,
190 | passphrase=passphrase,
191 | intraday=getdate(from_date) == getdate(),
192 | now=frappe.conf.developer_mode,
193 | )
194 |
195 |
196 | def ensure_ebics_is_enabled():
197 | if not frappe.db.get_single_value("Banking Settings", "enabled"):
198 | frappe.throw(
199 | _("Please activate the checkbox 'Enabled' in the {0}.").format(
200 | get_link_to_form("Banking Settings", "Banking Settings")
201 | )
202 | )
203 |
204 | if not frappe.db.get_single_value("Banking Settings", "enable_ebics"):
205 | frappe.throw(
206 | _("Please activate the checkbox 'Enable EBICS' in the {0}.").format(
207 | get_link_to_form("Banking Settings", "Banking Settings")
208 | )
209 | )
210 |
--------------------------------------------------------------------------------
/banking/ebics/doctype/ebics_user/test_ebics_user.py:
--------------------------------------------------------------------------------
1 | # Copyright (c) 2024, ALYF GmbH and Contributors
2 | # See license.txt
3 |
4 | # import frappe
5 | from frappe.tests.utils import FrappeTestCase
6 |
7 |
8 | class TestEBICSUser(FrappeTestCase):
9 | pass
10 |
--------------------------------------------------------------------------------
/banking/ebics/manager.py:
--------------------------------------------------------------------------------
1 | from typing import TYPE_CHECKING
2 |
3 | if TYPE_CHECKING:
4 | from collections.abc import Callable
5 |
6 | from fintech.ebics import (
7 | EbicsClient,
8 | )
9 |
10 |
11 | class EBICSManager:
12 | __slots__ = ["bank", "keyring", "user"]
13 |
14 | def set_keyring(self, keys: dict, save_to_db: "Callable", sig_passphrase: str, passphrase: str | None):
15 | from fintech.ebics import EbicsKeyRing
16 |
17 | class CustomKeyRing(EbicsKeyRing):
18 | def _write(self, keydict):
19 | save_to_db(keydict)
20 |
21 | self.keyring = CustomKeyRing(
22 | keys=keys,
23 | passphrase=passphrase,
24 | sig_passphrase=sig_passphrase,
25 | )
26 |
27 | def set_user(self, partner_id: str, user_id: str):
28 | from fintech.ebics import EbicsUser
29 |
30 | self.user = EbicsUser(keyring=self.keyring, partnerid=partner_id, userid=user_id, transport_only=True)
31 |
32 | def set_bank(self, host_id: str, url: str):
33 | from fintech.ebics import EbicsBank
34 |
35 | self.bank = EbicsBank(keyring=self.keyring, hostid=host_id, url=url)
36 |
37 | def create_user_keys(self):
38 | self.user.create_keys(keyversion="A005", bitlength=2048)
39 |
40 | def create_user_certificates(self, user_name: str, organization_name: str, country_code: str):
41 | self.user.create_certificates(
42 | commonName=user_name,
43 | organizationName=organization_name,
44 | countryName=country_code,
45 | )
46 |
47 | def get_client(self) -> "EbicsClient":
48 | from fintech.ebics import EbicsClient
49 |
50 | return EbicsClient(self.bank, self.user)
51 |
52 | def send_keys_to_bank(self):
53 | client = self.get_client()
54 | # Send the public electronic signature key to the bank.
55 | client.INI()
56 | # Send the public authentication and encryption keys to the bank.
57 | client.HIA()
58 |
59 | def create_ini_letter(self, bank_name: str, language: str | None = None) -> bytes:
60 | """Return the PDF data as byte string."""
61 | return self.user.create_ini_letter(
62 | bankname=bank_name,
63 | lang=language,
64 | )
65 |
66 | def download_bank_keys(self):
67 | client = self.get_client()
68 | return client.HPB()
69 |
70 | def activate_bank_keys(self) -> None:
71 | self.bank.activate_keys()
72 |
73 | def get_permitted_order_types(self, level: str = "T") -> list[str]:
74 | """Return a list of individual order types for the given (or unspecified) authorisation level."""
75 | client = self.get_client()
76 | user_data = client.HTD(parsed=True)
77 | permissions = user_data.get("HTDResponseOrderData", {}).get("UserInfo", {}).get("Permission", [])
78 |
79 | # Collect all order types for the specified level
80 | level_perms = []
81 | for permission in permissions:
82 | if permission.get("@AuthorisationLevel", level) == level:
83 | order_types = permission.get("OrderTypes")
84 | if isinstance(order_types, str):
85 | # Split if it's a space-separated string
86 | level_perms.extend(order_types.split())
87 |
88 | return level_perms
89 |
--------------------------------------------------------------------------------
/banking/ebics/utils.py:
--------------------------------------------------------------------------------
1 | import contextlib
2 | import hashlib
3 | import json
4 | from typing import TYPE_CHECKING, Literal
5 |
6 | import fintech
7 | import frappe
8 | from frappe import _
9 | from frappe.utils.data import get_link_to_form
10 |
11 | from banking.ebics.manager import EBICSManager
12 |
13 | if TYPE_CHECKING:
14 | from datetime import date
15 |
16 | from fintech.sepa import SEPATransaction
17 |
18 | from banking.ebics.doctype.ebics_user.ebics_user import EBICSUser
19 |
20 |
21 | def get_ebics_manager(
22 | ebics_user: "EBICSUser",
23 | passphrase: str | None = None,
24 | sig_passphrase: str | None = None,
25 | ) -> "EBICSManager":
26 | """Get an EBICSManager instance for the given EBICS User.
27 |
28 | :param ebics_user: The EBICS User record.
29 | :param passphrase: The secret passphrase for uploads to the bank.
30 | """
31 | register_fintech(needs_license_key=True)
32 |
33 | manager = EBICSManager()
34 | manager.set_keyring(
35 | keys=ebics_user.get_keyring(),
36 | save_to_db=ebics_user.store_keyring,
37 | sig_passphrase=sig_passphrase,
38 | passphrase=passphrase or ebics_user.get_password("passphrase"),
39 | )
40 |
41 | manager.set_user(ebics_user.partner_id, ebics_user.user_id)
42 |
43 | host_id, url = frappe.db.get_value("Bank", ebics_user.bank, ["ebics_host_id", "ebics_url"])
44 | manager.set_bank(host_id, url)
45 |
46 | return manager
47 |
48 |
49 | def sync_ebics_transactions(
50 | ebics_user: str,
51 | requested_by: Literal["User", "System"],
52 | start_date: str | None = None,
53 | end_date: str | None = None,
54 | passphrase: str | None = None,
55 | intraday: bool = False,
56 | ):
57 | user = frappe.get_doc("EBICS User", ebics_user)
58 | manager = get_ebics_manager(ebics_user=user, passphrase=passphrase)
59 |
60 | from fintech.sepa import (
61 | CAMTDocument,
62 | ) # import possible only after manager is initialized
63 |
64 | permitted_types = manager.get_permitted_order_types()
65 | validate_permitted_types(user, permitted_types, intraday)
66 |
67 | with_c54 = user.split_batch_transactions and "C54" in permitted_types
68 | request = log_request(
69 | ebics_user,
70 | "C52" if intraday else "C53",
71 | requested_by,
72 | {
73 | "start_date": start_date,
74 | "end_date": end_date,
75 | },
76 | )
77 |
78 | try:
79 | client = manager.get_client()
80 | main_xml = client.C52(start_date, end_date) if intraday else client.C53(start_date, end_date)
81 | batch_xml = client.C54(start_date, end_date) if with_c54 else None
82 | request.db_set(
83 | {
84 | "status": "Successful",
85 | "response": json.dumps(
86 | {file_name: file.decode() for file_name, file in main_xml.items()},
87 | indent=2,
88 | ),
89 | }
90 | )
91 | except fintech.ebics.EbicsNoDataAvailable:
92 | request.db_set({"status": "Successful", "response": "No Data Available"})
93 | return
94 | except Exception as e:
95 | request.db_set({"status": "Failed", "response": str(e)})
96 | frappe.log_error(
97 | title=_("Banking Error"),
98 | reference_doctype="EBICS User",
99 | reference_name=ebics_user,
100 | )
101 | return
102 |
103 | # Keep the request log, no matter what happens next.
104 | frappe.db.commit()
105 |
106 | # We want to process either all documents or none. If we fail to process one, we
107 | # want to rollback the entire transaction and report an error.
108 | try:
109 | for name in sorted(main_xml):
110 | camt_document = CAMTDocument(xml=main_xml[name], camt54=batch_xml)
111 | bank_account = get_bank_account(camt_document.iban, user.bank, user.company)
112 | if not bank_account:
113 | frappe.log_error(
114 | title=_("Banking Error"),
115 | message=_("Bank Account not found for IBAN {0}").format(camt_document.iban),
116 | reference_doctype="EBICS User",
117 | reference_name=user.name,
118 | )
119 | continue
120 |
121 | process_camt_document(
122 | camt_document,
123 | bank_account,
124 | user.company,
125 | user.start_date,
126 | user.split_batch_transactions,
127 | )
128 | except Exception:
129 | frappe.db.rollback()
130 | frappe.log_error(
131 | title=_("Banking Error"),
132 | reference_doctype="EBICS Request",
133 | reference_name=request.name,
134 | )
135 | client.confirm_download(success=False)
136 | return
137 |
138 | client.confirm_download(success=True)
139 |
140 |
141 | def validate_permitted_types(user, permitted_types, intraday: bool):
142 | # Not sure yet, how reliable permitted types are. For now, we just log an error
143 | # instead of raising an exception or returning.
144 | if intraday and "C52" not in permitted_types:
145 | frappe.log_error(
146 | title=_("Banking Error"),
147 | message=_(
148 | "It seems like EBICS User {0} lacks permission 'C52' for downloading intraday transactions. The permitted types are: {1}."
149 | ).format(user.name, ", ".join(permitted_types)),
150 | reference_doctype="EBICS User",
151 | reference_name=user.name,
152 | )
153 |
154 | if not intraday and "C53" not in permitted_types:
155 | frappe.log_error(
156 | title=_("Banking Error"),
157 | message=_(
158 | "It seems like EBICS User {0} lacks permission 'C52' for downloading booked bank statements. The permitted types are: {1}."
159 | ).format(user.name, ", ".join(permitted_types)),
160 | reference_doctype="EBICS User",
161 | reference_name=user.name,
162 | )
163 |
164 | if not intraday and user.split_batch_transactions and "C54" not in permitted_types:
165 | frappe.log_error(
166 | title=_("Banking Error"),
167 | message=_(
168 | "EBICS User {0} lacks permission 'C54' for splitting batch transactions. The permitted types are: {1}."
169 | ).format(user.name, ", ".join(permitted_types)),
170 | reference_doctype="EBICS User",
171 | reference_name=user.name,
172 | )
173 |
174 |
175 | def get_bank_account(iban: str, bank: str, company: str) -> str | None:
176 | return frappe.db.get_value(
177 | "Bank Account",
178 | {
179 | "iban": iban,
180 | "disabled": 0,
181 | "bank": bank,
182 | "is_company_account": 1,
183 | "company": company,
184 | },
185 | )
186 |
187 |
188 | def process_camt_document(
189 | camt_document,
190 | bank_account: str,
191 | company: "str | None" = None,
192 | earliest_date: "date | None" = None,
193 | split_batch_transactions: bool = False,
194 | ):
195 | if not company:
196 | company = frappe.db.get_value("Bank Account", bank_account, "company")
197 |
198 | for transaction in camt_document:
199 | if transaction.status and transaction.status != "BOOK":
200 | # Skip PDNG and INFO transactions
201 | continue
202 |
203 | if (
204 | transaction.batch
205 | and (split_batch_transactions or len(transaction) == 1)
206 | and len(transaction) >= 1
207 | ):
208 | # Split batch transactions into sub-transactions, based on info
209 | # from camt.054 that is sometimes available.
210 | # If that's not possible, create a single transaction
211 | for sub_transaction in transaction:
212 | _create_bank_transaction(
213 | bank_account,
214 | company,
215 | sub_transaction,
216 | earliest_date,
217 | )
218 | else:
219 | _create_bank_transaction(
220 | bank_account,
221 | company,
222 | transaction,
223 | earliest_date,
224 | )
225 |
226 |
227 | def _create_bank_transaction(
228 | bank_account: str,
229 | company: str,
230 | sepa_transaction: "SEPATransaction",
231 | start_date: "date | None" = None,
232 | ):
233 | """Create an ERPNext Bank Transaction from a given fintech.sepa.SEPATransaction.
234 |
235 | https://www.joonis.de/en/fintech/doc/sepa/#fintech.sepa.SEPATransaction
236 | """
237 | # sepa_transaction.bank_reference can be None, but we can still find an ID in the XML
238 | # For our test bank, the latter is a timestamp with nanosecond accuracy.
239 | transaction_id = (
240 | sepa_transaction.bank_reference
241 | or sepa_transaction._xmlobj.Refs.TxId.text
242 | or get_transaction_hash(sepa_transaction)
243 | )
244 |
245 | # NOTE: This does not work for old data, this ID is different from Kosma's
246 | if transaction_id and frappe.db.exists(
247 | "Bank Transaction",
248 | {"transaction_id": transaction_id, "bank_account": bank_account},
249 | ):
250 | return
251 |
252 | if start_date and sepa_transaction.date < start_date:
253 | return
254 |
255 | bt = frappe.new_doc("Bank Transaction")
256 | bt.date = sepa_transaction.date
257 | bt.bank_account = bank_account
258 | bt.company = company
259 |
260 | amount = float(sepa_transaction.amount.value)
261 | bt.deposit = max(amount, 0)
262 | bt.withdrawal = abs(min(amount, 0))
263 | bt.currency = sepa_transaction.amount.currency
264 |
265 | bt.description = "\n".join(sepa_transaction.purpose) or sepa_transaction.info
266 | bt.reference_number = sepa_transaction.eref
267 | bt.transaction_id = transaction_id
268 | bt.bank_party_iban = sepa_transaction.iban
269 | bt.bank_party_name = sepa_transaction.name
270 |
271 | with contextlib.suppress(frappe.exceptions.UniqueValidationError):
272 | bt.insert()
273 | bt.submit()
274 |
275 |
276 | def get_transaction_hash(transaction: "SEPATransaction"):
277 | sha = hashlib.sha256()
278 | for value in (
279 | transaction.date,
280 | transaction.iban,
281 | transaction.name,
282 | transaction.eref,
283 | transaction.amount.value,
284 | transaction.amount.currency,
285 | transaction.info,
286 | *transaction.purpose,
287 | ):
288 | if value:
289 | sha.update(frappe.safe_encode(str(value)))
290 |
291 | return sha.hexdigest()
292 |
293 |
294 | def log_request(
295 | ebics_user: str,
296 | order_type: str,
297 | requested_by: Literal["User", "System"],
298 | parameters: dict,
299 | ):
300 | request = frappe.new_doc("EBICS Request")
301 | request.ebics_user = ebics_user
302 | request.order_type = order_type
303 | request.requested_by = requested_by
304 | request.parameters = json.dumps(parameters, indent=2)
305 | return request.save(ignore_permissions=True)
306 |
307 |
308 | def get_protocol_versions(ebics_host_id: str, ebics_url: str):
309 | """Return a list of protocol versions supported by the bank."""
310 | register_fintech()
311 |
312 | from fintech.ebics import EbicsBank, EbicsKeyRing
313 |
314 | keyring = EbicsKeyRing({})
315 | bank = EbicsBank(keyring, ebics_host_id, ebics_url)
316 |
317 | return bank.get_protocol_versions()
318 |
319 |
320 | @frappe.whitelist()
321 | def upload_camt_file():
322 | frappe.has_permission("Bank Transaction", "create", throw=True)
323 |
324 | file_bytes = frappe.local.uploaded_file
325 | bank_account = frappe.form_dict.docname
326 |
327 | register_fintech()
328 |
329 | from fintech.sepa import CAMTDocument
330 |
331 | camt_document = CAMTDocument(file_bytes.decode())
332 | process_camt_document(camt_document, bank_account)
333 |
334 |
335 | def register_fintech(needs_license_key: bool = False):
336 | banking_settings = frappe.get_single("Banking Settings")
337 |
338 | licensee_name = banking_settings.fintech_licensee_name or None
339 | license_key = None
340 | with contextlib.suppress(frappe.AuthenticationError, frappe.ValidationError):
341 | license_key = banking_settings.get_password("fintech_license_key")
342 |
343 | if needs_license_key and not license_key:
344 | frappe.throw(
345 | _(
346 | "License key not found. Please activate the checkbox 'Enable EBICS' in the {0} and ensure that your subscription is active."
347 | ).format(get_link_to_form("Banking Settings", "Banking Settings"))
348 | )
349 |
350 | try:
351 | fintech.register(
352 | name=licensee_name,
353 | keycode=license_key,
354 | )
355 | except RuntimeError as e:
356 | if e.args[0] != "'register' can be called only once":
357 | raise e
358 |
--------------------------------------------------------------------------------
/banking/hooks.py:
--------------------------------------------------------------------------------
1 | app_name = "banking"
2 | app_title = "ALYF Banking"
3 | app_publisher = "ALYF GmbH"
4 | app_description = "Banking Integration by ALYF GmbH"
5 | app_email = "hallo@alyf.de"
6 | app_license = "GPLv3"
7 | notification_email_logo = "/assets/banking/images/alyf-logo.png"
8 |
9 | # Includes in
10 | # ------------------
11 |
12 | # include js, css files in header of desk.html
13 | app_include_css = "bank_reconciliation_beta.bundle.css"
14 | # app_include_js = "/assets/banking/js/banking.js"
15 |
16 | # include js, css files in header of web template
17 | # web_include_css = "/assets/banking/css/banking.css"
18 | # web_include_js = "/assets/banking/js/banking.js"
19 |
20 | # include custom scss in every website theme (without file extension ".scss")
21 | # website_theme_scss = "banking/public/scss/website"
22 |
23 | # include js, css files in header of web form
24 | # webform_include_js = {"doctype": "public/js/doctype.js"}
25 | # webform_include_css = {"doctype": "public/css/doctype.css"}
26 |
27 | # include js in page
28 | # page_js = {"page" : "public/js/file.js"}
29 |
30 | # include js in doctype views
31 | doctype_js = {"Bank": "custom/bank.js"}
32 | # doctype_list_js = {"doctype" : "public/js/doctype_list.js"}
33 | # doctype_tree_js = {"doctype" : "public/js/doctype_tree.js"}
34 | # doctype_calendar_js = {"doctype" : "public/js/doctype_calendar.js"}
35 |
36 | # Home Pages
37 | # ----------
38 |
39 | # application home page (will override Website Settings)
40 | # home_page = "login"
41 |
42 | # website user home page (by Role)
43 | # role_home_page = {
44 | # "Role": "home_page"
45 | # }
46 |
47 | # Generators
48 | # ----------
49 |
50 | # automatically create page for each record of this doctype
51 | # website_generators = ["Web Page"]
52 |
53 | # Jinja
54 | # ----------
55 |
56 | # add methods and filters to jinja environment
57 | # jinja = {
58 | # "methods": "banking.utils.jinja_methods",
59 | # "filters": "banking.utils.jinja_filters"
60 | # }
61 |
62 | # Installation
63 | # ------------
64 |
65 | # before_install = "banking.install.before_install"
66 | after_install = "banking.install.after_install"
67 |
68 | # Uninstallation
69 | # ------------
70 |
71 | # before_uninstall = "banking.uninstall.before_uninstall"
72 | # after_uninstall = "banking.uninstall.after_uninstall"
73 |
74 | # Desk Notifications
75 | # ------------------
76 | # See frappe.core.notifications.get_notification_config
77 |
78 | # notification_config = "banking.notifications.get_notification_config"
79 |
80 | # Permissions
81 | # -----------
82 | # Permissions evaluated in scripted ways
83 |
84 | # permission_query_conditions = {
85 | # "Event": "frappe.desk.doctype.event.event.get_permission_query_conditions",
86 | # }
87 | #
88 | # has_permission = {
89 | # "Event": "frappe.desk.doctype.event.event.has_permission",
90 | # }
91 |
92 | # DocType Class
93 | # ---------------
94 | # Override standard doctype classes
95 |
96 | override_doctype_class = {"Bank Transaction": "banking.overrides.bank_transaction.CustomBankTransaction"}
97 |
98 | # Document Events
99 | # ---------------
100 | # Hook on document methods and events
101 |
102 | doc_events = {
103 | "Bank Transaction": {
104 | "on_update_after_submit": "banking.overrides.bank_transaction.on_update_after_submit",
105 | }
106 | }
107 |
108 | # Scheduled Tasks
109 | # ---------------
110 |
111 | scheduler_events = {
112 | "cron": {
113 | "7 7-18 * * 1-5": [
114 | # At minute 7 past every hour from 7 through 18
115 | # on every day-of-week from Monday through Friday.
116 | "banking.klarna_kosma_integration.doctype.banking_settings.banking_settings.intraday_sync_ebics",
117 | ],
118 | "42 4 * * *": [
119 | # Daily at 4:42 am
120 | "banking.klarna_kosma_integration.doctype.banking_settings.banking_settings.sync_all_accounts_and_transactions",
121 | ],
122 | },
123 | }
124 |
125 | # Testing
126 | # -------
127 |
128 | before_tests = "banking.utils.before_tests"
129 |
130 | # Overriding Methods
131 | # ------------------------------
132 | #
133 | # override_whitelisted_methods = {
134 | # "frappe.desk.doctype.event.event.get_events": "banking.event.get_events"
135 | # }
136 | #
137 | # each overriding function accepts a `data` argument;
138 | # generated from the base implementation of the doctype dashboard,
139 | # along with any modifications made in other Frappe apps
140 | # override_doctype_dashboards = {
141 | # "Task": "banking.task.get_dashboard_data"
142 | # }
143 |
144 | # exempt linked doctypes from being automatically cancelled
145 | #
146 | # auto_cancel_exempted_doctypes = ["Auto Repeat"]
147 |
148 |
149 | # User Data Protection
150 | # --------------------
151 |
152 | # user_data_fields = [
153 | # {
154 | # "doctype": "{doctype_1}",
155 | # "filter_by": "{filter_by}",
156 | # "redact_fields": ["{field_1}", "{field_2}"],
157 | # "partial": 1,
158 | # },
159 | # {
160 | # "doctype": "{doctype_2}",
161 | # "filter_by": "{filter_by}",
162 | # "partial": 1,
163 | # },
164 | # {
165 | # "doctype": "{doctype_3}",
166 | # "strict": False,
167 | # },
168 | # {
169 | # "doctype": "{doctype_4}"
170 | # }
171 | # ]
172 |
173 | # Authentication and authorization
174 | # --------------------------------
175 |
176 | # auth_hooks = [
177 | # "banking.auth.validate"
178 | # ]
179 |
180 | alyf_banking_custom_fields = {
181 | "Bank": [
182 | dict(
183 | fieldname="ebics_section",
184 | label="EBICS",
185 | fieldtype="Section Break",
186 | insert_after="plaid_access_token",
187 | ),
188 | dict(
189 | fieldname="ebics_host_id",
190 | label="EBICS Host ID",
191 | fieldtype="Data",
192 | insert_after="ebics_section",
193 | translatable=0,
194 | ),
195 | dict(
196 | fieldname="ebics_url",
197 | label="EBICS URL",
198 | fieldtype="Data",
199 | options="URL",
200 | insert_after="ebics_host_id",
201 | translatable=0,
202 | ),
203 | ],
204 | }
205 |
206 | alyf_banking_property_setters = {
207 | "Bank Account": [
208 | dict(
209 | fieldname="last_integration_date",
210 | property="read_only",
211 | value=1,
212 | property_type="Check",
213 | ),
214 | dict(
215 | fieldname="last_integration_date",
216 | property="description",
217 | value="",
218 | property_type="Small Text",
219 | ),
220 | ]
221 | }
222 |
223 | get_matching_queries = "banking.klarna_kosma_integration.doctype.bank_reconciliation_tool_beta.bank_reconciliation_tool_beta.get_matching_queries"
224 |
--------------------------------------------------------------------------------
/banking/install.py:
--------------------------------------------------------------------------------
1 | import click
2 | import frappe
3 | from frappe.custom.doctype.custom_field.custom_field import create_custom_fields
4 | from frappe.custom.doctype.property_setter.property_setter import make_property_setter
5 |
6 |
7 | def after_install():
8 | click.echo("Installing Banking Customizations ...")
9 |
10 | create_custom_fields(frappe.get_hooks("alyf_banking_custom_fields"))
11 | make_property_setters()
12 |
13 |
14 | def make_property_setters():
15 | for doctypes, property_setters in frappe.get_hooks("alyf_banking_property_setters", {}).items():
16 | if isinstance(doctypes, str):
17 | doctypes = (doctypes,)
18 |
19 | for doctype in doctypes:
20 | for property_setter in property_setters:
21 | make_property_setter(
22 | doctype,
23 | **property_setter,
24 | validate_fields_for_doctype=False,
25 | for_doctype=not property_setter.get("fieldname"),
26 | )
27 |
--------------------------------------------------------------------------------
/banking/klarna_kosma_integration/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alyf-de/banking/eb6e65b82b41c65dfd1994df1d2df664a10c6ffb/banking/klarna_kosma_integration/__init__.py
--------------------------------------------------------------------------------
/banking/klarna_kosma_integration/admin.py:
--------------------------------------------------------------------------------
1 | # Copyright (c) 2023, ALYF GmbH and contributors
2 | # For license information, please see license.txt
3 | import frappe
4 |
5 | from banking.connectors.admin_request import AdminRequest
6 | from banking.klarna_kosma_integration.exception_handler import ExceptionHandler
7 |
8 |
9 | class Admin:
10 | """A class that directly communicates with the Banking Admin App."""
11 |
12 | def __init__(self, settings=None) -> None:
13 | """Initialize the Admin class with the necessary settings.
14 |
15 | :param settings: Banking Settings document.
16 | Enables you to pass the most recent settings that may not be in the database yet.
17 | """
18 | settings = settings or frappe.get_single("Banking Settings")
19 | self.api_token = settings.get_password("api_token")
20 | self.customer_id = settings.customer_id
21 | self.url = settings.admin_endpoint
22 |
23 | @property
24 | def request(self):
25 | return AdminRequest(
26 | api_token=self.api_token,
27 | url=self.url,
28 | customer_id=self.customer_id,
29 | )
30 |
31 | def fetch_subscription(self):
32 | try:
33 | subscription = self.request.fetch_subscription()
34 | subscription.raise_for_status()
35 | return subscription.json().get("message", {})
36 | except Exception as exc:
37 | ExceptionHandler(exc)
38 |
39 | def get_customer_portal_url(self):
40 | try:
41 | url = self.request.get_customer_portal()
42 | url.raise_for_status()
43 | return url.json().get("message")
44 | except Exception as exc:
45 | ExceptionHandler(exc)
46 |
--------------------------------------------------------------------------------
/banking/klarna_kosma_integration/doctype/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alyf-de/banking/eb6e65b82b41c65dfd1994df1d2df664a10c6ffb/banking/klarna_kosma_integration/doctype/__init__.py
--------------------------------------------------------------------------------
/banking/klarna_kosma_integration/doctype/bank_reconciliation_tool_beta/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alyf-de/banking/eb6e65b82b41c65dfd1994df1d2df664a10c6ffb/banking/klarna_kosma_integration/doctype/bank_reconciliation_tool_beta/__init__.py
--------------------------------------------------------------------------------
/banking/klarna_kosma_integration/doctype/bank_reconciliation_tool_beta/bank_reconciliation_tool_beta.js:
--------------------------------------------------------------------------------
1 | // Copyright (c) 2023, ALYF GmbH and contributors
2 | // For license information, please see license.txt
3 |
4 | frappe.ui.form.on("Bank Reconciliation Tool Beta", {
5 | setup: function (frm) {
6 | frm.set_query("bank_account", function (doc) {
7 | return {
8 | filters: {
9 | company: doc.company,
10 | is_company_account: 1,
11 | },
12 | };
13 | });
14 | },
15 |
16 | onload: function (frm) {
17 | if (!frm.doc.bank_statement_from_date && !frm.doc.bank_statement_to_date) {
18 | // Set default filter dates
19 | let today = frappe.datetime.get_today();
20 | frm.doc.bank_statement_from_date = frappe.datetime.add_months(today, -1);
21 | frm.doc.bank_statement_to_date = today;
22 | }
23 |
24 | if (!frm.doc.company) {
25 | // set default company
26 | frm.doc.company = frappe.user_defaults.company;
27 | }
28 | },
29 |
30 | filter_by_reference_date: function (frm) {
31 | if (frm.doc.filter_by_reference_date) {
32 | frm.set_value("bank_statement_from_date", "");
33 | frm.set_value("bank_statement_to_date", "");
34 | } else {
35 | frm.set_value("from_reference_date", "");
36 | frm.set_value("to_reference_date", "");
37 | }
38 | },
39 |
40 | refresh: function (frm) {
41 | frm.disable_save();
42 | frm.fields_dict["filters_section"].collapse(false);
43 |
44 | frm.page.add_action_icon("refresh", () => {
45 | frm.events.get_bank_transactions(frm);
46 | });
47 | frm.change_custom_button_type(__("Get Bank Transactions"), null, "primary");
48 |
49 | frm.page.add_menu_item(__("Auto Reconcile"), function () {
50 | frappe.confirm(
51 | __(
52 | "Auto reconcile bank transactions based on matching reference numbers?"
53 | ),
54 | () => {
55 | frappe.call({
56 | method:
57 | "banking.klarna_kosma_integration.doctype.bank_reconciliation_tool_beta.bank_reconciliation_tool_beta.auto_reconcile_vouchers",
58 | args: {
59 | bank_account: frm.doc.bank_account,
60 | from_date: frm.doc.bank_statement_from_date,
61 | to_date: frm.doc.bank_statement_to_date,
62 | filter_by_reference_date: frm.doc.filter_by_reference_date,
63 | from_reference_date: frm.doc.from_reference_date,
64 | to_reference_date: frm.doc.to_reference_date,
65 | },
66 | freeze: true,
67 | freeze_message: __("Auto Reconciling ..."),
68 | callback: (r) => {
69 | if (!r.exc) {
70 | frm.refresh();
71 | }
72 | },
73 | });
74 | }
75 | );
76 | });
77 |
78 | frm.page.add_menu_item(__("Upload CSV / Excel file"), () =>
79 | frm.events.route_to_bank_statement_import(frm)
80 | );
81 |
82 | frm.page.add_menu_item(__("Upload CAMT file"), () =>
83 | show_camt_uploader(frm)
84 | );
85 |
86 | frm.$reconciliation_area = frm.get_field(
87 | "reconciliation_action_area"
88 | ).$wrapper;
89 | frm.events.setup_empty_state(frm);
90 |
91 | frm.events.build_reconciliation_area(frm);
92 | },
93 |
94 | get_bank_transactions: function (frm) {
95 | if (!frm.doc.bank_account) {
96 | frappe.throw({
97 | message: __("Please set the 'Bank Account' filter"),
98 | title: __("Filter Required"),
99 | });
100 | }
101 |
102 | frm.events.build_reconciliation_area(frm);
103 | },
104 |
105 | route_to_bank_statement_import(frm) {
106 | frappe.open_in_new_tab = true;
107 |
108 | if (!frm.doc.bank_account || !frm.doc.company) {
109 | frappe.new_doc("Bank Statement Import");
110 | return;
111 | }
112 |
113 | // Route to saved Import Record in new tab
114 | frappe.call({
115 | method:
116 | "banking.klarna_kosma_integration.doctype.bank_reconciliation_tool_beta.bank_reconciliation_tool_beta.upload_bank_statement",
117 | args: {
118 | dt: frm.doc.doctype,
119 | dn: frm.doc.name,
120 | company: frm.doc.company,
121 | bank_account: frm.doc.bank_account,
122 | },
123 | callback: function (r) {
124 | if (!r.exc) {
125 | var doc = frappe.model.sync(r.message);
126 | frappe.open_in_new_tab = true;
127 | frappe.set_route("Form", doc[0].doctype, doc[0].name);
128 | }
129 | },
130 | });
131 | },
132 |
133 | bank_account: function (frm) {
134 | if (frm.doc.bank_account) {
135 | frappe.db.get_value(
136 | "Bank Account",
137 | frm.doc.bank_account,
138 | "account",
139 | (r) => {
140 | frappe.db.get_value("Account", r.account, "account_currency", (r) => {
141 | frm.doc.account_currency = r.account_currency;
142 | frm.trigger("get_account_opening_balance");
143 | frm.trigger("get_account_closing_balance");
144 | frm.trigger("render_summary");
145 | });
146 | }
147 | );
148 |
149 | frm.events.get_bank_transactions(frm);
150 | } else {
151 | frm.events.setup_empty_state(frm);
152 | }
153 | },
154 |
155 | bank_statement_from_date: function (frm) {
156 | frm.trigger("get_account_opening_balance");
157 | frm.trigger("get_bank_transactions");
158 | },
159 |
160 | bank_statement_to_date: function (frm) {
161 | frm.trigger("get_account_closing_balance");
162 | frm.trigger("render_summary");
163 | frm.trigger("get_bank_transactions");
164 | },
165 |
166 | bank_statement_closing_balance: function (frm) {
167 | frm.trigger("render_summary");
168 | },
169 |
170 | get_account_opening_balance(frm) {
171 | if (frm.doc.bank_account && frm.doc.bank_statement_from_date) {
172 | frappe.call({
173 | method:
174 | "erpnext.accounts.doctype.bank_reconciliation_tool.bank_reconciliation_tool.get_account_balance",
175 | args: {
176 | bank_account: frm.doc.bank_account,
177 | till_date: frm.doc.bank_statement_from_date,
178 | company: frm.doc.company,
179 | },
180 | callback: (response) => {
181 | frm.set_value("account_opening_balance", response.message);
182 | },
183 | });
184 | }
185 | },
186 |
187 | get_account_closing_balance(frm) {
188 | if (frm.doc.bank_account && frm.doc.bank_statement_to_date) {
189 | return frappe.call({
190 | method:
191 | "erpnext.accounts.doctype.bank_reconciliation_tool.bank_reconciliation_tool.get_account_balance",
192 | args: {
193 | bank_account: frm.doc.bank_account,
194 | till_date: frm.doc.bank_statement_to_date,
195 | company: frm.doc.company,
196 | },
197 | callback: (response) => {
198 | frm.cleared_balance = response.message;
199 | },
200 | });
201 | }
202 | },
203 |
204 | setup_empty_state: function (frm) {
205 | frm.$reconciliation_area.empty();
206 | frm.$reconciliation_area.append(`
207 | 209 | ${__("Please select a Bank Account to start reconciling.")} 210 |
211 |63 | ${__("Subscription Details")} 64 |
65 |66 | ${__("Subscriber")}: 67 | ${subscription.full_name} 68 |
69 |70 | ${__("Status")}: 71 | ${subscription.subscription_status} 72 |
73 |74 | ${__("Ebics Users")}: 75 | ${subscription.ebics_usage.used} (${__("Usage")}) / ${ 76 | subscription.ebics_usage.allowed 77 | } (${__("Limit")}) 78 |
79 |80 | ${__("Valid Till")}: 81 | ${frappe.format(subscription.plan_end_date, { fieldtype: "Date" })} 82 |
83 |84 | ${__("Last Renewed On")}: 85 | ${frappe.format(subscription.last_paid_on, { fieldtype: "Date" })} 86 |
87 |88 | 93 | ${__("Open Billing Portal")} 94 | ${frappe.utils.icon("link-url", "sm")} 95 | 96 |
97 |
82 | ${__("No Transactions found for the current filters.")}
83 |