Praca z parserem wyciągu bankowego
Wyciągi bankowe dostarczane przez instytucje finansowe przesyłane są zazwyczaj w formie plików tekstowych (np. format MT940) lub w postaci ustrukturyzowanej (standard XML).
System Comarch ERP XL został wyposażony w natywną obsługę formatu SWIFT MT940, która umożliwia odczyt oraz import większości standardowych plików tekstowych. Ze względu na uniwersalny charakter tego mechanizmu, w określonych przypadkach może on nie zapewniać pełnej kompatybilności ze specyficznymi formatami danych lub niestandardowymi metodami kodowania znaków.
Dotychczas system nie wspierał również importu plików w formatach ustrukturyzowanych (CAMT.053). Import tego typu danych pozostaje dostępny wyłącznie poprzez kanał Webservice, który umożliwia ich jednoczesne odczytywanie, zgodnie ze specyfikacją przekazaną przez konkretny bank.
W celu zapewnienia wsparcia dla plików, które nie są natywnie w pełni obsługiwane, system udostępnia narzędzia pozwalające na bieżącą konfigurację i dostosowanie parametrów importu do indywidualnych wymagań użytkownika oraz specyfikacji dostarczanych plików.
Koncepcja systemu opiera się na odseparowaniu procesów odczytu oraz interpretacji wyciągów bankowych od rdzenia systemu i przeniesieniu ich do zewnętrznego modułu wykonawczego. Takie podejście zapewnia użytkownikowi pełną kontrolę nad mechanizmem przetwarzania danych.
Kluczowe cechy rozwiązania:
- Otwartość technologiczna: System Comarch ERP XL umożliwia wykorzystanie programów napisanych w dowolnym języku programowania.
- Wsparcie programistyczne: Comarch dostarcza przykładowy kod źródłowy oraz definicję agenta AI, który mogą służyć jako baza do samodzielnej modyfikacji i dostosowania do specyficznych wymagań.
- Mechanizm wymiany danych:
- System ERP XL przekazuje plik źródłowy wyciągu do zewnętrznego programu.
- Zewnętrzny moduł dokonuje transformacji danych.
- System odbiera przetworzony plik o ustandaryzowanej strukturze, gotowy do dalszego księgowania.
Definicja ustrukturyzowanego formatu wymiany
Budowa formatu z wykorzystaniem parsera
Definiowanie parametrów wymiany danych z zewnętrznym parserem odbywa się w module Administrator. Proces ten realizowany jest w ramach zarządzania strukturami płatności i wyciągów.
W celu skonfigurowania nowego mechanizmu należy:
- Przejść do okna Lista formatów przelewów (ścieżka: Firma / Formaty przelewów).
- Wybrać opcję dodania nowego formatu wymiany.
- Ustawić opcję Własny parser pliku wyciągu bankowego.
W systemie Comarch ERP XL, wzorem pozostałych formatów przelewów definiowalnych, wprowadzono mechanizm wskazywania domyślnego rozszerzenia plików. Parametr ten określa typ plików, które będą automatycznie pobierane i przetwarzane przez program parsera.
Kluczowym elementem konfiguracji w oknie formatu jest komenda wywołania. Jest to instrukcja uruchamiana bezpośrednio w powłoce systemowej Windows w momencie, gdy system inicjuje proces odczytu wyciągu bankowego.
Prawidłowo skonfigurowana komenda powinna zawierać ścieżkę do pliku wykonywalnego (np. interpretera języka Python lub skompilowanego pliku .exe) oraz niezbędne parametry przekazujące dane między systemem a parserem.
Podczas wywoływania procedury importu istnieje możliwość przekazania identyfikatora rejestru bankowego jako parametru do programu zewnętrznego.
Funkcjonalność ta pozwala na automatyczne różnicowanie działań parsera w zależności od kontekstu źródłowego. Dzięki temu użytkownik może zdefiniować w zewnętrznej aplikacji odmienne typy operacji przypisane do konkretnych rejestrów bankowych obsługiwanych w systemie Comarch ERP XL.
Podgląd przykładowej instrukcji, która zostanie wygenerowana i wykonana przez system Comarch ERP XL, znajduje się w dolnej części okna konfiguracji w sekcji Przykład wywołania.
Informacje zawarte w tym polu są kluczowe podczas diagnostyki (troubleshootingu) na początkowym etapie wdrażania rozwiązania.
Program wywoływany przez powłokę systemową (Powershell) ma za zadanie wygenerowanie pliku wyjściowego, który zostanie zainicjowany i przetworzony przez system Comarch ERP XL.
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.
& “C:\Sciezka Do Programu\app.exe” –parametr
Podłączenie ustrukturyzowanego pliku wymiany
Oprócz standardowej wymiany danych za pomocą dedykowanego parsera, system Comarch ERP XL umożliwia import informacji z plików w formatach XML oraz JSON.
Należy zwrócić uwagę, że bezpośredni import plików o złożonej strukturze nie zawsze jest możliwy. Dokumenty o wysokim stopniu skomplikowania – np. wyciągi bankowe w standardzie ISO 20022 (np. arkusze CAMT.053) – wymagają wstępnego przetworzenia przez parser użytkownika. Proces ten powinien zostać przygotowany w oparciu o dokumentację techniczną dostarczoną przez bank, co gwarantuje poprawność odczytu i interpretacji danych w systemie.
Wymagania techniczne dotyczące pliku wynikowego:
- Obsługiwane formaty: Dane muszą zostać zapisane w formacie XML lub JSON.
- Kodowanie: UFT-8
- Struktura danych: składa się z dwóch obszarów:
- Nagłówek: Określa dane ogólne wyciągu, takie jak numer rachunku, daty operacji oraz salda początkowe i końcowe.
- Pozycje: Definiuje strukturę poszczególnych operacji bankowych, w tym kwoty, dane kontrahentów oraz tytuły płatności.
Poniżej przedstawiono przykładowy fragment pliku w formacie JSON, który użytkownik chciałby zaimportować do rejestru bankowego.
Na powyższym przykładzie wyciąg bankowy składa się z informacji o numerze prowadzonego rachunku, walucie, daty wyciągu oraz zestawu poszczególnych transakcji, które zostały umieszczone w kluczu „ntry”.
Proces odczytu danych opiera się na mapowaniu odpowiednich elementów poprzez wskazanie konkretnych nazw kluczy, które są powiązane z informacjami wykorzystywanymi przez system ERP XL. Prawidłowe ich zmapowanie jest warunkiem koniecznym do poprawnej interpretacji danych oraz ich późniejszej dekretacji.
Struktura pliku wymiany
Nagłówek pliku wynikowego
W zakładce Nagłówek definiuje się ogólne informacje, które pozwalają na przyporządkowanie poszczególnych informacji do właściwego rejestru kasowo/bankowego.
Wymagane parametry: Obowiązkowe jest wskazanie kluczy zawierających
- Numer konta oraz
- Pozycje wyciągu: sekcja zawierająca ciąg kolejnych operacji na tym rachunku.
Parametry opcjonalne: Możliwe jest mapowanie dodatkowych standardowych informacji bankowych, takich jak:
- Data wyciągu,
- Saldo otwarcia i zamknięcia,
- Waluta rachunku.
Obsługa listy parametrów jest typowa dla innych okien systemu ERP:
- Dodawanie i usuwanie: Zarządzanie dostępnymi informacjami odbywa się za pomocą przycisków funkcyjnych: plusa (dodaj) oraz kosza (usuń).
- Edycja: System podpowiada najczęściej występujące nazwy kluczy. Zmiana nazwy klucza realizowana jest bezpośrednio na liście przy użyciu metody edit-in-place (podwójne kliknięcie na odpowiednim wierszu w kolumnie Nazwa klucza).
Pozycje pliku wynikowego
W zakładce Pozycje definiowane są zasady interpretacji poszczególnych pól pliku wynikowego jako danych konkretnej transakcji w ramach wyciągu bankowego (np. tytuł płatności oraz kwota). Proces odczytu danych w tej sekcji, analogicznie do sekcji Nagłówek, opiera się na mapowaniu odpowiednich elementów poprzez wskazanie konkretnych nazw kluczy.
Pola obowiązkowe
W sekcji tej należy obligatoryjnie skonfigurować następujące pola:
- Data operacji: określa domyślną datę zapisu kasowo-bankowego.
- Kwota: wartość transakcji
- Strona operacji: definiuje sposób księgowania kwoty transakcji (jako uznanie lub obciążenie rachunku). System interpretuje standardowe oznaczenia stosowane w wyciągach bankowych:
- Uznanie (przychód środków pieniężnych)
- Podstawowe oznaczenie: C
- Dopuszczalne warianty: Cr, Credit
- Obciążenie (rozchód środków pieniężnych)
- Podstawowe oznaczenie: D
- Dopuszczalne warianty: Db, Debit
- Uznanie (przychód środków pieniężnych)
- Nazwa kontrahenta: pole służące do identyfikacji drugiej strony operacji bankowej. Parametr ten jest wymagany do poprawnego zaimportowania zapisu. W sytuacjach, gdy stroną operacji jest bank (np. w przypadku pobrania prowizji lub opłat bankowych), dane kontrahenta mogą nie występować w pliku źródłowym. W takim przypadku zaleca się, aby parser po stronie użytkownika zawierał logikę uzupełniającą to pole wartością domyślną, np. nazwą banku lub frazą „N/A”.
- Tytuł operacji: opis transakcji.
Pola opcjonalne – dodatkowa identyfikacja kontrahenta
Możliwe jest także przekazanie szeregu pól dodatkowych, pozwalających na identyfikację kontrahenta jak:
- Adres kontrahenta: pole tekstowe przeznaczone na pełne dane adresowe kontrahenta.
- Numer rachunku kontrahenta: parametr służący do jednoznacznej identyfikacji karty kontrahenta w systemie Comarch ERP XL
- Mechanizm identyfikacji: System automatycznie wiąże operację z kontrahentem, jeśli importowany numer rachunku znajduje się na liście przypisanych do niego kont.
- Standard zapisu: Wszystkie numery rachunków w bazie danych przechowywane są w notacji stosowanej dla rachunków IBAN (czyli numer rachunku poprzedzony jest kodem kraju).
- Rekomendacja: Przekazywanie rachunku z kodem kraju, również dla krajów spoza strefy IBAN (np. USA, Chiny) – znacząco przyspiesza proces identyfikacji. W przypadku otrzymania wyłącznie numeru konta, system podejmuje próbę automatycznego rozpoznania kraju kontrahenta w celu odnalezienia powiązanego rekordu.
- Pełny rachunek wirtualny: pole umożliwiające identyfikację kontrahenta na podstawie indywidualnego numeru konta, na który dokonano wpłaty. Funkcjonalność ta jest wykorzystywana w rejestrach bankowych obsługujących płatności masowe (rachunki wirtualne). Wymagania techniczne:
- Format NRB: W celu zapewnienia unikalności identyfikacji, system wymaga podania pełnego polskiego numeru rachunku w standardzie NRB (26 cyfr wraz z sumą kontrolną).
- Zadanie parsera: W sytuacjach, gdy bank w pliku wynikowym udostępnia jedynie końcowy fragment rachunku wirtualnego, parser po stronie użytkownika musi automatycznie rozwinąć go do pełnej, 26-cyfrowej formy przed przekazaniem danych do systemu Comarch ERP XL
- Identyfikator operacji: pole służące do unikalnej identyfikacji przelewu, który został wygenerowany i zlecony bezpośrednio z poziomu systemu ERP. Obecność tego identyfikatora w treści importowanego wyciągu umożliwia systemowi automatyczne rozliczenie transakcji
- Specyfikacja techniczna: System najczęściej wykorzystuje 10-znakowy kod w zapisie szesnastkowym, który z reguły rozpoczyna się od litery C (np. C000006001). Konkretna implementacja może jednak różnić się w zależności od serwisu bankowego i konfiguracji bazy.
Pola opcjonalne – dodatkowy opis operacji
Możliwe jest także przekazanie pól, pozwalających na dodatkowy opis typu operacji:
- Bankowy kod operacji: pole tekstowe zawierające ciąg cyfr lub znaków definiujących typ operacji zgodnie ze specyfikacją danego banku. Wykorzystanie kodów transakcyjnych umożliwia precyzyjne określenie rodzaju przelewu w sytuacjach, gdy treść pola Tytuł operacji jest niewystarczająca do poprawnej klasyfikacji zdarzenia gospodarczego.
- Numer referencyjny operacji banku: unikalny identyfikator przypisywany przez bank do konkretnej transakcji (stosowany m.in. przez bank Pekao). Pole to jest wykorzystywane przez system do mechanizmu wykrywania duplikatów, co pozwala na automatyczne pomijanie zapisów już zaimportowanych.
- Zasada działania weryfikacji: System zablokuje ponowny import operacji, jeżeli na liście zapisów pod tą samą datą istnieje już rekord o identycznej kwocie oraz takim samym numerze referencyjnym
Pola opcjonalne – instrukcje sterujące
Pola takie jak Numer rachunku kontrahenta oraz Bankowy kod operacji są wykorzystywane przez system Comarch ERP XL do precyzyjnej identyfikacji transakcji. Proces ten obejmuje:
- Weryfikację kontrahenta: Automatyczne odnalezienie odpowiedniego podmiotu w bazie danych na podstawie numeru rachunku.
- Klasyfikację operacji: Przypisanie właściwego typu operacji, zdefiniowanego dla danego rejestru bankowego.
Istnieje możliwość przekazania konkretnych wartości tych pól bezpośrednio z pliku ustrukturyzowanego. Pozwala to na narzucenie systemowi Comarch ERP XL docelowej interpretacji danych już na etapie importu. Służą do tego opcjonalne pola:
- XL Akronim kontrahenta: W przypadku uzupełnienia tego pola system pomija proces identyfikacji karty podmiotu na podstawie numeru rachunku bankowego. Do zapisu kasowo-bankowego zostaje automatycznie przypisany kontrahent o wskazanym akronimie
- XL GidTyp: Pole opcjonalne, interpretowane wspólnie z parametrem XL Akronim kontrahenta. Parametr ten określa typ podmiotu, który zostanie przypisany do operacji bankowej na podstawie wskazanego akronimu. W zależności od wprowadzonej wartości, system interpretuje akronim w następujący sposób:
- Brak wartości (domyślnie): System identyfikuje kontrahenta (GidTyp 32).
- 944: Przypisanie pracownika.
- 4304: Przypisanie urzędu.
- 48: Przypisanie banku.
- 0: Ustawienie podmiotu typu „INNY”.
Wykorzystanie pola XL GidTyp pozwala na precyzyjne wskazanie typu rekordu w bazie danych, eliminując ryzyko błędnej identyfikacji w przypadku powtarzających się akronimów w różnych kategoriach podmiotów
- XL Kod operacji: Mechanizm księgowania dokumentu w systemie Comarch ERP XL jest determinowany przez przypisany do niego Typ operacji kasowo-bankowej. Aby dany typ operacji był dostępny, musi zostać uprzednio powiązany z właściwym rejestrem. W przypadku występowania wielu typów operacji (np. wynagrodzenia, prowizje, odsetki), system umożliwia ich automatyczne rozpoznawanie na podstawie definicji skonfigurowanych w module Księgowość / Kasa/Bank / Definicje banków
Zastosowanie pola XL Kod operacji w pliku ustrukturyzowanym pozwala na:
- Pominięcie etapu automatycznego rozpoznawania operacji przez system.
- Bezpośrednie narzucenie właściwego typu operacji dla importowanego zapisu
Pliki testowe
Przykładowy parser mBank MT940
Poniżej znajduje się przykładowy kod źródłowy opracowany w języku Python, prezentujący przykładową strukturę pliku parsera, który został opracowany na przykładzie dokumentacji mBank. Należy podkreślić, że wybór technologii programistycznej jest dowolny i nie wpływa na poprawność współpracy z systemem Comarch ERP XL.
Wykorzystanie generatywnej AI
Comarch, jako organizacja wdrażająca zaawansowane rozwiązania z zakresu sztucznej inteligencji, promuje wykorzystanie technologii AI również wśród swoich klientów. W związku z tym do dokumentacji technicznej dołączono dedykowanego agenta AI, wyspecjalizowanego w konwersji plików bankowych do formatu zgodnego z systemem Comarch ERP XL.
Zastosowanie agenta AI powinno pozwolić na znaczne skrócenie czasu przygotowania niestandardowych rozwiązań ściśle dopasowanych do indywidualnych potrzeb i specyficznych formatów danych klienta.
