XL184 – Parser pliku wyciągu bankowego

Praca z parserem wyciągu bankowego

Wyciągi bankowe są przekazywane przez instytucje finansowe zazwyczaj w formie plików tekstowych (np. format MT940) lub w postaci ustrukturyzowanej (standard XML).

System Comarch ERP XL natywnie obsługuje format SWIFT MT940, co pozwala odczytać i zaimportować większość standardowych plików tekstowych. Ze względu na uniwersalny charakter tego mechanizmu nie zawsze zapewnia on jednak pełną zgodność ze specyficznymi formatami danych lub niestandardowym kodowaniem znaków. Z kolei formaty ustrukturyzowane (np. CAMT.053) były dotychczas dostępne wyłącznie przez kanał Webservice, zgodnie ze specyfikacją danego banku. Oba te ograniczenia znosi parser opisany w niniejszym dokumencie.

Rozwiązanie opiera się na przeniesieniu odczytu i interpretacji wyciągów z rdzenia systemu do zewnętrznego modułu wykonawczego, co zapewnia użytkownikowi pełną kontrolę nad przetwarzaniem danych.

Kluczowe cechy rozwiązania:

Definicja ustrukturyzowanego formatu wymiany

Budowa formatu z wykorzystaniem parsera

Konfiguracja parsera polega na wskazaniu systemowi, jak ma współpracować z zewnętrznym programem przetwarzającym wyciągi: którego programu użyć, jakie pliki mu przekazywać i w jaki sposób go uruchamiać. Dzięki takiemu podejściu obsługę nietypowego formatu wyciągu można dodać bez modyfikowania samego systemu Comarch ERP XL. Wszystkie te ustawienia definiuje się w module Administrator, w obszarze zarządzania formatami przelewów i wyciągów.

Aby skonfigurować nowy format wymiany, należy:

Podobnie jak w pozostałych definiowalnych formatach przelewów, w oknie formatu można wskazać domyślne rozszerzenie plików. Parametr ten określa, jakiego typu pliki system będzie automatycznie pobierał i przekazywał do parsera (np. .txt lub .xml).

Najważniejszym ustawieniem jest komenda wywołania — polecenie, które system Comarch ERP XL uruchamia w powłoce systemowej Windows w chwili rozpoczęcia odczytu wyciągu. To ona uruchamia zewnętrzny program parsera i inicjuje przetwarzanie danych.

Poprawnie zbudowana komenda zawiera ścieżkę do pliku wykonywalnego (np. interpretera języka Python lub skompilowanego pliku .exe) oraz parametry przekazujące dane między systemem a parserem.

Podczas importu system może dodatkowo przekazać do zewnętrznego programu identyfikator rejestru bankowego. Pozwala to parserowi rozpoznać, z którego rejestru pochodzi wyciąg, i w zależności od tego zastosować inną logikę przetwarzania — na przykład odmienne typy operacji dla różnych rachunków obsługiwanych w systemie Comarch ERP XL.

W dolnej części okna konfiguracji, w sekcji Przykład wywołania, system prezentuje podgląd gotowej komendy — z pełną ścieżką do programu oraz wszystkimi argumentami — którą Comarch ERP XL uruchomi podczas odczytu wyciągu. Pozwala to zweryfikować poprawność konfiguracji jeszcze przed pierwszym uruchomieniem, a na etapie wdrożenia ułatwia diagnostykę (troubleshooting), ponieważ dokładnie pokazuje, z jakimi parametrami parser jest wywoływany.

Zadaniem wywoływanego programu jest przekształcenie pliku otrzymanego z banku na ustrukturyzowany format pośredni, który system Comarch ERP XL następnie odczytuje i księguje. Kierunek tej konwersji wskazuje argument import, przekazywany parserowi w komendzie wywołania.

W kolejnych wersjach planowane jest rozszerzenie tego mechanizmu o możliwość eksportu. System Comarch ERP XL będzie wówczas przygotowywał zlecenia w tym samym formacie pośrednim, a następnie uruchamiał skrypt użytkownika, który przekształci je do formatu wymaganego przez dany bank. Dzięki temu ten sam format pośredni oraz ten sam parser będą mogły obsłużyć wymianę danych w obu kierunkach.

W przypadku wywoływania programu poprzez pełną ścieżkę dostępu (szczególnie gdy zawiera ona spacje, np. C:\Program Files\…), należy bezwzględnie użyć operatora wywołania &. Zapewnia on poprawną interpretację ciągu znaków jako komendy wykonywalnej, a nie zwykłego tekstu.

Podłączenie ustrukturyzowanego pliku wymiany

Oprócz współpracy z zewnętrznym parserem (opisanej w rozdziale 2.1) system Comarch ERP XL umożliwia bezpośredni import gotowego pliku w formacie XML lub JSON. Ścieżkę tę stosuje się, gdy plik został przygotowany wcześniej i jest już zgodny ze strukturą wymaganą przez system — na przykład został wygenerowany przez inny program użytkownika albo utworzony ręcznie. Funkcja ta jest również przydatna diagnostycznie: pozwala szybko sprawdzić, czy dany plik JSON lub XML został zbudowany poprawnie i zostanie prawidłowo odczytany przez Comarch ERP XL.

Import bezpośredni sprawdza się w przypadku plików o prostej, płaskiej strukturze. Nie należy natomiast używać go do natywnych wyciągów w standardzie ISO 20022 (np. CAMT.053) — mimo że są to pliki XML, ich wielopoziomowe zagnieżdżenie uniemożliwia bezpośredni odczyt. Takie pliki wymagają wcześniejszego przetworzenia przez parser (rozdział 2.1), przygotowany w oparciu o dokumentację techniczną banku, dlatego w praktyce zaleca się dla nich ścieżkę parsera zamiast importu bezpośredniego.

Niezależnie od wybranej ścieżki plik przekazywany do systemu musi spełniać następujące wymagania techniczne:

Poniżej przedstawiono przykładowy fragment pliku w formacie JSON, który użytkownik chciałby zaimportować do rejestru bankowego.

W tym przykładzie plik opisuje numer rachunku, walutę i datę wyciągu, a poszczególne transakcje zebrane są w kluczu „ntry”. Aby system poprawnie odczytał takie dane, każdą informację należy powiązać z odpowiednim polem Comarch ERP XL — wskazując nazwę klucza, pod którą znajduje się ona w pliku. To powiązanie, nazywane mapowaniem, jest warunkiem prawidłowej interpretacji i dekretacji zapisów. Sposób konfiguracji mapowania dla nagłówka oraz pozycji opisano szczegółowo w rozdziale 3.

Struktura pliku wymiany

Nagłówek pliku wymiany

W zakładce Nagłówek mapuje się dane ogólne wyciągu — te, które pozwalają przypisać go do właściwego rejestru kasowo-bankowego. Dla każdej pozycji wskazuje się nazwę klucza, pod którą dana wartość występuje w pliku.

Parametry wymagane: obowiązkowo należy zmapować dwa klucze:

Parametry opcjonalne: dodatkowo można zmapować standardowe dane bankowe, takie jak:

Listę parametrów obsługuje się tak samo jak w pozostałych oknach systemu ERP:

Pozycje pliku wymiany

Zakładka Pozycje określa, jak system ma interpretować pola opisujące pojedynczą transakcję w ramach wyciągu — na przykład jej kwotę czy tytuł płatności. Podobnie jak w Nagłówku, każde pole mapuje się, wskazując nazwę klucza, pod którą występuje ono w pliku.

Pola obowiązkowe

Poniższe pola są obowiązkowe — bez ich zmapowania system nie zaimportuje transakcji:

Pola opcjonalne – dodatkowa identyfikacja kontrahenta

Opcjonalnie można przekazać dodatkowe pola ułatwiające identyfikację kontrahenta:

Pola opcjonalne – dodatkowy opis operacji

Opcjonalnie można przekazać pola, które dokładniej opisują typ operacji i wspierają jej automatyczne rozliczenie:

Pola opcjonalne – instrukcje sterujące

Standardowo system sam rozpoznaje kontrahenta (po numerze rachunku) i typ operacji (po bankowym kodzie). Poniższe pola pozwalają pominąć to automatyczne rozpoznawanie i narzucić systemowi konkretne wartości już na etapie importu:

Gotowe narzędzia i przykłady

Zawartość pakietu

Do dokumentacji dołączono pakiet ParserAgent.zip, który przyspiesza przygotowanie własnego parsera wyciągów. Zamiast pojedynczych plików testowych udostępniono kompletny zestaw materiałów: gotowy parser referencyjny, przykładowe wyciągi, instrukcje dla agenta AI oraz materiały potrzebne do zbudowania i wdrożenia rozwiązania u klienta.

ParserAgent

Na pakiet składają się następujące elementy:

Budowa parsera z pomocą AI

Głównym zadaniem pakietu jest wsparcie budowy własnego parsera przy pomocy agenta AI. Dołączone instrukcje (plik AGENTS.md), gotowy parser referencyjny MT940 oraz przykładowe wyciągi stanowią dla agenta komplet kontekstu, na podstawie którego potrafi on wygenerować parser dopasowany do indywidualnego formatu danych klienta — w dowolnym języku programowania. Pozwala to znacząco skrócić czas przygotowania niestandardowego rozwiązania.

Aby skorzystać z tej ścieżki, wystarczy otworzyć folder pakietu w wybranym narzędziu AI (np. GitHub Copilot, Cursor lub Claude Code) — agent samodzielnie odczyta instrukcje z pliku AGENTS.md. Następnie należy wskazać przykładowy plik ze swojego banku oraz preferowany język programowania; na tej podstawie agent wygeneruje parser zgodny z wymaganiami systemu Comarch ERP XL i zweryfikuje go na dołączonych przykładach.

Parser referencyjny można też wykorzystać samodzielnie — jako gotowe narzędzie do testów lub punkt wyjścia do własnej implementacji. Jest dostępny w wersji źródłowej (Python) oraz jako samodzielny plik wykonywalny, który nie wymaga instalowania środowiska Python u klienta. Kodowanie pliku wejściowego i powiązanie pól wyciągu z nazwami kluczy konfiguruje się w sekcji ustawień na początku pliku parsera, dzięki czemu dostosowanie do konkretnego banku najczęściej nie wymaga ingerencji w logikę przetwarzania.