Integracja z SAP Business One: cztery drogi do danych i kiedy którą wybrać

Service Layer to serwer aplikacji SAP Business One, który udostępnia obiekty i usługi systemu przez HTTP i OData, a dane zwraca w formacie JSON. To jedna z kilku dróg do danych w SAP Business One, obok DI API, odczytu bazy i plików.

Piszę ten tekst jako inżynier produkcji, który czyta SAP Business One przez Service Layer w panelu dla Kocher+Beck Polska, i jako ktoś, kto musiał te drogi porównać, zanim wybrał jedną. Opieram się na dokumencie SAP „Working with SAP Business One Service Layer”, wersja 1.29 z 27 lipca 2026 r. (opisuje SAP Business One 10.0). Każdą liczbę i nazwę z dokumentacji podaję z miejscem, w którym ją znalazłem. Gdy czegoś w dokumentacji nie ma, zaznaczam to i oznaczam jako moje doświadczenie albo moją decyzję.

Cztery drogi do danych SAP Business One w jednej tabeli

Do danych SAP Business One prowadzą cztery drogi: Service Layer (HTTP i OData), DI API (biblioteka dla dodatków i programów), odczyt bazy danych oraz pliki z eksportu. Pierwsze dwie to interfejsy opisane przez SAP, które opierają się na tej samej warstwie obiektów. Odczyt bazy i pliki wybieram dopiero wtedy, gdy API nie wystarcza albo go brakuje.

Licencji i warunków wsparcia ta tabela nie rozstrzyga. Zakres licencji na interfejsy, dostęp do bazy i warunki wsparcia wynikają z umowy z SAP albo z partnerem, który utrzymuje Twój system. Sprawdź je przed wyborem drogi.

Czym jest Service Layer i czy zastępuje DI API?

Service Layer nie zastępuje DI API. Oba korzystają z tego samego DI Core, więc mają te same definicje obiektów i właściwości, ale różnią się sposobem dostępu: Service Layer przez HTTP i OData, DI API przez bibliotekę w programie. Dokument SAP zawiera aneks, który zestawia obie składnie obok siebie.

DI Core jako wspólna podstawa

Dokument SAP opisuje Service Layer jako architekturę trzywarstwową: klient rozmawia z serwerem WWW przez HTTP i OData, a serwer korzysta z bazy danych. W serwerze pracują cztery elementy: parser OData, DI Core, menedżer sesji i OBServer. Parser tłumaczy żądanie HTTP na operację na obiekcie biznesowym. DI Core to ten sam interfejs do obiektów SAP Business One, którego używa DI API (rozdział 2.2 dokumentu).

W praktyce oznacza to, że utworzenie zamówienia wygląda podobnie w obu światach. W DI API pobierasz obiekt oOrders, ustawiasz właściwości i wołasz Add(). W Service Layer wysyłasz POST /Orders z JSON o tych samych polach (aneks I dokumentu). Dla czytania danych, które wykonuję w panelu, odpowiednikiem jest GET /Orders(2).

Logowanie i sesja

Przed każdą operacją trzeba się zalogować żądaniem POST /b1s/v1/Login z nazwą bazy firmy, nazwą użytkownika i hasłem w JSON. W odpowiedzi serwer ustawia ciasteczko B1SESSION. To ciasteczko jest obowiązkowe w każdym kolejnym żądaniu. Drugie ciasteczko, ROUTEID, jest opcjonalne i służy do przypinania sesji do jednego węzła przy równoważeniu obciążenia.

POST https://<serwer>:<port>/b1s/v1/Login
{"CompanyDB": "<baza>", "UserName": "<użytkownik>", "Password": "<hasło>"}

GET /b1s/v1/Orders(2)
Cookie: B1SESSION=<identyfikator sesji>

W przykładzie SAP odpowiedź na logowanie zawiera "SessionTimeout": 30. Opcja konfiguracyjna SessionTimeout określa czas bezczynności sesji w minutach, a wartość domyślna to 30. Po jego upływie serwer odpowiada kodem 401 z komunikatem „Invalid session or session already timeout”. Klient, który trzyma sesję dłużej, musi więc obsłużyć ponowne logowanie.

v1 i v2: OData v3 i v4

Service Layer obsługuje dwie wersje protokołu OData. Adres /b1s/v1/$metadata odpowiada za OData v3, a /b1s/v2/$metadata za OData v4 (rozdział 1.3). Różnica widoczna od razu w praktyce dotyczy stronicowania: w wersji 3 odnośnik do następnej porcji nazywa się odata.nextLink, w wersji 4 @odata.nextLink. Dokument $metadata wylistuje encje i pola dostępne w Twojej instalacji, więc zaczynam od niego, zanim napiszę pierwsze zapytanie.

Czy Service Layer działa tylko na HANA?

Nie. Historia zmian dokumentu SAP zapisuje wsparcie dla SAP Business One 10.0 PL01 na Microsoft SQL Server (wpis 1.16 z 2 grudnia 2019 r.). Według rozdziału 2.1 Service Layer działa na SUSE Linux Enterprise i Microsoft Windows (obie platformy, od 10.0 PL01). Niektóre funkcje zależą od bazy, co opisuję niżej.

Service Layer działa także na SQL Server (wpis 1.16 historii zmian). Różnice między bazami dotyczą szczegółów:

• Widoki SQL (view.svc) są dostępne w SAP Business One 10.0 PL02 na Microsoft SQL Server. Dokument zaznacza, że dotyczą wyłącznie tej kombinacji (rozdział 3.8).
• Semantic Layer, czyli odpowiednik widoków dla wersji na HANA, ma własny adres /b1s/v1/sml.svc (rozdział 3.7).
• SQLQueries działają od SAP Business One 10.0 FP 2011 na obu bazach. Service Layer normalizuje nazwy tabel i kolumn oraz część funkcji (na przykład IsNull i IfNull) między SQL Server a HANA (rozdział 4.8), ale obsługuje tylko ograniczony podzbiór SQL i funkcji (rozdział 4.7), więc zapytanie sprawdzam na bazie klienta.

Poziom poprawek dla widoków SQL podaję za dokumentem SAP (rozdział 3.8): PL02 na Microsoft SQL Server. Jeśli planujesz widoki, sprawdź to w dokumentacji swojej wersji.

Dlaczego zapytanie zwraca tylko 20 rekordów?

Domyślny rozmiar strony w Service Layer wynosi 20 rekordów. Większą stronę można zażądać nagłówkiem Prefer: odata.maxpagesize=N; dokumentacja SAP pokazuje przykład z wartością 50, a serwer potwierdza ją nagłówkiem Preference-Applied. Kolejne porcje pobiera się odnośnikiem nextLink z odpowiedzi. Rozmiar domyślny zmienia też opcja PageSize w pliku conf/b1s.conf.

Dwie uwagi z dokumentu (rozdział 3.6). Wartość przesłana w żądaniu ma pierwszeństwo przed opcją konfiguracyjną. Wartość 0 wyłącza stronicowanie, czego dla dużych tabel nie robię, bo pojedyncza odpowiedź staje się wtedy ciężka dla serwera. Dla zapytań SQLQueries dokument wymaga stronicowania po stronie serwera (rozdział 4.4), więc tam wartość nie jest do wyboru.

GET /b1s/v1/Orders
Prefer: odata.maxpagesize=50

HTTP/1.1 200 OK
Preference-Applied: odata.maxpagesize=50

Dlaczego dostaję 403 przy SQLQueries?

Zwykły użytkownik domyślnie nie ma uprawnień do uruchamiania zapytań SQLQueries i dostaje HTTP 403 z kodem -6006 i komunikatem „You are not permitted to perform this action”. Uprawnienie nadaje administrator w oknie Autoryzacje ogólne, osobno dla każdego zapytania. Tworzenie i zmiana zapytań ma osobną autoryzację „Modify SQL Queries in Service Layer” (rozdział 4.11).

To samo dotyczy widoków: użytkownik bez uprawnień dostaje 403 z kodem 804 („No permission to access this view”). Zapytania mają też listę dozwolonych tabel w pliku b1s_sqltable.conf. Tabel spoza listy dokument nie obejmuje wsparciem, a dopisywanie ich na własną rękę określa jako działanie poza zakresem wsparcia, które może osłabić bezpieczeństwo (rozdział 4.5). Na liście są między innymi dokumenty sprzedaży i zakupu, kartoteki kontrahentów i artykułów, struktury produktów (receptury) oraz zlecenia produkcyjne.

Czy w Service Layer jest tryb tylko do odczytu?

W dokumencie SAP nie znalazłem osobnego trybu tylko do odczytu. Wyszukanie tego pojęcia trafia jedynie w opis właściwości, których nie można zmienić. Ograniczenie do metod GET to więc decyzja architektury po stronie integracji, wsparta uprawnieniami użytkownika technicznego w SAP Business One. Tak to rozwiązuję w panelu dla Kocher+Beck Polska.

Moje zasady dla odczytu. To moje decyzje, SAP ich nie narzuca:

• Konto techniczne z minimalnymi uprawnieniami, zakładane i opisane przez IT firmy.
• Klient w panelu, który wysyła wyłącznie żądania GET. Metod POST, PATCH i DELETE do SAP nie używam.
• Wspólny limit równoległych żądań do SAP, żeby panel nie obciążał systemu finansowego. Dokument SAP nie podaje jednej liczby takiego limitu, więc wartość ustalam z administratorem po próbie obciążenia.
• Wynik raportu sprawdzony z raportem w samym SAP. Raport „Analiza sprzedaży wg odbiorcy” odwzorowany w panelu zgadza się z SAP co do grosza w sześciu ustawieniach raportu, co sprawdziłem czterema niezależnymi drogami (stan: wrzesień 2026, bez kwot).

Zapisu do SAP Business One w żadnym wdrożeniu nie robiłem. Gdyby był potrzebny, wymagałby osobnej decyzji, testów na kopii i osobnej bramki.

Dodatek do SAP Business One czy integracja przez API?

Dodatek wybieram wtedy, gdy trzeba zmienić coś w oknie SAP: dodać pole, przycisk albo kontrolę przy zapisie dokumentu. Integrację przez API wybieram, gdy dane mają wyjść do zewnętrznego panelu, portalu lub innego systemu, a samo okno SAP zostaje bez zmian. Dodatek trzeba utrzymywać przy każdej aktualizacji wersji, a API zwykle wymaga tylko uprawnień i monitoringu.

Pytania, które zadaję przed wyborem:

• Czy użytkownicy mają pracować nadal w oknie SAP, czy w osobnym panelu?
• Czy potrzebna jest zmiana zachowania SAP (walidacja, pole), czy wystarczy odczyt?
• Kto będzie utrzymywał rozwiązanie po aktualizacji SAP Business One do nowej wersji?
• Czy dane mają trafić do systemów, które nie mają dostępu do sieci SAP?

W SDK Help klasa Company jest głównym obiektem DI API (połączenie z bazą firmy SAP Business One), a Application korzeniem UI API (uruchomione okno SAP). Dodatek do SAP Business One zwykle używa obu, to moja ocena, nie zapis z dokumentacji. Odczyt przez Service Layer mam wdrożony, dodatek na SDK to oferta.

Czy da się podłączyć Excel lub Power BI do SAP Business One?

Excel i Power BI mają konektor OData, więc technicznie rozmowa z Service Layer jest możliwa, ale tego połączenia nie testowałem na instancji SAP Business One i nie podaję kroków, których nie sprawdziłem. Podaję tylko zasady, które wynikają z dokumentacji SAP i Microsoft, żeby można było ocenić, czy to ma szansę zadziałać u Ciebie.

• Service Layer wymaga logowania żądaniem POST /Login i ciasteczka B1SESSION w każdym kolejnym żądaniu. Trzeba sprawdzić, czy narzędzie potrafi tak się zalogować.
• Konektor OData w Power Query wymienia rodzaje uwierzytelniania: anonimowe, Windows, Basic, Web API i konto organizacyjne. Windows i Basic wymagają bramy danych (Gateway) w usłudze Power BI, zależnie od scenariusza. Dokumentacja Microsoft zaznacza też, że uwierzytelnianie OAuth do dowolnych usług w większości przypadków nie działa i wtedy właściciel usługi musi zmienić konfigurację albo zbudować własny konektor.
• Domyślna strona ma 20 rekordów, więc bez obsługi nextLink raport będzie niepełny.
• Uprawnienia konta w SAP ograniczają to, co narzędzie zobaczy.

Jeśli połączenie bezpośrednie nie działa, rozwiązaniem bywa mała usługa pośrednia, która loguje się do SAP, obsługuje stronicowanie i oddaje dane w prostszej formie. To jednak kolejny element do utrzymania, więc najpierw sprawdzam, czy wystarczy zwykły eksport.

Co sprawdzić przed startem integracji z SAP Business One

Lista dla działu IT, którą przechodzę na diagnozie:

• Wersja i poziom poprawek SAP Business One (od tego zależy dostępność funkcji, na przykład widoków SQL).
• Baza: Microsoft SQL Server czy SAP HANA. Wpływa na dostępność widoków SQL i na szczegóły zapytań.
• Czy Service Layer jest zainstalowany i dostępny z sieci, z której będzie łączył się panel. W przykładach dokumentacji adres ma postać https://serwer:50000/b1s/v1, a HTTPS jest domyślny. Port i certyfikat ustala administrator.
• Konto techniczne z minimalnymi uprawnieniami i osoba, która za nie odpowiada.
• Limit równoległych żądań i okna, w których cięższe odczyty są dozwolone.
• Kopia testowa albo baza testowa, na której porównam wynik z raportem w SAP.
• Właściciel liczby po stronie firmy, który rozstrzygnie, która definicja raportu jest właściwa.

Dopiero po tej liście wybieram drogę z tabeli na początku. Kolejność kroków i bramki opisuję na stronie Integracje SAP, MES i CAD.

Najczęstsze pytania

Źródła i aktualność

Stan dokumentacji sprawdziłem 3 listopada 2026. Datę tę zmieniam tylko wtedy, gdy zmieniam treść artykułu. Wersje oprogramowania mogą się różnić od opisanych w źródłach, więc przed decyzją sprawdź dokumentację swojej wersji.

1. SAP, „Working with SAP Business One Service Layer”, User Guide, wersja 1.29 z 27 lipca 2026 (PDF). Dostęp: 3 listopada 2026.
2. SAP Learning, „Exploring the Service Layer API Architecture and Capabilities”. Dostęp: 3 listopada 2026.
3. SAP Business One SDK Help 10.0, zakładka DI API. Dostęp: 3 listopada 2026.
4. Microsoft Learn, „Power Query OData Feed connector”. Dostęp: 3 listopada 2026.
5. SAP, zasady używania znaków towarowych. Dostęp: 3 listopada 2026.

Podobne artykuły i usługi