Gdy mowa o „POHODA API“, zwykle chodzi o interfejs XML. Producent, firma STORMWARE, sam nazywa go API i właśnie przez niego do POHODY trafiają zamówienia ze sklepów internetowych, dokumenty z kas i dane z innych aplikacji. Kto potrzebuje danych tylko do odczytu, ma w liniach POHODA SQL i E1 jeszcze drugą drogę: prosto z bazy danych. W tym przeglądzie znajdziesz, jak działają obie drogi, kiedy której użyć i na co uważać.
Krótka odpowiedź
POHODA ma trzy drogi do danych: pliki XML, mServer i bezpośredni odczyt z bazy. Pliki XML przetwarza się wsadowo, na przykład z wiersza poleceń. mServer to serwer HTTP wbudowany w POHODĘ, który przyjmuje ten sam XML przez sieć. Linie POHODA SQL i E1 działają na Microsoft SQL Server, więc dane można z nich czytać także bezpośrednio. Zapis do POHODY zawsze powinien iść przez interfejs XML, nie przez bazę.
Trzy drogi do danych
- Import i eksport XMLPrzygotowujesz plik XML zgodny ze schematem, a POHODA go przetwarza. Uruchomić to można ręcznie w programie albo automatycznie z wiersza poleceń. Sprawdza się przy wsadach, na przykład nocnym przesyłaniu dokumentów.
- POHODA mServerTen sam XML, tylko wysyłany przez HTTP lub HTTPS. Twoja aplikacja wysyła żądanie i od razu dostaje odpowiedź. Na tym opiera się większość konektorów do sklepów internetowych.
- Bezpośredni odczyt z SQLTylko w liniach POHODA SQL i E1. Dane czytasz dedykowanym kontem tylko do odczytu, bez kolejki i bez obciążania programu. Idealne do zestawień i raportów, do zapisu nie.
Jak wygląda komunikacja XML
Każdy plik XML dla POHODY ma tę samą kopertę. Element główny dataPack zawiera pojedyncze pozycje dataPackItem, a w każdej jest jeden dokument do importu albo jedno żądanie eksportu. Jeden dataPack może łączyć import i eksport. Strukturę opisują schematy XSD: POHODA ma osobny schemat dla każdej agendy, a aktualna jest wersja 2.x. Cały pakiet schematów wraz z opisem pobierzesz ze strony Stormware. Dokumentację dla programistów, czyli opis struktury, obsługiwane dane, a przy eksporcie także filtrowanie i stronicowanie, producent udostępnia na portalu api.stormware.cz.
Na każde żądanie dostajesz odpowiedź. Przy każdym dokumencie znajdziesz w niej informację, czy przeszedł, a jeśli nie, numer błędu, opis i ścieżkę XPath do problematycznego elementu. POHODA potrafi też pilnować duplikatów: po włączeniu kontroli ten sam dokument nie zostanie zaimportowany drugi raz na podstawie identyfikatorów w kopercie.
Użytkownik, na którego koncie przetwarzasz XML, musi mieć w POHODZIE uprawnienia. Do importu potrzebuje zapisu w danej agendzie, do eksportu co najmniej odczytu. Brak uprawnień to jedna z najczęstszych przyczyn, dla których import „nic nie robi“.
Które agendy obsługuje XML
Lista jest długa. Importować można między innymi faktury, zamówienia, oferty, zapytania, przyjęcia, wydania, przesunięcia, paragony, dokumenty kasowe, dokumenty bankowe, zlecenia i produkcję. Z list: adresy, zapasy, magazyny, serie numeracji, rachunki bankowe i kategorie sklepu internetowego. Eksport obejmuje dodatkowo na przykład saldo, dziennik księgowy, centra kosztów, ceny sprzedaży czy listę jednostek księgowych. Dokładny i aktualny przegląd Stormware prowadzi w liście dokumentów do importu i do eksportu, razem z przykładowymi plikami.
mServer w skrócie
mServer jest częścią programu POHODA. Nasłuchuje na wybranym porcie i przyjmuje XML metodą POST z typem text/xml. Uwierzytelnia się nagłówkiem STW-Authorization z danymi użytkownika POHODY i działa przez HTTP i HTTPS. Żądania przetwarza po kolei, w kolejności przyjęcia, dlatego duże wsady warto rozłożyć. Stan sprawdzisz prostym żądaniem na adres /status.
Każda konfiguracja mServera należy do jednej jednostki księgowej, czyli jednej firmy w jednym roku obrotowym. Uruchomiony mServer rezerwuje też całą instancję programu, a producent zaleca uruchamiać go na systemie serwerowym w sieci wewnętrznej. Eksploatację, koszty i praktyczne wskazówki szczegółowo omawia artykuł mServer w POHODZIE.
Bezpośredni odczyt z bazy
Linie POHODA SQL i E1 przechowują dane w Microsoft SQL Server. Do odczytu nie potrzebujesz więc ani mServera, ani XML. Wystarczy dedykowane konto bazy danych tylko do odczytu i bezpieczny dostęp do serwera. Odczyt odbywa się poza programem, a odpowiedź przychodzi od razu. Podstawowa linia POHODY używa bazy plikowej, więc tam ta droga nie działa.
Dokładnie tak działa nasze POHODA MCP: asystent AI czyta dane prosto z bazy SQL i nie potrzebuje mServera ani płatnych dodatków. Akcje zapisu w wyższej taryfie idą natomiast przez interfejs XML, tak jak w każdej innej integracji.
Nie zapisuj do bazy
Zapis bezpośrednio do tabel omija logikę programu: serie numeracji, wyliczanie VAT, powiązania między dokumentami i blokady. Skutkiem są dokumenty, które w POHODZIE wyglądają poprawnie, ale nie zgadzają się w księgowości. Zapis zawsze prowadź przez interfejs XML.
Na co uważać
- Nowy rok obrotowy to nowa jednostka księgowa. Konfigurację mServera i importu XML trzeba na początku roku przełączyć na nową jednostkę, inaczej integracja dalej pracuje na starym roku.
- Aktualizacje POHODY. Po aktualizacji czasem trzeba przekonwertować jednostkę księgową do nowej wersji. Dopóki to nie nastąpi, przetwarzanie XML kończy się błędem. Po każdej aktualizacji sprawdź więc, czy komunikacja znów działa.
- Kopie zapasowe i utrzymanie bazy. Uruchomiony mServer utrzymuje połączenie z bazą i blokuje niektóre operacje, na przykład tworzenie kopii zapasowych. Producent nie zaleca pozostawiania go uruchomionego bez przerwy ani uruchamiania jako usługi Windows. Start i zatrzymanie planuje się w harmonogramie zadań.
- Kolejka żądań. mServer przetwarza żądania po kolei. Gdy sklep wyśle setki zamówień naraz, czekają w kolejce. Uwzględnij to przy projektowaniu synchronizacji.
- Wersje schematów. Stormware na bieżąco rozszerza schematy. Waliduj XML względem aktualnego pakietu i śledź planowane zmiany kompatybilności.
Budować samemu czy nie?
Do jednorazowego importu albo prostego skryptu interfejs XML wystarczy, a dokumentacja jest przyzwoita. Gdy jednak potrzebujesz niezawodnej synchronizacji w obie strony, pilnowania błędów i ponawiania, pracy szybko przybywa. Możliwości dla sklepów internetowych porównuje artykuł Połączenie POHODY ze sklepem internetowym, narzędzia automatyzacji omawia Make, Zapier, n8n i POHODA. Co potrafią poszczególne warianty przy podłączaniu kolejnych systemów, znajdziesz w opisie POHODA Komplet.
Najczęstsze pytania
Czy POHODA ma REST API?
Nie w zwykłym sensie. Za API producent uważa interfejs XML. Przez mServer wywołujesz go po HTTP, ale dane są zawsze w XML zgodnym ze schematami POHODY, nie w JSON.
Czy potrzebuję mServera?
Do bieżącej komunikacji z innej aplikacji tak. Do przetwarzania wsadowego wystarczy import XML z wiersza poleceń. A do odczytu w liniach SQL i E1 nie potrzebujesz żadnego z nich, dane można czytać prosto z bazy.
Czy mServer jest też w niższych wariantach POHODY?
Według producenta mServer jest częścią wszystkich wariantów programu POHODA. Niektóre funkcje różnią się jednak w zależności od linii, na przykład linia E1 potrafi uruchamiać komunikację XML automatycznie wprost z programu.
Gdzie znajdę schematy XSD i przykłady?
Na stronie Stormware w sekcji XML. Jest tam kompletny pakiet schematów w wersji 2.x do pobrania, opis każdego schematu oraz przykładowe żądania i odpowiedzi dla poszczególnych agend.
Czy mogę zapisywać bezpośrednio do bazy SQL?
Technicznie się da, ale tego nie polecamy. Omijasz logikę programu i ryzykujesz dokumenty, które się nie zgadzają. Zapis należy do interfejsu XML.
Czy artykuł był pomocny?
Dzięki za opinię!