enova365 WebAPI: przewodnik programisty po REST API Sonety

Dlaczego to piszę

Większość treści o "integracji z enova365" w sieci to strona marketingowa przebrana za tutorial. Ta nie jest. Prowadzę produkcyjnego agenta, który zapisuje szkice zamówień hurtowych do enova365 przez Soneta WebAPI — działa od miesięcy, ma własną kolejkę wyjątków, a ja osobiście trafiłem na każdy z opisanych niżej trybów awarii przynajmniej raz. To przewodnik, który chciałbym mieć, zanim zacząłem go budować: czym naprawdę jest WebAPI, ile kosztuje, jak realnie działa autoryzacja, jak odpytujesz i zapisujesz dane, i gdzie w praktyce się to sypie.

Jeśli czytałeś już opis integracji portalu B2B z enova365, potraktuj ten artykuł jako uzupełnienie na poziomie programisty. Tamten pokrywa architekturę — zadania synchronizacyjne, ceny, przepływ zamówień. Ten jest bliżej metalu: moduł, uścisk dłoni autoryzacji, model kontrolerów i konkretne błędy, które kosztują ludzi tydzień.

Najpierw licencja: WebAPI to płatny moduł, nie coś oczywistego

Potwierdź to, zanim otworzysz IDE. Soneta WebAPI to osobny płatny moduł na bazowej enova365 — nie jest wliczony, nie jest aktywny automatycznie tylko dlatego, że klient ma enova365. Dostępny jako dodatek wieczysty albo subskrypcja miesięczna, aktywowany przez resellera na konkretnej licencji.

Zadzwoń i zapytaj wprost: czy moduł WebAPI jest aktywny na tej licencji i jaki build enova365 jest zainstalowany. Wersja ma znaczenie, bo zachowanie kontrolerów dynamicznych naprawdę zmieniało się między głównymi wydaniami — zapytanie, które działa na jednej instalacji, może zachować się inaczej na tej, która jest rok czy dwa w tyle. "Mamy enova365" to nie odpowiedź, wokół której da się zbudować harmonogram projektu. "Mamy enova365 2026.1 z aktywnym WebAPI" — już tak.

Jeśli moduł nie jest aktywny, dokup go przed startem developmentu. Prawie zawsze wychodzi taniej w skali roku niż budowa i utrzymanie obejścia opartego na eksporcie plikowym — a alternatywa dla WebAPI to bezpośredni dostęp do MS SQL, który omija logikę biznesową enova365 i tworzy własną klasę problemów (więcej o tym niżej, w sekcji o buforze).

REST kontra stary serwer WebWCF (SOAP)

WebAPI występuje w dwóch wariantach serwera, i przy nowej pracy nie jest to tak naprawdę wybór.

WebAPI Server (REST) to obecny standard — JSON po HTTP/HTTPS, aktywnie rozwijany, udokumentowany wygenerowanym interfejsem Swagger, dzięki któremu widzisz dokładnie, jakie kontrolery i metody istnieją na Twojej konkretnej instalacji, zanim wyślesz pierwsze żądanie. Tego powinna używać każda nowa integracja.

WebWCF Server (SOAP) to wariant legacy, utrzymywany wyłącznie dla wstecznej kompatybilności ze starymi integracjami, sprzed czasów, gdy REST stał się domyślny. Jeśli przejmujesz taką integrację — portal albo narzędzie księgowe zbudowane przez kogoś na WebWCF pięć lat temu — migracja do REST jest warta zaplanowania, ale to nie pożar. Jeśli zaczynasz integrację od zera w 2026 roku i ktoś sugeruje WebWCF, to decyzja z przyzwyczajenia, nie z konieczności. Nie idź w tę stronę.

Kontrolery dynamiczne kontra statyczne

Tu WebAPI enova365 zasługuje na opinię najbardziej przyjaznego dla programisty spośród polskich ERP-ów.

Kontrolery dynamiczne są generowane automatycznie z modelu danych enova365. Soneta mapuje większość standardowych obiektów — produkty, kontrahentów, dokumenty, magazyny — na endpointy REST bez jednej linii kodu po stronie enova. Dla zdecydowanej większości przypadków — odczyt katalogu produktów, pobranie kontrahentów, utworzenie zamówienia sprzedaży albo faktury zakupu — kontrolery dynamiczne to jedyne, czego dotkniesz. Wygenerowana dokumentacja Swagger na Twoim konkretnym serwerze WebAPI jest faktycznym źródłem prawdy o tym, co jest dostępne — odzwierciedla dokładną konfigurację Twojej instalacji, łącznie z dodatkami.

Kontrolery statyczne to niestandardowy kod osadzony bezpośrednio w serwerze WebAPI, pisany wtedy, gdy kontrolery dynamiczne nie pokrywają potrzeby — wieloetapowy proces biznesowy, kalkulacja, która musi działać po stronie enova, kształt danych niepasujący czysto do standardowego obiektu. Napisanie takiego kontrolera oznacza, że ktoś z doświadczeniem w .NET i SDK enova365 buduje i wdraża go jako część samego serwera WebAPI — to cięższe zadanie niż wywołanie istniejącego endpointu. Przy standardowej integracji odczyt/zapis — a to obejmuje większość przypadków automatyzacji księgowości — rzadko będziesz tego potrzebować. Jeśli w pierwszym tygodniu projektu sięgasz po kontroler statyczny, warto zapytać, czy model dynamiczny faktycznie nie pokrywa Twojego przypadku, tylko jeszcze nie znalazłeś właściwego endpointu.

Autoryzacja: jak naprawdę działa przepływ JWT

WebAPI autoryzuje przez JWT, a przepływ jest bliski standardowemu OAuth — nie potrzebujesz do tego żadnej specjalnej biblioteki:

1. Twoja integracja wysyła dane uwierzytelniające (użytkownik integracyjny, nie login człowieka-operatora) do endpointu autoryzacji WebAPI.
2. enova365 waliduje je i zwraca podpisany token JWT.
3. Każde kolejne żądanie niesie ten token w nagłówku.
4. Token wygasa po skonfigurowanym czasie życia; Twoja integracja odświeża go, zanim to nastąpi, nie po fakcie.

Kształt żądania i odpowiedzi jest prosty — mniej więcej taki:

POST /token
{
  "login": "integration_user",
  "password": "***",
  "database": "TWOJAFIRMA"
}

Dokładne nazwy pól i ścieżka endpointu różnią się wersja od wersji i to je pokazuje Swagger na Twoim konkretnym serwerze — nie ufaj fragmentowi kodu z bloga (włącznie z tym) bardziej niż dokumentacji własnej instalacji. Architektonicznie liczy się coś innego: zbuduj jeden wrapper klienta HTTP, który trzyma token, odświeża go proaktywnie na timerze działającym wyraźnie wewnątrz czasu życia tokena i wstrzykuje go do każdego wychodzącego żądania. Nigdy nie pozwól, żeby pojedyncze żądanie odkryło wygaśnięcie tokena i po prostu się nie udało — tak wygląda zadanie wsadowe, które po cichu umiera w środku nocy w połowie przebiegu.

Nigdy nie umieszczaj poświadczeń enova365 w kodzie frontendowym ani klienckim. Autoryzuje się backend Twojej integracji; nic poniżej niego nie powinno nigdy widzieć surowych poświadczeń — tylko token, który backend udostępnia wewnętrznie.

Odpytywanie danych: filtry i stronicowanie bez odkrywania SQL na nowo

Kontrolery dynamiczne przyjmują standardowe parametry zapytań w stylu REST do filtrowania, sortowania i stronicowania — nie piszesz SQL-a wobec bazy enova365, przekazujesz parametry i to kontroler filtruje po stronie serwera. Dokładne nazwy parametrów są specyficzne dla wersji i udokumentowane w Twoim Swaggerze, ale wzorzec przy każdej instalacji, z którą pracowałem, jest spójny: filtruj po wartości pola, sortuj po wybranym polu, żądaj rozmiaru strony i numeru strony zamiast pobierać wszystko naraz.

Korzystaj z tego. Przy katalogu 10 000 SKU, pobieranie pełnego zbioru przy każdym uruchomieniu synchronizacji zamiast pytania tylko o rekordy zmienione od ostatniego udanego przebiegu, to nie drobna optymalizacja — to różnica między synchronizacją kończącą się w kilka sekund a taką, która za każdym razem obciąża łącze do granic. Większość kontrolerów dynamicznych eksponuje filtr w stylu "zmodyfikowane od" właśnie z tego powodu; używaj go jako domyślnego podejścia, nie dodatku na później.

To samo dotyczy danych zagnieżdżonych — pozycje dokumentu są zazwyczaj dostępne przez powiązany endpoint, a nie osadzone w całości w każdej odpowiedzi rekordu nadrzędnego. Nie zakładaj, że dostaniesz wszystko w jednym wywołaniu — sprawdź, co faktycznie zwraca konkretny kontroler, zanim zaprojektujesz wokół tego model danych.

Zapis dokumentów w buforze, nie od razu finalnie

Ta sekcja jest warta przeczytania dwa razy, jeśli budujesz cokolwiek, co zapisuje dokumenty księgowe lub sprzedażowe do enova365.

Dokumenty w enova365 mają status odrębny od "jeszcze nie istnieje" i "w pełni przetworzone" — status bufora, ten sam stan, który człowiek przełącza ręcznie wewnątrz aplikacji desktopowej (istnieje dedykowana funkcja cofania zatwierdzonego dokumentu z powrotem do bufora, podpięta pod skrót Shift+F11, dokładnie z tego powodu: enova365 zostało zbudowane przy założeniu, że dokumenty przechodzą przez stan możliwy do przejrzenia i edycji, zanim staną się finalne). Dokument utworzony przez WebAPI można zapisać w tym samym statusie bufora — zapisany, widoczny, edytowalny wewnątrz enova365, ale jeszcze niezatwierdzony i jeszcze niewpływający na ruchy magazynowe, rejestry VAT ani dalsze księgowania.

To rozróżnienie jest całą zasadą projektową dla każdej integracji, która zapisuje dokumenty automatycznie. Kontroler dynamiczny tworzący zamówienie sprzedaży albo fakturę zakupu (FZ) nie musi — i w niemal każdym przypadku nie powinien — wywoływać też osobnej akcji, która go zatwierdza. Zapisz dokument, zostaw w buforze i pozwól człowiekowi przejrzeć i zatwierdzić go wewnątrz enova365 albo przez własny interfejs przeglądu, który dopiero wtedy wywołuje krok zatwierdzenia — jako drugie, świadome wywołanie.

Minimalny, poglądowy payload dla takiego zapisu wygląda mniej więcej tak — znów: dokładne nazwy pól bierz ze Swaggera na własnym serwerze, nie z tego posta:

POST /Handel/ZamowieniaSprzedazy
{
  "Kontrahent": { "Id": 4821 },
  "Elementy": [
    { "Towar": { "Id": 1092 }, "Ilosc": 10, "Cena": 42.50 }
  ],
  "Bufor": true
}

Dlaczego to ważne poza samą "dobrą praktyką": sekwencje numeracji enova365, triggery rezerwacji towaru i kalkulacje VAT to logika biznesowa żyjąca w warstwie aplikacji, nie w bazie danych. Zapis do bufora przez WebAPI nadal przechodzi przez tę warstwę — enova365 przydziela numer dokumentu, stosuje własne reguły cenowe i podatkowe — zatrzymując się tylko przed jednym krokiem, który ma realne konsekwencje finansowe i prawne: finalnym zatwierdzeniem. To krok, który powinien należeć do człowieka, za każdym razem, dopóki nie zbudujesz dostatecznego zaufania do automatyzacji, żeby to przemyśleć — a i wtedy zastanowiłbym się dwa razy, zanim usunę kliknięcie człowieka całkowicie.

Harmonogram Zadań: jak sprawić, żeby enova365 wysyłała, a nie tylko odpowiadała

Wszystko powyżej to Ty pytający enova365 o coś albo przekazujący jej coś. Harmonogram Zadań to druga strona: wbudowany silnik automatyzacji enova365, zbudowany wokół wyzwalaczy i akcji, który można skonfigurować tak, żeby wysyłał wychodzące powiadomienie HTTP, gdy coś się dzieje w systemie — dokument zmienia status, pojawia się nowa faktura, stan magazynowy przekracza próg.

To ma znaczenie dla projektowania integracji, bo zamienia architekturę odpytującą w zdarzeniową. Zamiast Twojej integracji pytającej "czy jest coś nowego?" co N minut, enova365 mówi Ci w momencie, gdy coś się zmieniło, a Ty pobierasz tylko konkretny rekord, który się ruszył. Wyraźnie redukuje to niepotrzebne obciążenie i sprawia, że każdy system po drugiej stronie — portal, agent rekoncyliacyjny, panel przeglądu — działa bliżej czasu rzeczywistego.

Haczyk: nie każda instalacja enova365 ma Harmonogram Zadań skonfigurowany do wychodzących webhooków. Jest dostępny w produkcie, ale to, czy jest skonfigurowany na konkretnej instalacji, z którą integrujesz, to pytanie do administratora albo resellera, nie założenie, wokół którego projektujesz architekturę. Zapytaj przed, nie po. A jeśli z tego korzystasz, Twoja strona potrzebuje publicznie dostępnego endpointu HTTPS — konfiguracja tylko przez VPN wymaga dodatkowego routingu, żeby to odebrać.

Gdzie integracje z WebAPI faktycznie się sypią

Mniej więcej w kolejności, jak często kosztowały realny czas:

Brak ścieżki sieciowej do serwera WebAPI. Największe źródło opóźnienia kalendarzowego i nie ma nic wspólnego z kodem. Wyślij testowe żądanie z rzeczywistego środowiska Twojej integracji do serwera WebAPI, zanim napiszesz cokolwiek innego. Jeśli się nie uda, wszystko dalej jest teorią, dopóki IT nie otworzy portu albo nie skonfiguruje VPN.

Założony, a nie potwierdzony moduł licencyjny. "Mamy enova365" nic nie mówi o WebAPI. Zdobądź pisemne potwierdzenie od resellera i przy okazji dokładny numer builda — zachowanie kontrolerów dynamicznych nie jest idealnie stabilne między głównymi wersjami.

Naiwnie obsłużone odświeżanie tokena. Zadanie wsadowe, które autoryzuje się raz na starcie i nigdy nie odświeża tokena, zacznie zwracać błędy 401 w połowie długiej synchronizacji, dokładnie w momencie, gdy skończy się czas życia tokena. Zbuduj odświeżanie jako proaktywne, oparte na timerze zadanie w tle, nie reakcję na błąd.

Pola dodatkowe z zainstalowanych dodatków. Kontrolery dynamiczne je eksponują — ale tylko jeśli wiesz, że istnieją, i jawnie je zmapujesz. Poproś administratora enova365 o listę dodatków branżowych i ich pól dodatkowych, zanim zamkniesz model danych — nie po tym, jak pierwsza produkcyjna synchronizacja po cichu zgubi dane, o których nikt Ci nie powiedział.

Zbyt wczesne sięganie po kontroler statyczny. Niestandardowy kod po stronie serwera to prawdziwe, ważne narzędzie — ale też zobowiązanie utrzymaniowe. Potwierdź, że kontroler dynamiczny naprawdę nie da rady, zanim go zbudujesz i wdrożysz.

Generowanie numerów dokumentów po stronie integracji. Sekwencje numeracji enova365 są powiązane z jej wewnętrznym stanem. Pozwól jej przydzielać numer za każdym razem; nigdy nie generuj ani nie sugeruj go z zewnątrz, nawet dla szkicu.

Dokąd to prowadzi: od API odczyt/zapis do agenta

Wszystko w tym artykule — przepływ autoryzacji, model kontrolerów, zapis dokumentów w buforze zamiast automatycznego zatwierdzania — to dokładnie ta instalacja, której potrzebuje agent AI, żeby księgować przychodzące faktury jako szkice do przejrzenia zamiast człowieka przepisującego je ręcznie. Opisałem, jak to działa od początku do końca — od faktury z KSeF lądującej w skrzynce do szkicu siedzącego w buforze enova365 i czekającego na jedno kliknięcie: Automatyczne księgowanie w enova365: jak agent AI tworzy szkice dokumentów przez WebAPI.

Jeśli budujesz tego typu integrację — albo chcesz, żeby ktoś, kto już trafił na te tryby awarii, spojrzał na Twoją konkretną konfigurację enova365, zanim zaczniesz — odezwij się. Ten sam fundament WebAPI opisany tutaj napędza agenty AI dla księgowości, które buduję: czytają faktury z KSeF i maila, zapisują szkice księgowań do enova365, a każde zatwierdzenie zostawiają człowiekowi.