Comarch ERP Optima nie oferuje publicznego REST API. Firmy integrujące swoje systemy z Optimą muszą wybierać między COM objects, bezpośrednim SQL a rozwiązaniami third-party. Ten artykuł porównuje wszystkie trzy podejścia — z konkretnymi przykładami kodu, ograniczeniami i rekomendacjami.

Najważniejsze informacje

REST API Comarch Optima jest najwygodniejszym kontraktem dla e-commerce, WMS, CRM i aplikacji webowych, ale Comarch nie udostępnia go publicznie w standardzie HTTP/JSON.
COM objects zapewniają walidację biznesową, lecz wymagają Windows, sesji Optimy i programisty znającego nieudokumentowane obiekty.
Bezpośredni SQL nadaje się najwyżej do odczytów read-only. Zapis dokumentów przez SQL omija reguły Optimy i jest ryzykowny.
Optima API od WebArm łączy wygodę REST API z walidacją zapisów przez mechanizmy Comarch ERP Optima.

Porównanie legacy COM objects z nowoczesnym REST API — chaos kabli vs czyste przepływy danych

Problem: brak standardowego interfejsu

Comarch Optima to jeden z najpopularniejszych systemów ERP w Polsce. Mimo to, integracja z zewnętrznymi systemami — sklepy internetowe, CRM, narzędzia AI — pozostaje wyzwaniem. Oficjalnie dostępne metody mają istotne ograniczenia. Przyczyny tego stanu rzeczy opisujemy szczegółowo w artykule dlaczego Comarch nie oferuje publicznego REST API.

Web API, REST API i Comarch ERP Optima: co to oznacza dla twojego biznesu

W praktyce firmy pytają o Web API, REST API i obiekty COM, ale porównują trzy różne poziomy integracji. Web API kojarzy się z usługą dostępną po sieci, często z XML lub SOAP. REST API oznacza prostszy kontrakt HTTP/JSON, z którym łatwo pracują sklepy, CRM, WMS i inne aplikacje webowe. Obiekty COM są natomiast lokalnym mechanizmem Windows, bliższym automatyzacji zainstalowanego programu niż publicznemu interfejsowi dla systemów zewnętrznych.

Dla systemu Comarch ERP Optima wybór metody wpływa nie tylko na kod. Decyduje też o czasie wdrożenia, kompatybilności wersji, kontroli dostępu, rozliczaniu błędów i dodatkowych kosztach utrzymania. Jeżeli integracja ma obsługiwać zamówienie ze sklepu, faktury sprzedaży, płatności, stany magazynowe i dane kontrahenta bez ręcznego przepisywania, warstwa API powinna ukrywać złożoność programu, a nie przerzucać ją na każdy system klienta ani na inne aplikacje w firmie.

Metoda 1: COM objects (.NET/C++)

COM objects to najstarsza metoda integracji z Comarch Optimą. Polega na programowym wywoływaniu obiektów COM zarejestrowanych przez instalację Optimy na serwerze Windows.

Jak to wygląda w praktyce

Typowa integracja przez COM wymaga z grubsza takich kroków po stronie kodu klienta (.NET/C++ na Windows z zainstalowaną Comarch ERP Optima):

Inicjalizacja sesji oficjalnym interfejsem Optimy (logon firmy, użytkownika, hasła)
Utworzenie obiektu biznesowego odpowiadającego encji (np. kontrahenci, towary, faktury)
Ustawienie filtra zawężającego zbiór rekordów
Iteracja po rekordach z odczytem każdego pola pojedynczo
Zwolnienie obiektu i zamknięcie sesji — krytyczne dla zwolnienia zasobów COM

W praktyce to kilkadziesiąt linii kodu .NET tylko na pobranie listy aktywnych kontrahentów — przy każdej operacji powtarzalnego boilerplate’u. Każda operacja zapisu (utworzenie faktury, modyfikacja kontrahenta) wymaga znajomości kolejności pól, walidacji wstępnej i obsługi błędów COM, które potrafią się objawiać brakiem komunikatu (HRESULT 0x80020009 jako jedyny ślad).

Ograniczenia COM objects

Tylko Windows — COM działa wyłącznie na Windows z zainstalowaną Optimą
Brak dokumentacji — API nie jest oficjalnie dokumentowane; programiści uczą się metodą prób i błędów
Sesyjność — każde połączenie wymaga logowania do sesji Optimy, co jest wolne i zasobożerne
Kruche po aktualizacji — nowa wersja Optimy może zmienić sygnatury obiektów COM bez ostrzeżenia
Brak concurrency — obiekty COM nie są thread-safe; każda operacja blokuje sesję
Czas integracji — typowo 2–6 miesięcy pracy doświadczonego programisty .NET

Metoda 2: Bezpośredni SQL

Niektóre firmy omijają oficjalne mechanizmy i operują bezpośrednio na bazie danych SQL Server, w której Optima przechowuje dane.

Dlaczego to zły pomysł

Niskopoziomowe SELECT na bazie wygląda kuszące — kilka linii, natychmiastowy wynik. Problem zaczyna się przy operacjach zapisu. Optima przy każdym dodaniu faktury, modyfikacji kontrahenta czy zatwierdzeniu dokumentu aktualizuje równolegle dziesiątki powiązanych encji: numerację dokumentów, rejestry VAT, rozrachunki, zapisy księgowe, stany magazynowe, historię zmian. Pominięcie którejkolwiek = niespójna baza i błędy widoczne dopiero przy zamknięciu miesiąca.

Dodatkowo: struktura wewnętrzna Optimy jest własnością Comarch i zmienia się między wersjami bez dokumentacji — to co działa dziś, jutro może wymagać przepisania. Bezpośrednie operacje na bazie nie są objęte wsparciem technicznym Comarch i mogą skutkować utratą gwarancji.

Ograniczenia bezpośredniego SQL

Brak walidacji — omijasz reguły biznesowe wbudowane w Optimę
Ryzyko uszkodzenia danych — INSERT/UPDATE bez znajomości wewnętrznych zależności może uszkodzić bazę
Brak wsparcia Comarch — bezpośrednie operacje na bazie nie są objęte wsparciem technicznym
Utrata gwarancji — Comarch może odmówić pomocy, jeśli wykryje bezpośrednie modyfikacje bazy
Aktualizacje łamią schemat — struktura tabel zmienia się między wersjami bez dokumentacji zmian

Metoda 3: REST API (Optima API od WebArm)

Optima API — REST API do Comarch ERP Optima stworzone przez WebArm — to warstwa REST między Twoim systemem a Comarch Optimą. Zbudowana i utrzymywana przez WebArm.

Jak wygląda pobieranie danych przez REST API Comarch ERP Optima

# Pobranie listy kontrahentów
curl -X GET https://twoj-serwer/api/kontrahenci \
  -H "X-Api-Key: twoj-klucz" \
  -H "X-Optima-Firma: FIRMA-DB"

Odpowiedź REST API to JSON: identyfikator, kod kontrahenta, NIP, adres e-mail oraz dane paginacji. Pobranie listy nie wymaga sesji Windows, a wyszukiwanie po NIP lub nazwie może działać tak samo z CRM, sklepu, panelu B2B albo narzędzia raportowego.

Zalety REST API

Dowolna platforma — Linux, macOS, Docker, przeglądarka, aplikacja mobilna
Dokumentacja Swagger/OpenAPI — pełna, interaktywna dokumentacja od razu po instalacji
Walidacja reguł biznesowych — każda operacja przechodzi przez silnik walidacyjny Optimy
Bezpieczeństwo — API Key + HTTPS, bez bezpośredniego dostępu do bazy
Stabilność po aktualizacji — WebArm testuje kompatybilność z nowymi wersjami Optimy
Czas integracji — 1–3 dni zamiast miesięcy

Waga złożoności — ciężkie legacy kontra lekki nowoczesny interfejs API

Porównanie metod

Kryterium	COM objects	Bezpośredni SQL	REST API (Optima API)
Platforma	Tylko Windows	Dowolna (z dostępem do DB)	Dowolna
Dokumentacja	Brak oficjalnej	Schemat DB nieudokumentowany	Swagger/OpenAPI
Walidacja biznesowa	Tak (przez COM)	Brak	Tak
Bezpieczeństwo	Sesja Windows	Bezpośredni dostęp do bazy	API Key + HTTPS
Czas integracji	2–6 miesięcy	1–4 tygodnie	1–3 dni
Stabilność po aktualizacji	Niska	Bardzo niska	Wysoka
Wsparcie Comarch	Ograniczone	Brak	N/D (wsparcie WebArm)
Concurrency	Brak (sesyjne)	Pełna (DB-level)	Pełna (HTTP)
Format danych	Obiekty COM	SQL result sets	JSON

Przykładowe zadania integracyjne

Zadanie	COM objects	Bezpośredni SQL	REST API od WebArm
Pobieranie listy kontrahentów	działa, ale wymaga sesji Windows	szybki odczyt, read-only	`GET /api/kontrahenci` z paginacją
Wyszukiwanie po NIP, kodzie lub nazwie	wymaga osobnego filtra COM	możliwe, ale tylko na strukturze tabel	query parametry HTTP i spójny opis błędu
Dodawanie dokumentów handlowych	poprawne, ale wymaga kodu .NET	ryzykowne, bez walidacji	`POST /api/dokumenty/*` przez walidację Optimy
Faktury sprzedaży i dokument FS	złożone obiekty COM	wysokie ryzyko niespójności	REST payload + numeracja i rejestry po stronie Optimy
Korekty, płatności i numer obcy	wiele obiektów i zależności	łatwo pominąć rozrachunki lub rejestr VAT	jedna operacja z walidacją programu
E-commerce i systemy WMS	wymaga własnego middleware	tylko część odczytowa	standard HTTP/JSON dla dowolnej platformy

To dlatego pytanie “COM czy REST API” nie jest tylko preferencją technologiczną. Decyduje o tym, kto utrzymuje integrację po aktualizacji Optimy, jak szybko dodasz nowy system i czy operacje zapisu pozostają zgodne z logiką programu.

REST API, Web API i koszty utrzymania wersji

Web API, COM objects i REST API różnią się też kosztem życia integracji. Licencja jednorazowa albo pierwsze wdrożenie to zwykle mniejsza część wydatku. Większy koszt pojawia się przy aktualizacji wersji Comarch ERP Optima, zmianie pól dokumentów, dodaniu nowej funkcjonalności albo podłączeniu kolejnego systemu. REST API od WebArm ogranicza ten problem, bo stabilny protokół HTTP oddziela aplikacje klienta od mechanizmów Optimy.

Dodatkowe koszty i integracja z innymi aplikacjami

Dodatkowe koszty pojawiają się wtedy, gdy każda integracja z innymi aplikacjami wymaga osobnego kodu COM, osobnych testów wersji i osobnej obsługi błędów. REST API zmniejsza ten ciężar, bo CRM, sklep, WMS i raporty korzystają z tego samego formatu żądań.

W praktyce automatyzacja obejmuje zarządzania danymi, pobieranie towarów, aktualizacja cen, synchronizacja dokumentów i wdrożenie kolejnych funkcjonalności bez przebudowy całego systemu. To zwiększenie stabilności jest ważne szczególnie wtedy, gdy z Optimą pracuje więcej niż jedno oprogramowanie: sklep, magazyn, księgowość i panel sprzedażowy.

Jak wygląda dodawanie dokumentów i synchronizacja stanów

Największa różnica między metodami pojawia się przy zapisie, a nie przy samym pobieraniu listy. Dodawanie dokumentów handlowych oznacza zwykle utworzenie nagłówka, pozycji towarów, danych kontrahenta, płatności, numeru obcego, rejestru VAT i statusu w buforze. Do tego dochodzi tworzenie dokumentów powiązanych, na przykład faktury sprzedaży do zamówienia albo dokumentu magazynowego do wydania towarów.

Bezpośredni SQL widzi tylko tabele bazy danych, więc łatwo pominąć księgowość, korekty, rozliczanie dokumentów handlowych albo stany magazynowe. COM objects potrafią przeprowadzić zapis przez mechanizmy Optimy, ale wymagają kodu zależnego od sesji Windows. REST API od WebArm wystawia operacje przez HTTP, a walidację i aktualizację dokumentów zostawia po stronie Comarch ERP Optima. Dzięki temu eksport dokumentów, wyszukiwanie po NIP, aktualizacja cenników, synchronizacja produktów i pobranie stanów magazynowych całkowitych mogą być obsłużone jednym spójnym protokołem.

Kiedy wybrać które rozwiązanie

COM objects — gdy masz istniejącą integrację COM, która działa i nie planujesz zmian. Koszt migracji nie jest uzasadniony, jeśli wszystko jest stabilne.

Bezpośredni SQL — nigdy jako rozwiązanie docelowe. Dopuszczalne jedynie do jednorazowych eksportów danych w trybie read-only, z pełną świadomością ryzyka.

REST API (Optima API) — nowe integracje, e-commerce, aplikacje mobilne, agenty AI, lub gdy obecna integracja COM sprawia problemy po każdej aktualizacji Optimy. Krok po kroku jak wygląda taka integracja opisujemy w przewodniku po integracji sklepu z Comarch Optima.

FAQ

Czy REST API zastępuje COM objects całkowicie? Dla klienta integrującego systemy tak, bo pracuje na HTTP/JSON. W środku zapisy nadal mogą przechodzić przez COM, żeby zachować walidację biznesową Optimy.

Czy bezpośredni SQL jest zawsze zły? Do kontrolowanych odczytów read-only bywa użyteczny. Do zapisów dokumentów, kontrahentów, płatności i stanów magazynowych nie powinien być rozwiązaniem docelowym.

Czy Web API Comarch Optima to to samo co REST API? Nie. Web API Comarch opiera się na innym modelu integracji i nie daje prostego, publicznego kontraktu REST/JSON dla wszystkich scenariuszy, których potrzebują sklepy i aplikacje webowe.

Podsumowanie

Brak oficjalnego REST API od Comarch to realny problem dla firm integrujących swoje systemy z Optimą. COM objects działają, ale są kruche, wolne w implementacji i przywiązane do Windows. Bezpośredni SQL to ryzyko, którego nie warto podejmować.

Optima API od WebArm eliminuje te problemy — standardowe REST API z dokumentacją, walidacją i wsparciem aktualizacji. Integracja, która zajmowała miesiące, trwa dni.

Masz pytania o integrację z Comarch Optima? Sprawdź odpowiedzi na najczęstsze pytania lub skontaktuj się z nami.