Comarch Optima API: przewodnik programisty po integracji

Dlaczego to piszę

Najczęściej czytaną stroną na tym blogu jest przewodnik programisty po enova365 WebAPI. Mniej więcej raz w miesiącu ktoś pyta mnie o odpowiednik dla Optimy i moja odpowiedź go rozczarowuje: to zależy, co dokładnie masz na myśli, mówiąc "API".

Optima jest najpowszechniej zainstalowanym ERP w polskich małych i średnich firmach. I jednocześnie tym, przy którym pytanie "czy ma API?" ma najmniej użyteczną odpowiedź — a nie dlatego, że odpowiedź brzmi "nie".

Tę nazwę nosi pięć różnych rzeczy. Różni właściciele, różne licencje, różne tryby awarii i różni ludzie odbierający telefon, kiedy któraś z nich przestaje działać o drugiej w nocy.

To jest programistyczne uzupełnienie mojego wcześniejszego tekstu o integracji Optimy z portalem B2B, który opisuje architekturę: zadania synchronizacyjne, ceny, przepływ zamówień. Ten schodzi bliżej metalu.

"API Optimy" to nie jedna rzecz. To pięć

Uporządkuj to, zanim zapadnie jakakolwiek decyzja techniczna. Większość sporów na pierwszym spotkaniu bierze się stąd, że dwie osoby używają jednego zwrotu na dwa różne produkty:

1. CDN.API — własny model obiektowy COM Comarchu. To właśnie ma na myśli Comarch, mówiąc "API".
2. Comarch ERP Web API — usługa REST, którą Comarch dostarcza i którą włącza się w konfiguracji.
3. Praca Rozproszona — wymiana plików XML, zbudowana do rozdzielenia sprzedaży od księgowości.
4. Bezpośredni odczyt z SQL — w ogóle nie jest API, a używa się go jak API bez przerwy.
5. "Web API do Optimy" firm trzecich — komercyjne dodatki resellerów, sprzedawane jako produkty.

Pierwsze pytanie w projekcie z Optimą nie brzmi więc, jak się autoryzować. Brzmi: która z tych pięciu rzeczy jest na tej instalacji, kto jest jej właścicielem i kto ją wspiera, gdy się wywróci. Widziałem, jak dwutygodniowa wycena zamieniła się w dwa miesiące, bo to pytanie padło w trzecim tygodniu.

CDN.API: co Comarch ma na myśli, mówiąc "API"

CDN.API to model obiektowy COM. Podpinasz bibliotekę, logujesz się, wykonujesz operacje, wylogowujesz — model sesyjny, blisko własnej logiki ERP. Przez niego zakładasz i aktualizujesz kontrahentów, towary, adresy, definicje atrybutów i ich wartości, płatności, dokumenty handlowe, dokumenty magazynowe oraz rezerwacje odbiorcy.

Trzy konsekwencje, które przesądzają o architekturze pierwszego dnia:

Działa na Windows, w procesie, obok zainstalowanej Optimy. Nie wywołasz tego z kontenera stojącego gdzie indziej. Standardowy kształt to cienka usługa HTTP na tym hoście, z którą rozmawia właściwa aplikacja. To nie obejście, tylko właściwy projekt: ta usługa staje się jedynym elementem przywiązanym do wersji Optimy, a całą resztę wdrażasz bez dotykania serwera ERP.

Loguje się jako operator, więc zajmuje stanowisko. Integracja odpytująca co pięć minut jest z punktu widzenia licencji użytkownikiem. Zapytaj, ile licencji modułowych ma instalacja, zanim zaprojektujesz pętlę odpytywania.

Stosuje logikę biznesową Optimy i to jest cały powód, dla którego używa się jej zamiast SQL. Numeracja dokumentów, ruchy magazynowe, semantyka rezerwacji — wszystko dzieje się tak, jak dzieje się przy kliknięciu przez człowieka.

Comarch ERP Web API: istnieje, jest dostarczane, dokumentacja za ścianą partnerską

Comarch faktycznie dostarcza usługę REST. Włącza się ją w Konfiguracja → Stanowisko → Wymiana danych → Comarch ERP Web API, ustawia port (domyślnie 8080) i adres serwera, po czym restartuje usługę Windows. Ten ostatni krok nie jest opcjonalny i jest najczęstszą przyczyną błędu 401, który pojawia się chwilę po tym, jak ktoś zaklina się, że skonfigurował wszystko poprawnie.

Dwa zastrzeżenia i oba zmieniają plan. Zakres tej usługi wyrósł wokół ekosystemu samego Comarchu — e-Sklep, Mobile, BPM — więc pokrywa to, czego potrzebowały tamte produkty, co może, ale nie musi pokrywać się z Twoimi potrzebami. A pełna dokumentacja techniczna trafia do Partnerów Comarch, nie do otwartego internetu.

Razem daje to konkretne ryzyko projektowe. Zdanie "Optima ma Web API" jest prawdziwe i nie mówi prawie nic. Poproś partnera o specyfikację endpointów dla wersji zainstalowanej u klienta i przeczytaj ją, zanim podasz komukolwiek termin. To odpowiednik weryfikacji licencji, którą postawiłem na początku przewodnika po enova365 WebAPI: pytanie kosztuje jednego maila i regularnie oszczędza tydzień.

Praca Rozproszona: niedoceniana, czasem właściwa odpowiedź

Praca Rozproszona to wymiana plików — dane słownikowe i dokumenty wędrują między częścią sprzedażową a księgową jako XML, od wersji 2017.5.1 pakowane do .zip, oznaczone identyfikatorem księgowości, który domyślnie ma wartość K1 i u klienta bardzo często K1 nie jest. Powstała do offline'owego rozdzielenia działów, nie do integracji, i programiści odrzucają ją dokładnie z tego powodu.

I często się mylą. Wszystko idzie przez własną logikę importu Optimy, więc nie jesteś przywiązany do żadnego schematu. Znosi aktualizacje wersji lepiej niż cokolwiek innego na tej liście. A kiedy zawodzi, zawodzi widocznie: plik, który się nie zaimportował, leży w katalogu.

Przestaje być dobrą odpowiedzią w momencie, w którym musisz coś sprawdzić w czasie rzeczywistym, bo nie ma tu żadnej powierzchni zapytań — jest tylko to, co ktoś wyeksportował. I wnosi ten tryb awarii, który opisałem przy Harmonogramie Zadań: katalog, którego nikt nie pilnuje, gdzie zadanie, które przestało działać, i zadanie, które nie miało czego wysłać, zostawiają identyczny ślad, czyli żaden.

Baza SQL: czytaj śmiało, nie zapisuj nigdy

Odczyt z bazy SQL Optimy jest powszechny, działa, a do raportowania jest zwykle rozsądnym wyborem. Zapis nie jest kompromisem, tylko błędem: omija logikę biznesową, psuje dane w sposób, który ujawnia się miesiącami później, i wyprowadza Cię poza wsparcie Comarchu. Schemat nie jest dokumentowany do użytku zewnętrznego i zmienia się między wersjami.

Jest jeszcze druga konsekwencja i umyka, bo nie jest problemem danych. Połączenie SQL nie wie, że model uprawnień ERP w ogóle istnieje. Prawa operatora, granice modułów, ograniczenia na poziomie rekordów — nic z tego nie obowiązuje. To ta sama pułapka, którą opisałem przy kontach serwisowych w enova365: "tylko do odczytu" na bazie to znacznie szersze uprawnienie niż "tylko do odczytu" w ERP, a nazywa się to tak samo, na tym samym spotkaniu.

"Web API do Optimy" od firm trzecich: co właściwie kupujesz

Rynek komercyjnych API doklejanych do Optimy istnieje naprawdę i istnieje dlatego, że opisana wyżej luka jest prawdziwa. Dwa przykłady, oba łatwe do znalezienia: Lagarta sprzedaje pakiety Web API do Optimy w widełkach mniej więcej 5 800–8 800 zł netto, zależnie od zakresu i od tego, czy licencja obejmuje jedną firmę, czy biuro rachunkowe z kilkoma; WebArm ERP API działa jako lokalna usługa HTTP wystawiająca encje Optimy w JSON, z dokumentacją Swagger, i deklaruje około 1 100 endpointów.

To normalne produkty i kupienie takiego bywa tańsze niż zbudowanie warstwy pośredniej samemu. Trzy pytania, zanim to zrobisz:

• Czyj to schemat? Mapując się na API firmy trzeciej, wiążesz integrację z tym dostawcą, a nie z Comarchem. To realna zależność z realną ceną odnowienia.
• Co się dzieje przy kolejnej wersji Optimy? Comarch wydaje ich kilka rocznie. Zapytaj o ich tempo aktualizacji i o to, jak szybko dostarczyli zgodność dla dwóch ostatnich wersji.
• Gdzie to działa? Większość i tak musi stać na hoście Optimy albo obok niego. Jeśli Twoja architektura zakładała wywołanie z chmury, sprawdź to przed podpisaniem.

Różnią się też protokoły — część to SOAP po XML, część nowoczesny JSON. Kiedy dostawca mówi "Optima ma Web API", użyteczne pytanie uzupełniające brzmi: czyje?

Jak to rozstrzygnąć na jednym spotkaniu

• Odczyt i zapis w czasie rzeczywistym, kod po Twojej stronie → CDN.API za własną usługą HTTP.
• Odczyt i zapis w czasie rzeczywistym, wolisz kupić niż budować → API firmy trzeciej, z trzema pytaniami wyżej odpowiedzianymi na piśmie.
• Po drugiej stronie stoi produkt Comarchu → Comarch ERP Web API, najpierw specyfikacja w ręku.
• Cykliczny przepływ dokumentów do księgowości → Praca Rozproszona, z pulsem na katalogu.
• Raportowanie i analityka → SQL, tylko do odczytu.
• Zapis do tabel SQL → nigdy. Nie ma wersji tej historii, która kończy się dobrze.

Gdzie integracje z Optimą naprawdę się sypią

Mniej więcej w kolejności, w jakiej to spotykam:

Aktualizacje wersji. Kilka wydań rocznie, a zmienić może się zarówno schemat, jak i powierzchnia obiektowa. Trzymaj bazę testową na docelowej wersji i waliduj, zanim klient zaktualizuje produkcję, nie po.

Host Windows, którego nikt nie wycenił. CDN.API go potrzebuje. Pojawia się w drugim tygodniu projektu wycenionego w tygodniu zerowym.

Stanowisko licencyjne. Odkrywane na koniec miesiąca, przez osobę, która nie mogła się zalogować.

Semantyka rezerwacji. Rezerwacja odbiorcy to realny dokument, który blokuje towar. Integracja, która usłużnie zakłada po jednej na każdy koszyk, sprawi, że stany magazynowe zaczną znikać — i przez trzy dni będzie to wyglądało na problem magazynu.

Numeracja dokumentów. Niech nadaje ją Optima. Za każdym razem. Ta sama reguła co w każdym innym polskim ERP, łamana z tego samego kuszącego powodu: przecież już wiesz, jaki ten numer ma być.

Dokąd to prowadzi

Wszystko powyżej to hydraulika, a hydraulika jest nudniejszą połową roboty. Ciekawsza połowa to, co przez nią przepuszczasz: proces, który czyta dokumenty z Optimy, sprawdza je z czymś spoza ERP i kładzie człowiekowi przed oczami gotowy szkic do zatwierdzenia, zamiast prosić go o przepisanie tego ręcznie.

Jeśli szacujesz integrację z Optimą i chcesz, żeby ktoś, kto już trafił na te tryby awarii, spojrzał na konkretną instalację, zanim zobowiążesz się do terminu — odezwij się. Ten sam fundament napędza agenty AI dla firm, które buduję, i integracje z ERP: najpierw odczyt, zapis później, a każde zatwierdzenie zostaje przy człowieku.