Rozwiązywanie problemów

Połączenie z SAP

”Connection refused” przy testowaniu połączenia

Przyczyny:

• Service Layer nie działa na serwerze SAP
• Port (50000/50001) jest zablokowany przez firewall
• Błędny adres URL

Rozwiązanie:

1. Na serwerze SAP sprawdź status Service Layer: systemctl status b1s
2. Sprawdź dostępność portu z serwera BizFlow NH: curl -k https://sapserver:50000/b1s/v1/Info
3. Sprawdź reguły firewalla
4. Upewnij się, że adres URL kończy się na /b1s/v1/

”SSL connection could not be established”

Przyczyna: Service Layer używa certyfikatu self-signed.

Rozwiązanie:

• Dodaj certyfikat CA serwera SAP do zaufanych w kontenerze
• Tymczasowo (tylko do testów): ustaw SAP_IGNORE_SSL=true w .env

”Authorization failed” (401)

Przyczyny:

• Nieprawidłowy login lub hasło
• Użytkownik zablokowany w SAP
• Błędna nazwa CompanyDB (wielkość liter!)

Rozwiązanie:

1. Sprawdź dane logowania bezpośrednio w Service Layer (Postman/curl)
2. W SAP: Administracja — Użytkownicy — sprawdź status użytkownika
3. Sprawdź dokładną nazwę bazy: GET /b1s/v1/CompanyList

Certyfikaty KSeF

”Certificate expired” przy wysyłce

Przyczyna: Certyfikat autoryzacji wygasł.

Rozwiązanie:

1. Dashboard — Ustawienia — Organizacja — [firma] — Integracja KSeF — sprawdź datę ważności certyfikatu
2. Wgraj nowy certyfikat lub uruchom enrollment
3. Nie jest wymagany restart systemu

”Invalid certificate for environment”

Przyczyna: Certyfikat jest dla innego środowiska (np. certyfikat test użyty na demo).

Rozwiązanie:

1. Sprawdź środowisko certyfikatu vs środowisko KSeF firmy
2. Wgraj certyfikat dla właściwego środowiska

”ECDSA P-256 key required for offline certificate”

Przyczyna: Certyfikat offline musi mieć klucz ECDSA P-256. Wgrany certyfikat ma inny typ klucza (np. RSA).

Rozwiązanie:

• Wygeneruj certyfikat offline przez enrollment (automatycznie użyje P-256)
• Lub uzyskaj certyfikat z kluczem ECDSA P-256 od dostawcy

Logowanie i konta

Zapomniałem hasła

Na stronie logowania kliknij Zapomniałeś hasła? — system wyśle email z linkiem do resetowania hasła. Link jest ważny przez ograniczony czas.

Jeśli email nie dochodzi:

1. Sprawdź folder spam
2. Sprawdź konfigurację SMTP w .env
3. Poproś administratora o ręczny reset hasła (Ustawienia — Użytkownicy — Reset hasła)

Faktury odrzucone przez KSeF

”Element ‘NIP’ is missing”

Przyczyna: Brak NIPu nabywcy w wygenerowanym XML.

Rozwiązanie:

1. Sprawdź czy kontrahent w SAP ma wypełnione pole FederalTaxID
2. Jeśli nabywca nie ma NIPu (osoba fizyczna), profil powinien ustawiać BrakID=1
3. Sprawdź mapowanie pola Faktura.Podmiot2.DaneIdentyfikacyjne.NIP

”Invalid tax rate category”

Przyczyna: Kod VAT z SAP nie jest zmapowany w tabeli mapowania VAT.

Rozwiązanie:

1. Otwórz profil mapowania — zakładka VAT
2. Sprawdź, który kod VAT jest na fakturze (np. w SAP)
3. Dodaj brakujące mapowanie

”Schema validation failed”

Przyczyna: Wygenerowany XML nie jest zgodny ze schematem FA(3).

Rozwiązanie:

1. Użyj podglądu XML w dashboardzie
2. Porównaj z oficjalnym schematem FA(3)
3. Najczęstsze problemy: brakujące wymagane pola, nieprawidłowy format daty, nieprawidłowa struktura adresu

”Duplicate invoice”

Przyczyna: Faktura o tym samym identyfikatorze została już wysłana do KSeF.

Rozwiązanie:

• Sprawdź czy faktura nie została wcześniej wysłana (dashboard — filtr Accepted)
• Każdy dokument może być wysłany do KSeF tylko raz

Tryb offline

Tryb offline nie aktywuje się mimo niedostępności KSeF

Przyczyny:

• BizFlow NH nie ma dostępu do API Latarni
• Latarnia nadal raportuje Available (KSeF jest niedostępny, ale Latarnia tego nie wie)

Rozwiązanie:

1. Sprawdź dostępność Latarni: curl https://latarnia.ksef.mf.gov.pl/api/Status
2. Sprawdź logi: ./ctl.sh logs api | grep Latarnia
3. Ręczne przełączenie na tryb offline: w selektorze firm (CompanySelector) w nagłówku dashboardu rozwiń dropdown i wybierz override stanu Latarni. Opcja dostępna wyłącznie w środowiskach testowych i demo.

Kody QR nie generują się

Przyczyny:

• Brak certyfikatu offline (KOD II)
• PDF Sidecar nie działa

Rozwiązanie:

1. Sprawdź czy certyfikat offline jest wgrany (Dashboard — Certyfikaty)
2. Sprawdź health check PDF Sidecar: ./ctl.sh status
3. Sprawdź logi: ./ctl.sh logs pdf-sidecar

PDF

”PDF sidecar unhealthy”

Przyczyna: Kontener PDF Sidecar nie działa lub nie odpowiada na health check.

Rozwiązanie:

1. Sprawdź status: ./ctl.sh status
2. Restart: docker restart bizflow-pdf-sidecar
3. Sprawdź logi: ./ctl.sh logs pdf-sidecar
4. Sprawdź czy port 3100 nie jest zajęty przez inny proces

PDF nie zawiera danych faktury

Przyczyna: Błąd w przekazywaniu danych do PDF Sidecar.

Rozwiązanie:

1. Sprawdź logi API: ./ctl.sh logs api | grep PDF
2. Sprawdź czy MinIO działa: ./ctl.sh status
3. Sprawdź wersję PDF Sidecar vs API (kompatybilność)

Panel serwisowy

Panel serwisowy (dostępny dla ról super_admin i service) zawiera trzy zakładki:

SAP Setup

Instalacja i zarządzanie UDT, UDF i UDO w SAP. Wyświetla listę wymaganych obiektów z ich statusem instalacji. Opcja Install All Missing do automatycznej instalacji brakujących elementów.

Zawiera również snippet triggera SQL — gotowy do skopiowania kod MSSQL lub HANA dla SBO_TransactionNotification, który tworzy zdarzenia w tabeli @BCD_EVENTS. Snippet jest generowany dynamicznie na podstawie konfiguracji firmy.

Submissions

Historia wysyłek do KSeF z możliwością filtrowania, podglądu szczegółów i ponowienia (retry) nieudanych wysyłek.

Diagnostics

Narzędzia diagnostyczne: sprawdzenie połączenia z SAP, KSeF, bazą danych, weryfikacja certyfikatów i konfiguracji.

Znane ograniczenia

Faktury zakupu (SAP Purchase Invoices)

Obsługa faktur zakupu z KSeF jest w fazie planowania. W menu bocznym pozycja SAP — Faktury zakupu wyświetla stronę “Coming soon”.

Ogólne

Jak sprawdzić wersję BizFlow NH?

./ctl.sh status
# lub
curl http://localhost:5001/api/v1/health

Jak zrestartować cały system?

./ctl.sh stop && ./ctl.sh start

Jak zebrać logi do zgłoszenia?

./ctl.sh logs --all --since 1h > bizflow-logs.txt

Wyślij plik bizflow-logs.txt do supportu BizCode.