Symfonia WebAPI: przewodnik programisty — sesje, licencje, bufor i błędy, które zobaczysz pierwszego dnia

Dlaczego Symfonia dostaje osobny przewodnik

Napisałem już przewodniki po WebAPI enova365, API Comarch Optimy i Sferze w Subiekcie nexo, do tego porównanie wszystkich trzech. Brakowało Symfonii, o którą pyta się najrzadziej, dopóki projekt nie wyląduje na biurku. Wtedy okazuje się, że publicznych materiałów jest mało, artykuły w centrum wsparcia są za logowaniem, a WebAPI zachowuje się mniej jak usługa sieciowa, a bardziej jak zdalnie sterowana kopia Handlu.

To ostatnie tłumaczy prawie wszystko, co dalej. Każde twierdzenie techniczne pochodzi z dokumentacji WebAPI 2026, którą Symfonia publikuje na pomoc.symfonia.pl. Ścieżki endpointów sprawdziłem dodatkowo w otwartoźródłowym kliencie symf-webapi-rs, wygenerowanym z interfejsów WebAPI w wersji 26.20. To projekt zewnętrzny, nie Symfonii, a trasy potrafią się zmieniać między wersjami, więc ostatnie słowo ma Swagger na Waszej instalacji.

Czym właściwie jest WebAPI

Dokumentacja Symfonii mówi to wprost: WebAPI to usługa systemu Windows, która uruchamia Handel w tle i wystawia go przez HTTP(S) w stylu REST, z komunikatami w JSON. Sama nie rozmawia z bazą. Uruchamia obiekty COM Handlu (a po stronie FK obiekt integracji) i nimi steruje.

Wynika z tego sześć konsekwencji. Każdą producent zapisał sam:

Ograniczenie	Co mówi dokumentacja	Co to znaczy dla Was
Zakres jednej instancji	jedna firma, jeden użytkownik Handlu	druga firma to druga usługa, w osobnym katalogu, z osobną licencją
Handel i FK	nie działają w jednej instancji	integracja obu programów to dwie usługi
Równoległe sesje	domyślnie 10, więcej na zapytanie	niezamknięte sesje liczą się, dopóki nie wygasną
Sprawdzanie licencji	tylko przy starcie usługi	po każdej zmianie licencji restart usługi
Model licencji	roczna subskrypcja, wyceniana według zakresu integracji	bez Main nie kupicie żadnego modułu
Równoległość	dodatkowe licencje uruchamiają więcej instancji COM Handlu	przepustowość się kupuje, a nie stroi

Zanim wycenicie projekt, przeczytajcie listę modułów. Po stronie Handlu (WAH): Main, Kontrahenci, Towary, Stany magazynowe, Zamówienia obce, Zamówienia własne, Dokumenty sprzedaży, Dokumenty zakupu, Dokumenty magazynowe, Płatności, Rezerwacje, Własne moduły i Komplet. Po stronie FK (WAF): Main, Kontrahenci, Pracownicy, Słowniki, Rozrachunki, Wymiary, Dokumenty, Plan kont.

A cena? W dokumentacji jej nie znajdziecie. Licencje są roczne i wyceniane według zakresu. Jedyne liczby, jakie znalazłem, to pakiety integratorów: konektor do sklepu plus roczna licencja WebAPI dla Symfonii ERP Handel za 2 400 zł netto rocznie u jednego dostawcy i 3 228 zł rocznie u drugiego. To górna granica dla najprostszego przypadku i zawiera cudze oprogramowanie. Od partnera Symfonii bierzcie wycenę listy modułów pod Wasz zakres, a nie „API".

Sesje: dwa tokeny i trzy rodzaje 401

Uwierzytelnianie ma dwa kroki. W konfiguratorze każdy użytkownik Symfonii, jako który ma działać WebAPI, dostaje token aplikacji. Sesję otwiera się żądaniem GET na endpoint sesji, z parametrem deviceName i takim nagłówkiem:

GET /api/Sessions/OpenNewSession?deviceName=erp-sync HTTP/1.1
Host: symfonia-srv:9000
Authorization: Application 3f2a...-guid

W treści odpowiedzi wraca token sesji. Dołączacie go do każdego kolejnego wywołania:

GET /api/Contractors/Page?page=1&size=100&orderBy=Asc HTTP/1.1
Authorization: Session 9c41...-guid

Jedno uczciwe zastrzeżenie co do ścieżki. FAQ producenta zapisuje wywołanie jako /api/OpenNewSession, a wygenerowany klient i jego układ kontrolerów używają /api/Sessions/OpenNewSession (obok /api/Sessions/CloseSession i /api/Sessions/SessionInformation). Zanim wpiszecie którąkolwiek na sztywno, otwórzcie Swaggera na swojej instancji. SwaggerUI włącza się checkboxem w konfiguratorze, a od wydania 2026 obejmuje wszystkie endpointy.

Długość sesji ustawia się w konfiguratorze osobno dla każdego klienta, a każde autoryzowane wywołanie ją odnawia. FAQ ostrzega przed obiema skrajnościami: za krótka i ciągle otwieracie sesje od nowa, za długa i martwe sesje zajmują Wasze 10 miejsc.

Tu jest pierwsza prawdziwa pułapka. Według strony o kodach HTTP 401 oznacza zły token aplikacji, zły token sesji, wygasłą sesję albo przekroczony limit sesji. Po samym kodzie Wasz klient nie rozpozna, czy ma otworzyć sesję ponownie, czy się zatrzymać. Mój wzorzec: przy 401 jedno ponowne otwarcie i ponowienie żądania. Jeśli samo otwarcie też zwraca 401, stop i alert, bo albo token jest zły, albo skończyły się sesje.

I zamykajcie sesje jawnie przy wyłączaniu. Zadanie synchronizacji, które pada w pętli i za każdym razem otwiera nową sesję, po dziesięciu iteracjach odetnie wszystkich pozostałych.

Kody, które naprawdę zobaczycie

Kod	Znaczenie według Symfonii	Co zrobić
200 / 201 / 204	przetworzone; treść może zawierać utworzony obiekt	odczytać ID i numer z odpowiedzi
400	błąd walidacji albo błąd wewnętrznej metody Handlu; w treści komunikat i ModelState	zalogować ModelState, nie ponawiać na ślepo
401	zły token, wygasła sesja albo przekroczony limit sesji	jedno ponowne otwarcie, potem alert
404	ID nie istnieje w bazie	traktować jak dane, nie jak awarię
409	obiekt edytuje inny użytkownik Handlu	odczekać i ponowić
500	nieobsłużony wyjątek w WebAPI; w treści StackTrace	zebrać logi i zgłosić producentowi

Osobne słowo o 409. Oznacza, że ktoś ma właśnie otwartego kontrahenta albo dokument w Handlu. W ruchliwym biurze to nie jest rzadkość, więc synchronizacja musi odłożyć zmianę do kolejki i spróbować później, zamiast wywalać cały przebieg.

Zapis dokumentów: domyślnie bufor

Dokumenty sprzedaży idą przez SalesIssue. POST /api/SalesIssue/New przyjmuje dokument w treści i parametr issue. Dokumentacja mówi jasno: jeśli nie podacie issue, dokument trafia do bufora, a nie do ksiąg. Osobny PUT /api/SalesIssue/InBuffer wystawia zbuforowany dokument po ID albo numerze, a korekty idą przez /api/SalesIssue/NewCorrection na tej samej zasadzie.

Ja bym ten domyślny tryb zostawił. Dokument zapisany przez integrację powinien wylądować tam, gdzie człowiek może na niego spojrzeć. Tej samej zasady broniłem przy kontach serwisowych w enova365. Po stronie FK jest tak samo: moduł Dokumenty WAF dodaje do bufora FK dokument prosty, zakupu, sprzedaży albo własny, a /api/FKDocuments/Buffer czyta to, co tam czeka.

Najczęstsza awaria przy zapisie to błąd w rodzaju [ImportZO]: [Metoda zwróciła błąd [0].], w wariantach także ImportMG, ImportSP, ImportZK i ImportZW. Strona z rozwiązywaniem problemów wymienia przyczyny i żadna nie dotyczy Waszego JSON-a. Użytkownik WebAPI nie ma uprawnień, nie ma dostępu do części działów, magazynów czy kas albo nie ma ustawionego domyślnego działu, magazynu lub kasy. Co pomaga: raz zalogować się do Handlu jako ten użytkownik, ustawić domyślne wartości i spróbować wystawić ten sam dokument ręcznie. Jeśli Handel przy logowaniu pokazuje jakiekolwiek okno (raport AmBasic, błąd OnTimer, komunikat integracji z FK), WebAPI w ogóle nie wystartuje.

Odczyt zmian: IncrementalSync i niezaznaczone pole

Do synchronizacji jest stronicowanie (/api/Contractors/Page?page=&size=&orderBy=) i GET /api/Contractors/IncrementalSync?dateFrom=, z odpowiednikami dla innych obiektów. Synchronizacja przyrostowa to właśnie to, czego potrzebuje sklep albo CRM: pobrać tylko to, co zmieniło się od ostatniego przebiegu.

Haczyk jest na zakładce Synchronizacja w konfiguratorze. Rejestrowanie zmian włącza się osobno dla każdego typu rekordu, a domyślnie włączone są tylko stany magazynowe. Towary, kontrahentów, zamówienia obce, dokumenty sprzedaży i cenniki trzeba włączyć. Jeśli nikt tego nie zrobi, IncrementalSync zwraca pustą listę, a integracja wygląda na zdrową i gubi każdego nowego klienta. Sprawdźcie tę zakładkę pierwszego dnia i wpiszcie ją do dokumentu przekazania.

Ze strony o problemach zapisałbym sobie jeszcze dwie rzeczy. Po założeniu nowego roku obrotowego w FK WebAPI potrafi zwracać „Nie odnaleziono roku dla daty", dopóki nie zrestartujecie usługi. A GET /api/Ping zwraca załadowane moduły i działające instancje Handlu. To najszybszy sposób, żeby sprawdzić, czy 404 na całym kontrolerze to w rzeczywistości brak licencji na moduł. /api/Alive zwraca po prostu datę serwera.

KSeF w wydaniu 2026

Wersja 26.0.1.0 dodała IKsefController: POST /api/Ksef/AddSendToKsefEvent kolejkuje dokument do wysłania przez Symfonia Cloud Connector, a ChangeKsefStatusAsync zmienia status KSeF w bazie Handlu. To samo wydanie dodało endpointy do załączników dokumentów sprzedaży i zakupu. Jeśli budujecie na Symfonii obieg KSeF dla biura rachunkowego, najpierw sprawdźcie wersję WebAPI. Wcześniejsze niż 2026 tych tras nie mają.

Co zbudowałbym najpierw

Synchronizację tylko do odczytu z porządnie obsłużonymi sesjami: otwarcie, odnawianie, zamknięcie przy wyłączaniu, jedno ponowne otwarcie po 401. Stronicowanie przy pierwszym ładowaniu, IncrementalSync z zaznaczonymi właściwymi polami na wszystko później. Potem zapis wyłącznie do bufora, a wystawia człowiek. Przepustowość na końcu, a w Symfonii to pytanie o licencje (więcej instancji COM), nie o kod.

Najciekawsza automatyzacja jest po stronie FK: rozrachunki, bufor i wymiary to dokładnie to, czego agent potrzebuje, żeby proponować dekretację, którą zatwierdza księgowa. Ten sam podział opisałem w tekście o wyciągach MT940 w Symfonii. Jak rozpoznać proces, który w ogóle nadaje się do oddania maszynie, rozpisałem przy agentach AI dla firm, a wariant z enova365 pod spodem przy integracji enova365 z AI.

Wyceniacie integrację z Symfonią i nie wiecie, których modułów naprawdę potrzebujecie? Napiszcie do mnie. Godzina z Waszym konfiguratorem i obiegiem dokumentów ustali listę licencji szybciej niż jakakolwiek oferta.