Integracja Comarch ERP Optima ↔ Bitrix24 — obieg akceptacji faktur kosztowych
Rozwiązanie, które przenosi obieg akceptacji faktur kosztowych z Comarch ERP Optima do Bitrix24 i zamyka pętlę z powrotem w ERP. Faktury zarejestrowane w Optimie trafiają automatycznie do Bitrix24 jako elementy procesu — wraz z kompletem danych, wydrukiem PDF oraz informacjami odczytanymi bezpośrednio z ustrukturyzowanego dokumentu KSeF. Osoba odpowiedzialna akceptuje lub odrzuca koszt w Bitrix24, a decyzja i komentarz wracają do Optimy i zapisują się przy dokumencie. Dzięki temu ERP pozostaje jedynym źródłem prawdy o dokumencie, a cała komunikacja z osobami zatwierdzającymi odbywa się w CRM, bez licencji Optimy dla każdego uczestnika procesu.
Rozwiązanie składa się z dwóch niezależnych aplikacji instalowanych lokalnie, przy bazie firmowej Comarch ERP Optima: aplikacji eksportującej faktury do Bitrix24 oraz API przyjmującego decyzje zwrotne z Bitrix24.
Kluczowe funkcje
1. Automatyczny eksport faktur kosztowych do Bitrix24
Aplikacja cyklicznie przegląda rejestr VAT w bazie Comarch ERP Optima i wybiera dokumenty, które nie zostały jeszcze przekazane do CRM. Kwalifikacja opiera się na jasnych kryteriach: rodzaj dokumentu w rejestrze, data wystawienia od ustalonej daty granicznej (co zapobiega masowemu wysyłaniu dokumentów sprzed wdrożenia), niezerowa wartość netto oraz brak znacznika wcześniejszego eksportu. Dla każdej faktury pobierany jest komplet danych nagłówka — numer, daty wystawienia, sprzedaży i terminu płatności, dane kontrahenta z numerem NIP, wartości netto, VAT i brutto, forma płatności oraz numer KSeF — a także lista pozycji z rejestru VAT wraz z opisem kategorii, wartością netto, stawką i wyliczoną kwotą VAT oraz wartością brutto. Każda faktura przetwarzana jest niezależnie: błąd na jednym dokumencie nie przerywa całego przebiegu, a podsumowanie z liczbą sukcesów i błędów trafia do dziennika.
2. Odczyt danych z ustrukturyzowanego dokumentu KSeF
To element, który odróżnia rozwiązanie od zwykłego przekazania danych z bazy. Aplikacja sięga do oryginalnego pliku XML faktury ustrukturyzowanej przechowywanego przez Optimę i odczytuje z niego informacje, których nie ma w standardowych polach dokumentu. Obsługiwany jest zarówno zapis jawny, jak i skompresowany — plik jest automatycznie rozpakowywany po stronie serwera bazy danych, bez pobierania całości do aplikacji. Z dokumentu wyciągane są pozycje „Dodatkowy opis" (pary klucz–wartość, którymi wystawca opisuje fakturę) oraz treść stopki faktury. Ze stopki dodatkowo wyłuskiwane są identyfikatory w formacie „ID <numer>" — typowo oznaczenie zamówienia, projektu lub osoby, która wygenerowała koszt — z pominięciem powtórzeń. Wszystkie odczytane fragmenty łączone są z opisem dokumentu z Optimy w jeden czytelny komentarz przekazywany do Bitrix24, dzięki czemu osoba akceptująca od razu widzi, czego dotyczy koszt, bez otwierania załącznika. Jeżeli XML jest pusty lub nie da się go sparsować, dokument i tak zostanie wyeksportowany — po prostu bez części opisowej, z odpowiednim wpisem w logu.
3. Wydruk PDF generowany bezpośrednio z Optimy
Do każdej faktury dołączany jest wydruk PDF przygotowany przez sam mechanizm wydruków Comarch ERP Optima — dokument jest więc identyczny z tym, który powstaje z poziomu programu, łącznie z układem i danymi firmy. Obsługiwane są zarówno wzorce standardowe, jak i wzorce własne; numer wzorca oraz jego rodzaj ustawiane są w konfiguracji, bez zmian w kodzie. Wydruk powstaje w katalogu tymczasowym, jest wczytywany do pamięci, przekazywany do Bitrix24 jako załącznik dokumentu, a plik tymczasowy natychmiast usuwany — na dysku serwera nie zostaje żadna kopia dokumentu. Przed generowaniem sprawdzana jest obecność dokumentu w bazie oraz kompletność danych wymaganych przez wydruk, dzięki czemu w logu pojawia się konkretna przyczyna, a nie surowy błąd mechanizmu wydruków.
4. Utworzenie elementu w procesie Bitrix24 z mapowaniem pól
Faktura wysyłana jest do Bitrix24 przez webhook przychodzący, jako element wskazanego procesu (Smart Process), od razu na właściwym etapie startowym. Wypełniane są pola: numer faktury (również jako tytuł elementu), numer NIP i nazwa kontrahenta, numer NIP spółki będącej nabywcą, wartość brutto, forma płatności, numer KSeF, komentarz zbudowany z danych KSeF, identyfikator dokumentu w Optimie oraz plik PDF faktury. Numer NIP kontrahenta jest normalizowany do samych cyfr, a znaki mogące zaburzyć strukturę danych są usuwane z treści komentarza. Identyfikator dokumentu z Optimy zapisany w Bitrix24 stanowi trwałe powiązanie obu systemów i to on jest później używany przy zapisie decyzji zwrotnej.
Obsługa wielu spółek — numer NIP nabywcy jest parametrem konfiguracyjnym, więc ta sama aplikacja obsługuje kolejne spółki grupy: wystarczy osobna konfiguracja wskazująca inną bazę firmową, a dokumenty trafiają do wspólnego procesu w Bitrix24 z poprawnym oznaczeniem spółki.
Mapowanie form płatności — forma płatności z Optimy tłumaczona jest na wartość słownikową Bitrix24 (gotówka, przelew). Dla form nieujętych w mapowaniu stosowana jest wartość domyślna, a zdarzenie odnotowywane jest w logu ostrzeżeniem — dokument zostaje wyeksportowany, zamiast blokować cały przebieg.
5. Znacznik eksportu w Optimie — brak duplikatów
Po potwierdzeniu przyjęcia dokumentu przez Bitrix24 faktura oznaczana jest atrybutem w bazie Optimy. Znacznik zapisywany jest wyłącznie po udanej wysyłce, więc dokument, którego nie udało się przekazać, zostanie ponowiony przy kolejnym uruchomieniu — bez ryzyka utworzenia drugiego elementu w CRM dla tej samej faktury. Definicja atrybutu zakładana jest automatycznie przy pierwszym uruchomieniu, jeśli nie istnieje w bazie, a przed zapisem sprawdzana jest obecność znacznika — operacja jest więc bezpieczna przy powtórnym wykonaniu. Atrybut jest widoczny na dokumencie w Optimie wraz z datą przekazania, co daje operatorowi bezpośrednią informację o stanie eksportu, bez zaglądania do logów.
6. Zwrotna aktualizacja komentarza z Bitrix24 w Optimie
Drugi moduł to API przyjmujące dane z Bitrix24. Komentarz wpisany przez osobę obsługującą proces w CRM dopisywany jest do opisu dokumentu w Optimie, z czytelnym prefiksem wskazującym źródło wpisu i z zachowaniem dotychczasowej treści opisu — kolejne uwagi dopisują się w nowych liniach, zamiast nadpisywać poprzednie. Jeżeli zapis w polu opisu dokumentu nie jest możliwy, komentarz zapisywany jest w dedykowanym atrybucie dokumentu, którego definicja tworzona jest automatycznie przy pierwszym użyciu. Odpowiedź API jednoznacznie wskazuje, którym z dwóch sposobów komentarz został zapisany. Żądanie dotyczące nieistniejącego dokumentu kończy się czytelnym komunikatem, a nie błędem serwera.
7. Zwrotny zapis statusu akceptacji kosztu
Decyzja podjęta w Bitrix24 — akceptacja albo odrzucenie kosztu — zapisywana jest w atrybucie dokumentu w Optimie. Atrybut aktualizowany jest, jeśli już istnieje przy dokumencie, a zakładany, jeśli go brakuje; brakująca definicja atrybutu również tworzona jest automatycznie. Dzięki temu status akceptacji jest widoczny bezpośrednio na dokumencie w Optimie, można po nim filtrować listy dokumentów i wykorzystać go w dalszym obiegu księgowym — bez potrzeby logowania się do CRM.
8. Praca bez nadzoru, logi i konfiguracja
Aplikacja eksportująca to program konsolowy uruchamiany cyklicznie przez Harmonogram zadań Windows — częstotliwość ustala się dowolnie, zależnie od tego, jak szybko faktury mają pojawiać się w CRM. Każdy przebieg zapisywany jest w szczegółowym dzienniku z podziałem na pliki dzienne: logowanie do Optimy, liczba dokumentów zakwalifikowanych i pominiętych wraz z przyczyną pominięcia, wynik odczytu XML z KSeF, treść komentarza przekazanego do CRM, zastosowane mapowanie formy płatności, odpowiedź Bitrix24 dla każdej faktury oraz pełna treść błędów. Ten sam mechanizm logowania obejmuje API, wraz z centralną obsługą nieprzewidzianych wyjątków. Wszystkie parametry wdrożeniowe ustawiane są w plikach konfiguracyjnych, bez ingerencji w kod: połączenie z bazą firmową, adres webhooka Bitrix24, katalog plików tymczasowych, data graniczna, numer NIP nabywcy, wzorzec wydruku oraz operator, hasło, firma i katalog instalacyjny Comarch ERP Optima.
