Połączenie z SAP B1

BizFlow NH komunikuje się z SAP Business One przez Service Layer (REST API). Każde połączenie SAP (SapConfig) reprezentuje jedną bazę danych firmy.

Konfiguracja firmy — trzy zakładki

W dashboardzie przejdź do Ustawienia — Organizacja, kliknij Dodaj firmę. Konfiguracja składa się z trzech zakładek:

Zakładka 1: Dane firmy

Podstawowe dane identyfikacyjne:

Pole	Przykład	Opis
Nazwa	Firma ABC Sp. z o.o.	Przyjazna nazwa do identyfikacji
NIP	1234567890	Numer identyfikacji podatkowej
Adres	ul. Przykładowa 10	Adres siedziby
Kod pocztowy	00-001	Kod pocztowy
Miasto	Warszawa	Miasto
Kraj	PL	Kod kraju
Email kontaktowy	biuro@firma.pl	Email do powiadomień

Zakładka 2: Połączenie SAP

Sekcja Service Layer:

Pole	Przykład	Opis
Service Layer URL	https://sapserver:50000/b1s/v1/	Pełny adres z portem i ścieżką
CompanyDB	SBO_ABC	Nazwa bazy danych SAP
Typ bazy	HANA / MSSQL	Typ silnika bazy danych
Użytkownik	BizFlowNH	Użytkownik integracji (nie manager!)
Hasło	********	Hasło użytkownika SAP

Przycisk Testuj połączenie wykonuje logowanie do Service Layer, pobranie informacji o firmie i sprawdzenie wersji. Przy sukcesie wyświetla nazwę firmy i wersję SAP.

Sekcja bezpośredniego połączenia z bazą danych:

Używana przez profile mapowania z typem źródła danych SQL (SqlMssql lub SqlHana):

Pole	Przykład	Opis
Connection string	Server=sapserver;Database=SBO_ABC;...	Ciąg połączenia do bazy danych
Użytkownik	bizflow_reader	Użytkownik bazy danych
Hasło	********	Hasło użytkownika bazy

Kiedy potrzebne

Bezpośrednie połączenie z bazą jest opcjonalne. Wymagane tylko gdy profile mapowania używają zapytań SQL zamiast OData (Service Layer). Pozwala na pełną elastyczność SQL (JOIN, subquery, funkcje), ale wymaga dostępu sieciowego do bazy SAP.

Zakładka 3: Integracja KSeF

Konfiguracja integracji z systemem KSeF:

Element	Opis
AutoSend	Przełącznik automatycznej wysyłki faktur (szczegóły)
Webhook URL	URL wywoływany gdy dokument nie pasuje do żadnej reguły routingu (szczegóły poniżej)
Środowisko KSeF	Test / Demo / Produkcja
Certyfikaty	Zarządzanie certyfikatami auth i offline (enrollment, upload, token)
Status sesji	Aktualny stan sesji KSeF
Test połączenia KSeF	Weryfikacja dostępności API KSeF

Użytkownik integracyjny

Nie używaj konta managera

Utwórz dedykowanego użytkownika SAP dla BizFlow NH. Konto managera ma zbyt szerokie uprawnienia i może zostać zablokowane przy zmianie hasła.

Zalecane uprawnienia użytkownika integracyjnego:

• Dokumenty handlowe: odczyt i zapis (faktury, korekty, zaliczki)
• Partnerzy biznesowi: odczyt
• UDO (User-Defined Objects): pełen dostęp (BizFlow NH tworzy własne obiekty)
• Administracja: brak

Webhook — niedopasowane dokumenty

Webhook URL służy do powiadamiania o dokumentach, które nie pasują do żadnej reguły routingu profili.

Jak to działa

Gdy system przetwarza dokument z SAP (np. przez AutoSend lub ręczną wysyłkę), najpierw sprawdza reguły routingu (Ustawienia → Router dokumentów). Jeśli dokument nie pasuje do żadnej reguły — ani UseProfile, ani Skip — system traktuje to jako podejrzenie błędu konfiguracji.

W takiej sytuacji:

1. Dokument jest zapisywany jako niedopasowany — widoczny na dashboardzie jako licznik “Niedopasowane dokumenty”
2. Wywoływany jest webhook (jeśli skonfigurowany) — HTTP POST na podany URL z danymi dokumentu (typ, DocEntry, nagłówek)
3. Dokument NIE jest wysyłany do KSeF — brak domyślnego zachowania

Dlaczego brak zachowania domyślnego

Założenie projektowe: każdy typ dokumentu musi mieć jawnie zdefiniowaną regułę. Jeśli pewne dokumenty nie powinny trafiać do KSeF (np. paragony), konsultant powinien stworzyć regułę routingu z akcją Skip — na przykład:

• Warunek: Series starts_with PAR/ → Akcja: Skip
• Warunek: Series starts_with FZ/ → Akcja: UseProfile → profil zaliczkowy

Brak reguły = brak wysyłki + alert. To bezpieczniejsze niż wysyłanie niezweryfikowanego dokumentu do KSeF.

Konfiguracja webhooka

1. Przejdź do Ustawienia → Organizacja → [firma] → Integracja KSeF
2. W polu Webhook URL podaj adres endpointu (np. https://n8n.firma.pl/webhook/ksef-unmatched)
3. System wyśle POST z payloadem JSON:

{
  "Event": "unmatched_document",
  "ObjType": "13",
  "DocEntry": "12345",
  "Timestamp": "2026-03-21T14:30:00Z"
}

Webhook można podpiąć pod dowolny system powiadomień — email, Slack, Teams, n8n, Make.com.

Przegląd niedopasowanych dokumentów

Na dashboardzie widoczny jest widget z liczbą niedopasowanych dokumentów. Szczegółowa lista dostępna jest przez API: GET /api/v1/mapping-profiles/rules/unmatched. Po naprawieniu konfiguracji (dodaniu brakującej reguły) dokumenty można oznaczyć jako rozwiązane.

Multi-company

Jedna instalacja BizFlow NH obsługuje wiele firm. Każda firma to osobny SapConfig z własnymi:

• Danymi połączenia z SAP
• Certyfikatami KSeF
• Profilami mapowania
• Mapowaniami VAT

Przełączanie między firmami odbywa się przez selektor w nagłówku dashboardu.

Rozwiązywanie problemów

Błąd SSL / certyfikat

Jeśli Service Layer używa certyfikatu self-signed:

System.Net.Http.HttpRequestException: The SSL connection could not be established

Rozwiązanie: dodaj certyfikat CA do zaufanych w kontenerze lub ustaw zmienną środowiskową SAP_IGNORE_SSL=true w pliku .env (tylko do testów!).

Connection refused

System.Net.Http.HttpRequestException: Connection refused

Sprawdź:

• Czy Service Layer działa na serwerze SAP (systemctl status b1s)
• Czy port (domyślnie 50000) jest otwarty w firewallu
• Czy serwer BizFlow NH ma dostęp sieciowy do serwera SAP

Timeout

Jeśli połączenie jest bardzo wolne lub timeout’uje:

• Sprawdź obciążenie serwera SAP
• Sprawdź czy nie ma problemów sieciowych (VPN, routing)
• Domyślny timeout to 30 sekund — można zwiększyć w .env (SAP_TIMEOUT=60)

Błąd autoryzacji (401)

• Sprawdź poprawność nazwy użytkownika i hasła
• Upewnij się, że użytkownik nie jest zablokowany w SAP
• Sprawdź czy CompanyDB jest poprawne (wielkość liter ma znaczenie)