Konektor Comarch ERP Optima
Zestaw narzędzi udostępniający dane z systemu Comarch ERP Optima innym aplikacjom. Zamiast pobierać dane bezpośrednio z bazy albo przepisywać je ręcznie, system zewnętrzny odpytuje konektor zwykłymi żądaniami HTTP i otrzymuje powiadomienia o nowych oraz opłaconych fakturach. Konektor nie jest przypisany do konkretnego programu — komunikacja odbywa się przez standardowe REST API i webhooki w formacie JSON, więc odbiorcą danych może być CRM, sklep internetowy, aplikacja własna lub platforma automatyzacji. W skład rozwiązania wchodzi również generator wydruków PDF faktur, współpracujący bezpośrednio z Comarch ERP Optima. Całość instalowana jest na serwerze klienta, przy jego bazie danych.
Kluczowe funkcje
1. Dane kontrahentów
Konektor pozwala pobierać dane kontrahenta po numerze NIP oraz zakładać nowych kontrahentów w Optimie na podstawie danych przesłanych z systemu zewnętrznego: nazwy, numeru NIP, adresu oraz identyfikatora UUID. Akronim kontrahenta tworzony jest automatycznie, a numer NIP podlega walidacji. Obsługiwane są numery krajowe i zagraniczne, z prefiksem kraju i bez niego — w przypadku braku prefiksu przyjmowany jest domyślnie „PL". Identyfikator UUID zapisywany jest jako atrybut kontrahenta i stanowi trwałe powiązanie rekordu Optimy z rekordem w systemie zewnętrznym; można go również zaktualizować osobnym żądaniem. Przy zakładaniu kontrahenta i zmianie identyfikatora kontrolowane są duplikaty — zarówno po numerze NIP, jak i po UUID.
2. Salda i rozrachunki
Aplikacja zwraca bieżące saldo kontrahenta wyliczone bezpośrednio z rozrachunków księgowych, w podziale na waluty. Odpowiedź zawiera kwotę, którą kontrahent jest winien firmie, kwotę, którą firma jest winna kontrahentowi, łączną kwotę pozostającą do rozliczenia oraz saldo końcowe. Wartość dodatnia salda oznacza zaległość po stronie kontrahenta, ujemna — zobowiązanie firmy, na przykład nadpłatę lub zwrot. Sposób liczenia jest konfigurowalny: wskazać można konta księgowe brane pod uwagę, minimalną kwotę, od której rozrachunek jest uznawany za istotny, oraz walutę domyślną.
3. Faktury sprzedaży
Konektor udostępnia pełne dane faktury sprzedaży wraz z listą pozycji towarowych oraz statusem rozrachowania dokumentu. Zwracane są także dane KSeF: numer KSeF, status, data wysłania, data odebrania UPO, data przyjęcia i link weryfikacyjny. Listę faktur można stronicować i sortować według daty wystawienia, operacji lub księgowania, numeru dokumentu, statusu i nazwy, a także filtrować po zakresie dat ze wskazaniem, która data ma być brana pod uwagę. Dostępne jest również wyszukiwanie po numerze faktury oraz po identyfikatorze UUID kontrahenta. Gotowy plik PDF faktury pobierany jest pojedynczym żądaniem.
4. Powiadomienia webhook
Konektor monitoruje w tle zmiany w dokumentach i rozrachunkach, w cyklu około sześćdziesięciu sekund, i wysyła powiadomienia HTTP POST do systemu zewnętrznego. Obsługiwane są dwa zdarzenia: „invoice.created" — wystawienie nowej faktury, oraz „invoice.changedStatus" — zmiana statusu dokumentu lub jego rozrachunku, na przykład odnotowanie płatności. Powiadomienie zawiera identyfikator faktury, numer NIP, nazwę kontrahenta, datę oraz identyfikator UUID kontrahenta. Adres odbiorcy konfigurowany jest osobno dla każdego typu zdarzenia. W razie niepowodzenia wysyłka jest ponawiana trzykrotnie z rosnącym odstępem czasowym, a nieudane próby trafiają do logów błędów i powiadomień e-mail.
5. Generator wydruków PDF
Generator tworzy wydruki faktur bezpośrednio z Comarch ERP Optima, korzystając z mechanizmu wydruków systemu ERP. Mapowanie rodzaju dokumentu na wzorzec wydruku jest konfigurowalne — osobno dla faktury sprzedaży, korekty ilościowej i korekty wartościowej — co pozwala podpiąć wydruki własne klienta bez zmian w kodzie. Uwzględniany jest status KSeF: dokument generowany jest dopiero po odebraniu UPO, przy czym dla faktur sprzed wdrożenia KSeF można wskazać datę graniczną, od której warunek obowiązuje. Opcjonalnie generator przeszukuje folder „Wysłane" skrzynki pocztowej przez IMAP i, jeśli odnajdzie wcześniej wysłany załącznik, archiwizuje dokładnie ten dokument, który otrzymał kontrahent. Status generowania każdego pliku — wygenerowany, oczekujący lub zakończony błędem — kontrolowany jest po stronie API.
6. Dokumentacja API
Aplikacja udostępnia pełną, interaktywną dokumentację w formacie OpenAPI (Swagger), dostępną pod adresem /docs. Każdy endpoint opisany jest wraz z parametrami, przykładowymi danymi wejściowymi i kodami odpowiedzi, a żądania można wykonywać bezpośrednio z przeglądarki. Dokumentację można również pobrać jako plik JSON, na przykład w celu zaimportowania do Postmana lub wygenerowania klienta API. Aplikacja zawiera także changelog z historią wprowadzonych zmian.
7. Logi, monitoring i powiadomienia o błędach
Wszystkie żądania oraz błędy zapisywane są w bazie danych — z metodą, adresem endpointu, statusem odpowiedzi, czasem wykonania, treścią żądania i odpowiedzi oraz parametrami zapytania. Podgląd logów dostępny jest w panelu administracyjnym, z podziałem na logi zapytań i logi błędów oraz stronicowaniem. Błędy krytyczne zgłaszane są dodatkowo e-mailem, z ograniczeniem częstotliwości — ten sam rodzaj błędu nie jest wysyłany częściej niż raz na godzinę. Jeżeli zapis logu do bazy danych się nie powiedzie, dane zapisywane są do pliku i dopisywane do bazy przy najbliższej możliwej okazji.
8. Bezpieczeństwo i konfiguracja
Każde żądanie do API autoryzowane jest kluczem przesyłanym w nagłówku X-API-KEY. Aplikacja przygotowana jest do pracy po HTTPS — połączenie szyfrowane konfigurowane jest przy wdrożeniu, na poziomie serwera IIS lub serwera pośredniczącego. Dostęp do panelu administracyjnego chroniony jest logowaniem. Aplikacja działa na serwerze klienta i łączy się bezpośrednio z jego bazą firmową, więc dane nie są przekazywane do żadnej usługi pośredniczącej. Parametry wdrożeniowe ustawiane są w plikach konfiguracyjnych, bez ingerencji w kod: połączenie z bazą danych, klucz API, adresy webhooków, katalog plików PDF, parametry serwera SMTP i skrzynki IMAP, dane operatora oraz firmy w Optimie, typ dokumentu sprzedaży, kod atrybutu przechowującego identyfikator kontrahenta, konta księgowe i próg kwoty przy liczeniu salda, waluta domyślna oraz mapowanie wzorców wydruku.
