Połączenie z KSeF
Przygotuj Stripe do zbierania danych faktury
Pola faktury KSeF pochodzą z danych w Stripe, więc zanim zaczniesz składać, włącz kilka rzeczy w Stripe. Dzięki nim faktury nie zostaną wstrzymane:
- Zbieranie NIP-ów (Tax ID), żeby NIP nabywcy (albo numer VAT UE / zagraniczny identyfikator podatkowy) trafił do
customer_tax_ids. To właśnie czyni z faktury fakturę B2B w KSeF. - Wymagany adres rozliczeniowy, żeby na fakturę trafił adres nabywcy. Zidentyfikowany nabywca (taki z identyfikatorem podatkowym) wymaga adresu; bez niego wstrzymujemy fakturę, zamiast ją złożyć. Zobacz Odrzucenia i problemy.
- Nazwa klienta, żeby nabywca był wskazany na fakturze.
Jak to włączyć, zależy od sposobu fakturowania:
| Fakturujesz przez | Gdzie to włączyć |
|---|---|
| Checkout / API / Billing | W ustawieniach Checkout Session / Customer: włącz Tax ID collection i ustaw adres rozliczeniowy jako wymagany; zbieraj nazwę klienta. |
| Payment Links (bez kodu) | W ustawieniach linku do płatności (Payment Link) w panelu włącz Collect tax IDs oraz Collect customers' addresses i wymagaj nazwy. |
Wskazówka. Webhooka nie ustawiasz: aplikacja Stripe konfiguruje go przy instalacji. W Stripe włączasz tylko powyższe zbieranie danych.
Token czy certyfikat KSeF
Dwie metody uwierzytelnienia. Obie generujesz w aplikacji podatnika KSeF i obie przechowujemy zaszyfrowane:
| Metoda | Co podajesz | Kiedy |
|---|---|---|
| Token KSeF | token maszyna-maszyna | najszybszy start: jedno pole do wklejenia |
| Certyfikat KSeF | certyfikat + klucz prywatny (PEM) | rozwiązanie docelowe Ministerstwa Finansów |
Certyfikat KSeF jest darmowy, wydaje go Ministerstwo Finansów i jest ważny do 2 lat. Zamiast wysyłać sekret przy każdym logowaniu, podpisujesz nim wyzwanie (XAdES), a sam klucz prywatny nigdy nie trafia do KSeF. Tak samo zadziała certyfikat z Twojego podpisu kwalifikowanego, o ile możesz wyeksportować klucz.
Przy certyfikacie wymagane są oba bloki PEM. Bez nich nie zapiszemy połączenia.
Planowo. Ministerstwo Finansów zapowiedziało, że tokeny działają do 31 grudnia 2026 r., a od 1 stycznia 2027 r. zostaną same certyfikaty. W czerwcu 2026 r. MF zaproponowało jednak pozostawienie tokenów na stałe i na razie nie ma rozstrzygnięcia. Obsługujemy obie metody i żadnej nie wycofujemy; jeśli wybierasz dziś od zera, certyfikat jest bezpieczniejszym wyborem.
Najpierw TEST
Środowisko TEST jest zaznaczone domyślnie. Na TEST składasz do piaskownicy KSeF, bez skutków prawnych.
KSeF ma trzy środowiska: TEST (piaskownica do sprawdzenia konfiguracji), DEMO (przedprodukcyjne, bez skutków prawnych) i PROD (produkcja, pełne skutki prawne). To trzy osobne kopie systemu, więc token generujesz w każdym z osobna.
Twój NIP się nie zmienia. KSeF Kit składa faktury z NIP-em z Twoich danych firmy w każdym środowisku. Osobny NIP testowy nie jest potrzebny (TEST przyjmuje też numery wymyślone). Różni się tylko token.
Ważne. Stripe dostarcza zdarzenia z trybu testowego i z trybu live osobno. Ćwicz na fakturach z trybu testowego Stripe, gdy KSeF jest na TEST, żeby dane testowe nigdy nie przeszły do KSeF na PROD. Po przełączeniu KSeF na PROD składamy Twoje prawdziwe faktury z trybu live.
Testuj połączenie
Przycisk „Testuj połączenie” próbuje uwierzytelnić się w wybranym środowisku Twoją metodą (token lub certyfikat). Zwraca tylko sukces albo porażkę. Użyj go, zanim zapiszesz.
Przejście na PROD
Gdy faktury testowe działają, przełącz środowisko na PROD. Przejście wymaga jawnego potwierdzenia, bo skutki prawne są nieodwracalne. Pełną ścieżkę przejścia i listę gotowości znajdziesz w Przejściu na produkcję.
Wygasł token? Połącz ponownie
Gdy KSeF odrzuci z powodu nieaktualnego klucza (kod 21470), wygeneruj nowy token i wklej go ponownie w ustawieniach połączenia. Pola sekretów są tylko do zapisu i w formularzu zawsze puste, więc puste pole nie nadpisze zapisanego sekretu. Zobacz Odrzucenia i problemy.