Najczęściej zadawane pytania

Comarch nie udostępnia publicznego REST API do systemu Comarch ERP Optima. Oficjalne mechanizmy integracji to obiekty COM (wymagają Windows i .NET), Comarch ERP Optima webapi (SOAP/XML — nie REST, wymaga dodatkowej licencji) oraz bezpośredni dostęp do bazy SQL (ryzykowny, nieobsługiwany). Optima API od WebArm to pełne REST API (HTTP/JSON) obejmujące pobieranie, dodawanie, aktualizację i wyszukiwanie danych — kontrahentów, towarów, dokumentów handlowych, faktur i dokumentów magazynowych. Umożliwia integrację dowolnego systemu z programem Comarch ERP Optima przez standardowe zapytania HTTP — także przenoszenia pomiędzy aplikacją zewnętrzną a systemem Comarch ERP Optima i pełną automatyzację procesów biznesowych. Więcej o przyczynach braku API →

Obiekty COM to natywny interfejs programu Comarch ERP Optima — wymaga Windows, zainstalowanej Optimy na maszynie, środowiska .NET i znajomości nieudokumentowanych wewnętrznych struktur. Sesje są jednowątkowe i sesyjne, co ogranicza wydajność. Optima API stosuje architekturę dwuwarstwową: pobieranie (GET) wykonywane jest bezpośrednio na bazie SQL, co zapewnia maksymalną szybkość przy pobraniu listy kontrahentów, towarów czy dokumentów, natomiast zapisy (POST/PUT/DELETE) — dodawanie, aktualizacja, modyfikację dokumentów — przechodzą przez obiekty COM z pełną walidacją biznesową Comarch. Operacje COM obsługuje dedykowany wątek STA z kolejką, eliminując konflikty współbieżności. Wysyłasz żądanie HTTP z dowolnego systemu (Linux, Mac, kontener Docker), a Optima API wykonuje operację po stronie serwera. Rozwiązanie oferuje prostotę obsługi i automatyzację integracji dzięki mechanizmów udostępnianych przez REST — bez konieczności uczenia się wewnętrznych API Optimy. Porównanie COM vs REST z przykładami kodu →

Tak. Optima API działa z Twoją istniejącą instalacją Comarch ERP Optima — potrzebujesz aktywnej licencji Comarch na moduły, z których chcesz korzystać. Optima API to dodatkowa warstwa dostępu do danych, nie zamiennik licencji Comarch.

Samo uruchomienie Optima API na serwerze z Optimą trwa do 30 minut. Jedyny dodatkowy krok wdrożeniowy to konfiguracja VPN, jeśli API ma być dostępne z zewnątrz. Po uruchomieniu Twój zespół od razu widzi Swagger UI z pełną dokumentacją OpenAPI i może wysyłać pierwsze zapytania — pobieranie listy kontrahentów, towarów, dokumentów handlowych czy faktury. Dostępne są operacje batch do 100 rekordów w jednym żądaniu, co przyspiesza masowy import danych i automatyzację procesów. Czas właściwej integracji zależy od zakresu — proste pobranie danych to kwestia godzin, pełna automatyzacja procesów biznesowych wymaga więcej pracy. Kluczowe jest to, że z REST API łatwo zintegrować własne rozwiązania oraz własne wdrożone pogramy z programem Comarch ERP Optima — wielokrotnie szybciej niż budowanie oprogramowaniem zewnętrznym od zera na obiektach COM. Praktyczny przewodnik po integracji sklepu →

Model opiera się na jednorazowej licencji + miesięcznej opłacie za utrzymanie. Licencja obejmuje instalację, konfigurację i szkolenie wstępne. Opłata miesięczna pokrywa aktualizacje kompatybilności z nowymi wersjami Optimy, wsparcie techniczne i monitoring. Szczegółowe ceny znajdziesz w cenniku na stronie głównej.

Optima API to samodzielna aplikacja .NET z architekturą dwuwarstwową i 976 endpointami pokrywającymi 201 serwisów w 131 kategoriach Swagger. Krótki opis: operacje odczytu (GET i batch read) trafiają bezpośrednio do bazy SQL — dzięki temu są szybkie i nie obciążają sesji obiektów COM. Operacje zapisu (POST, PUT, DELETE) przechodzą przez obiekty COM programu Comarch ERP Optima, zachowując pełną walidację biznesową: VAT, split payment, numeracja, reguły cenowe. Operacje obsługuje dedykowany wątek STA z kolejką o pojemności 64 operacji, eliminując konflikty współbieżności. Dokumentacja w formacie OpenAPI/Swagger jest dostępna od razu po instalacji i zawiera pełny opis każdego endpointu. Porównanie architektur COM vs REST →

API pokrywa 100% modułów programu Comarch ERP Optima: Moduł Dostępowy (Kasa/Bank), Faktury, Handel z Magazynem (kontrahenci, towary z atrybutami i cennikami, stany magazynowe, dokumenty handlowe i dokumenty magazynowe), Detal, Rejestr VAT, Księga Podatkowa, Księga Handlowa, Środki Trwałe, Kadry i Płace, CRM. Łącznie 976 endpointów, 201 serwisów i 131 grup Swagger. Dostępne są operacje batch do 100 rekordów w jednym żądaniu, 25 endpointów batch oraz 9 dedykowanych endpointów synchronizacji z cursor-based polling dla stanów magazynowych i kontrahentów.

Optima API obsługuje pełny zestaw dokumentów handlowych programu Comarch ERP Optima: faktury sprzedaży (dokument FS), faktury zakupu, paragony, dokument PA, dokumenty magazynowe (WZ, PZ, MM, RW, PW), dokumenty księgowe (w tym rejestr VAT), dokument RO (rezerwacje) oraz ich dokumenty powiązane. Metody API odpowiadają poszczególnym rodzajom dokumentów: dodawanie, modyfikację dokumentów, aktualizacja, wyszukiwanie po numerze lub dacie, pobranie listy, eksport dokumentów oraz tworzenie dokumentów powiązanych (np. FS z RO). Każda operacja uwzględnia walidację Comarch: VAT, split payment, numer obcy, jednostka miary pozycji, data kursu waluty, numeracja i serie dokumentów. Dzięki temu API zastępuje ręczne wprowadzanie i oferuje automatyzację integracji dokumentów między aplikacją zewnętrzną a systemem Comarch ERP Optima.

API udostępnia krótki opis metod odpowiadających poszczególnym rodzajom danych. Pobieranie listy kontrahentów i pobieranie listy towarów obsługuje paginowanie i filtry (kod, nazwa, NIP, grupa, data modyfikacji). Pobranie pojedynczych danych kontrahenta lub towaru zwraca komplet pól: adresy, warunki płatności, ceny indywidualne, atrybuty, jednostki miary, cenniki. Wyszukiwanie kontrahenta działa po dowolnym polu publicznym — NIP, nazwa, kod, adres e-mail. Dodawanie kontrahentów, dodawanie towarów i dodawanie dokumentów przechodzą przez walidację biznesową Comarch, a aktualizacja pozwala modyfikować dane bez ryzyka konfliktów — blokada sesji zapewnia spójność. Przykład WZ: pobierasz dane kontrahenta (identyfikator kontrahenta), tworzysz dokument i dodajesz pozycje z dynamicznymi cenami z cennika. Pełny opis i dokumentacja Swagger opisuje każdą metodę z przykładami dla każdego rodzaju kontrahenta (odbiorca, dostawca, obaj).

Tak. API obejmuje moduły kadrowo płacowych i księgowych programu Comarch ERP Optima. W module Kadry i Płace dostępne jest pobieranie informacji kadrowych o pracownikach, limitach urlopowych pracownika, nieobecnościach pracownika, szkoleniach pracownika oraz listach szkoleń pracownika, dodawanie i aktualizacja danych kadrowych oraz list płac. W module księgowości API umożliwia obsługę zapisów księgowych, rejestru VAT, księgi podatkowej i księgi handlowej — dodawanie, pobieranie, wyszukiwanie i eksport dokumentów księgowych. Osobne endpointy zarządzają środkami trwałymi: ewidencja, amortyzacja, likwidacja. Dzięki jednemu REST API zarządzanie księgowością i kadrami w integracjach przebiega tak samo jak w modułach handlowych — bez konieczności korzystania z różnych interfejsów.

Oficjalne Web API Comarch — Comarch ERP Optima webapi — to rozwiązanie działające jako usługą sieciową na serwerem webapi, wykorzystujące protokole SOAP, protokół RPC oraz oprogramowanie sieciowe i format tworzenia komunikatów XML (usługa wykorzystująca xml). Web API przeznaczone jest głównie dla integracji biznesowych z programem erp jakim jest Comarch, wymaga dodatkowej licencji i pokrywa wybrane moduły. Optima API od WebArm to nowoczesne REST API (HTTP/JSON) zamiast Web API SOAP — prostsze w integracji, obsługuje dowolny język programowania bez generatorów stubów, pokrywa 100% modułów programu Comarch ERP Optima i oferuje pobieranie, dodawanie dokumentów oraz aktualizację danych przez standardowe zapytania HTTP. To oprogramowanie przeznaczone dla wszystkich zainteresowanych budowaniem rozwiązań korzystających z danych Comarch Optima bez narzutu SOAP. Web API SOAP nadal ma zastosowania — jeśli Twój system już korzysta z klientów SOAP, webapi przeznaczone jest jako pomost; dla nowych integracji rekomendujemy REST. Na życzenie dopasowujemy webapi oraz REST do indywidualnych potrzeb konkretnego przedsiębiorstwa, zapewniając inne ułatwienia (ułatwienia pracy) dla zespołów developerskich.

API udostępnia 976 endpointów REST pokrywających 201 serwisów w 131 kategoriach Swagger. Podział metod HTTP: 247 GET (pobieranie, pobranie listy, wyszukiwanie), 384 POST (dodawanie, dodanie, tworzenie dokumentów handlowych, batch read), 177 PUT (aktualizacja, modyfikację dokumentów) oraz 168 DELETE (usuwanie). Obsługiwane moduły Comarch ERP Optima: Moduł Dostępowy (Kasa/Bank), Faktury, Handel z Magazynem, Detal, Rejestr VAT, Księga Podatkowa, Księga Handlowa, Środki Trwałe, Kadry i Płace, CRM. Dodatkowo 9 endpointów synchronizacji z cursor-based polling (stanów magazynowych całkowitych, kontrahentów, cenników) i 25 endpointów batch.

Sama instalacja Optima API wymaga serwera Windows z zainstalowaną Comarch Optimą — to wymaganie Comarch, nie nasze. Natomiast systemy komunikujące się z API mogą działać na dowolnej platformie — Linux, macOS, kontenery Docker. To standardowe REST API dostępne przez HTTP/HTTPS.

Optima API ma trzy warstwy ochrony przed awariami COM. ComHangWatchdog monitoruje czas wykonania każdej operacji — jeśli przekroczy 180 sekund, automatycznie restartuje proces COM i przyjmuje kolejne żądania. MemoryGuard śledzi zużycie pamięci: po przekroczeniu progu 1200 MB odrzuca nowe żądania z kodem 429 i uruchamia auto-recovery po 120 sekundach. OverloadShield zapewnia rate limiting z circuit breakerem — po 8 odrzuconych żądaniach blokuje klienta na 120 sekund, zapobiegając kaskadowym przeciążeniom. Te mechanizmy działają równolegle, zapewniając stabilność API nawet przy problematycznych operacjach Comarch.

Optima API wykorzystuje dwa nagłówki HTTP: X-Api-Key (autoryzacja) oraz X-Optima-Firma (wymagany identyfikator bazy danych firmy — nazwa firmy lub Baz_BazID). Weryfikacja klucza odbywa się w czasie stałym (ochrona przed timing attacks). Rate limiting ogranicza liczbę żądań — domyślnie 100 na minutę, a operacje synchroniczne (np. zapis COM) 1 na minutę z kolejką do 50 oczekujących. OverloadShield automatycznie blokuje klienta po 8 odrzuconych żądaniach na 120 sekund. Komunikacja wymaga HTTPS. Prostota API Key + Firma eliminuje złożoność OAuth przy jednoczesnym zachowaniu bezpieczeństwa w środowiskach serwerowych.

Tak. Nagłówek X-Optima-Firma jest wymagany przy każdym żądaniu — wskazuje bazę danych firmy (nazwa firmy lub Baz_BazID). Dzięki temu jeden serwer z Optima API obsługuje wiele baz Comarch Optimy. Każda firma otrzymuje osobną sesję COM zarządzaną przez LRU cache, co zapewnia izolację operacji między firmami.

VerSync to silnik synchronizacji, który łączy Twój system (sklep internetowy, ERP, CRM) z Comarch ERP Optima. Obsługuje connectory REST API oraz MariaDB/MySQL jako źródła i cele danych. Definiujesz pipeline w konfiguracji YAML: źródło danych, cel, mapowanie pól z transformacjami oraz match key do identyfikacji rekordów. Konflikty rozwiązywane są strategią Last-Write-Wins z konfigurowalnym priorytetem źródeł. VerSync obsługuje resztę — walidację danych, obsługę błędów i automatyczne ponawianie.

VerSync oferuje cztery tryby pracy. Init — jednorazowe uzgodnienie stanu, porównuje oba systemy i wyrównuje różnice. Watch — ciągłe monitorowanie zmian z konfigurowalnym interwałem odpytywania. Rollback — cofnięcie zmian z wybranego przedziału czasowego. Flaga --follow łączy tryby: wykonuje init, a następnie automatycznie przechodzi w watch. Każdy tryb można uruchomić z --dry-run (podgląd zmian bez zapisu) lub --record (test na pojedynczym rekordzie).

W konfiguracji VerSync definiujesz pipeline typu Watch na module stanów magazynowych. VerSync monitoruje zmiany z cursor-based polling — zapamiętuje pozycję ostatniego odczytu i pobiera tylko nowe zmiany. Interwał odpytywania jest konfigurowalny — od co minutę do raz dziennie, zależnie od potrzeb biznesowych. Batch processing z cooldown między partiami zapobiega przeciążeniu systemów źródłowych i docelowych. Szczegółowy przewodnik po synchronizacji stanów →

VerSync ma system outbox z gwarantowaną dostawą — każda operacja trafia do kolejki i nie zostanie utracona nawet przy awarii. Retry z exponential backoff automatycznie ponawia nieudane operacje — konfigurowalny bazowy interwał, mnożnik i maksymalna liczba prób. Operacje, które wyczerpią limity prób, trafiają do dead-letter queue (DLQ) — nie blokują pozostałych. Admin API udostępnia endpoint /dlq z możliwością ponownego wykonania (replay). W planie Full dostępne metryki Prometheus i dashboard Grafana z historią synchronizacji i alertami w czasie rzeczywistym.

Tak — w planie Full. VerSync loguje każdą operację w apply journal ze stanem przed i po każdej zmianie. Rollback można wykonać na konkretny przedział czasowy — cofasz dokładnie te zmiany, które chcesz. Przed wykonaniem dostępny jest tryb dry-run: Admin API endpoint /rollback/plan generuje raport planowanych cofnięć bez ich realizacji. Dopiero po akceptacji planu wykonujesz właściwy rollback.

Każdy system, który udostępnia REST API lub dostęp do bazy danych, może być źródłem lub celem synchronizacji — sklepy internetowe, marketplace'y, systemy ERP, CRM, aplikacje wewnętrzne, hurtownie danych. VerSync nie ogranicza się do konkretnych platform. Konfiguracja odbywa się przez pipeline YAML, w którym definiujesz źródło, cel i mapowanie pól. Przykład integracji sklepu krok po kroku →

Tak. VerSync ma dwa tryby testowe dostępne we wszystkich operacjach (init, watch, rollback). Flaga --dry-run generuje pełny raport zmian — co zostanie dodane, zmodyfikowane, usunięte — bez zapisu jakichkolwiek danych. Flaga --record pozwala przetestować synchronizację na jednym konkretnym rekordzie (identyfikowanym po match key), co jest przydatne przy debugowaniu mapowania pól. Oba tryby można łączyć, np. --dry-run --record wyświetli co stałoby się z konkretnym rekordem bez wykonywania zmian.