Jak zintegrowaliśmy system rezerwacji campingowych z KSeF 2.0 — case study

Klient prowadzi sieć kempingów i miejsc camperowych. Sezon to tysiące rezerwacji — namiotów, domków, parcel pod kampery. Każda rezerwacja wymaga faktury. Do tej pory: ręcznie, w panelu administracyjnym, jeden dokument na raz. A od 2026 roku Ministerstwo Finansów wymaga wysyłki faktur do KSeF — Krajowego Systemu e-Faktur.

Zadanie: zintegrować istniejący system rezerwacji (PHP 8.4, MariaDB) z KSeF 2.0 tak, żeby faktura generowała się automatycznie z rezerwacji i trafiała do Ministerstwa jednym kliknięciem. Bez ręcznego przepisywania, bez błędów, z pełną zgodnością ze schematem FA(3).

Punkt wyjścia

System rezerwacji działał od lat — sprawdzony, stabilny, obsługiwany przez kilka osób. Generował faktury PDF z danych rezerwacji. Problem: te faktury istniały tylko lokalnie. KSeF wymaga XML w ściśle określonym formacie, szyfrowania, certyfikatów kryptograficznych i komunikacji z API rządowym.

Dodatkowe wyzwanie: hosting współdzielony (shared hosting), nie VPS. Ograniczone możliwości instalacji rozszerzeń PHP, brak bcmath, ograniczony dostęp do systemu.

Wybór podejścia: certyfikat zamiast tokena

KSeF oferuje dwa sposoby uwierzytelniania: token API (stary) i certyfikat X.509 (nowy). Wybraliśmy certyfikat z kilku powodów:

1. Tokeny są wygaszane — Ministerstwo Finansów planuje wyłączenie uwierzytelniania tokenem w 2026 roku. Budowanie integracji na przestarzałym mechanizmie nie ma sensu.

2. Certyfikat jest bezpieczniejszy — plik .p12 (PKCS#12) zawiera klucz prywatny chroniony hasłem. Nie ma ryzyka wycieku tokena z bazy danych.

3. Biblioteka n1ebieski obsługuje certyfikaty natywnie — nie trzeba ręcznie implementować szyfrowania RSA-OAEP i zarządzania sesjami.

Biblioteka n1ebieski/ksef-php-client

To open-source'owa biblioteka PHP do komunikacji z KSeF API v2. Zainstalowaliśmy ją przez Composera. Obsługuje cały flow: otwarcie sesji → szyfrowanie AES-256-CBC → wysyłka XML → zamknięcie sesji → pobranie numeru KSeF.

Kluczowe klasy: Client (połączenie z API), Faktura (DTO faktury), EncryptionKeyFactory (generowanie kluczy szyfrujących), Mode (wybór środowiska demo/test/produkcja).

Na hostingu współdzielonym brakowało rozszerzenia bcmath (wymagane przez n1ebieski do operacji kryptograficznych). Rozwiązanie: polyfill phpseclib/bcmath_compat — czysty PHP, zero zależności systemowych.

Generowanie XML FA(3)

Najbardziej żmudna część pracy. Schemat FA(3) to ponad 200 pól z precyzyjnymi regułami walidacji. Każde pole musi być we właściwej kolejności, z właściwym typem danych, we właściwym zagnieżdżeniu.

Problemy które naprawiliśmy:

- NrWierszaFa musi być liczbą całkowitą (int), nie stringiem — PHP domyślnie traktuje klucze tablicy asocjacyjnej jako stringi - Tablica FaWiersz musi być indeksowana od 1, nie od 0 — standard KSeF wymaga 1-based indexing - Sekcja Platnosc: pola Zaplacono i TerminPlatnosci są wzajemnie wykluczające — jeśli faktura jest opłacona, nie podajesz terminu płatności i odwrotnie - Kolejność elementów w sekcji Platnosc: Zaplacono → DataZaplaty → FormaPlatnosci → RachunekBankowy — XSD walidator odrzuca inne kolejności - PrefiksPodatnika musi być wewnątrz DaneIdentyfikacyjne, nie obok

Każdy z tych błędów powodował odrzucenie faktury przez KSeF z enigmatycznym komunikatem o "naruszeniu schematu XSD".

Trzy środowiska

KSeF ma trzy środowiska i pomylenie ich to jeden z najczęstszych błędów:

DEMO (api-demo.ksef.mf.gov.pl) — do testów z fałszywymi certyfikatami. Można wysyłać faktury z dowolnym NIP-em. Idealne do developmentu.

TEST (ksef-test.mf.gov.pl) — środowisko z prawdziwymi certyfikatami testowymi. Tu generuje się certyfikaty przed produkcją. Dane są resetowane periodycznie.

PRODUKCJA (api.ksef.mf.gov.pl) — live. Kwalifikowane certyfikaty, prawdziwe faktury, prawdziwe konsekwencje prawne.

W naszym systemie przełączanie środowiska to zmiana jednego pola w bazie danych (status: 1/2/3). Wszystkie URL-e API, domeny QR i endpointy weryfikacji przełączają się automatycznie.

QR kody na fakturze

KSeF wymaga dwóch typów kodów QR na fakturze PDF:

QR I (offline): URL z hashem SHA-256 treści XML. Pozwala zweryfikować autentyczność faktury bez dostępu do internetu. Format: https://qr-{env}.ksef.mf.gov.pl/invoice/{NIP}/{DATA}/{HASH}

QR II (certyfikat): URL z podpisem cyfrowym RSA-PSS wykonanym certyfikatem offline (ECDSA Non-Repudiation). Potwierdza tożsamość wystawcy. Używa INNEGO certyfikatu niż certyfikat do uwierzytelniania — to częsty błąd implementacji.

Nasz system generuje oba QR kody automatycznie przy tworzeniu faktury z rezerwacji i umieszcza je na PDF z dynamicznym pozycjonowaniem (nowa strona jeśli brakuje miejsca).

Bezpieczeństwo

Certyfikaty .p12 przechowywane poza katalogiem webroot (~/private/ksef/), chmod 600. Hasła do certyfikatów zakodowane base64 w bazie danych. Ścieżki do certyfikatów w konfiguracji bazy, nie w kodzie. Szyfrowanie AES-256-CBC dla komunikacji z API. Blokada edycji danych nabywcy po wysłaniu faktury do KSeF (ksef_status=2).

Rezultat

Cały proces: klient rezerwuje miejsce → recepcja klika "generuj fakturę" → system tworzy XML FA(3) z danych rezerwacji → klika "wyślij do KSeF" → faktura trafia do Ministerstwa → numer KSeF wraca automatycznie → PDF z QR kodami gotowy do pobrania.

Czas wysyłki jednej faktury: 3-5 sekund. Batch wysyłki (wszystkie nowe): sekwencyjna kolejka, jedna po drugiej, ze statusem w czasie rzeczywistym. Panel KSeF: lista wszystkich faktur z filtrami po miesiącu i statusie, statystyki (wysłane/oczekujące/błędy), pobranie XML.

Całość zrealizowana w 24 godziny pracy deweloperskiej, w 4 sesjach. Klient używa systemu w środowisku testowym, produkcja planowana po wygenerowaniu certyfikatów kwalifikowanych.

Potrzebujesz integracji z KSeF? Napisz na michal@mikamait.pl — zrobimy to szybciej niż myślisz.