Jak działa składanie

Faktura ze Stripe może trafić do KSeF bez Twojego udziału. Oto cały przepływ.

Kto jest nabywcą? To pierwsza rzecz, którą rozstrzygamy. Sam identyfikator podatkowy nie wystarcza. Łączymy kraj z adresu nabywcy, rodzaj identyfikatora podatkowego oraz kwoty netto i VAT. Dopiero ten zestaw danych pozwala zakwalifikować dokument do jednego z opisanych niżej scenariuszy. Jeśli reguła nie daje jednoznacznego wyniku, nie zgadujemy i nie wysyłamy dokumentu do KSeF.

Pipeline

invoice.finalized: Stripe wysyła webhook po sfinalizowaniu faktury. Rozpoznajemy konto po połączonym koncie Stripe i zapisujemy fakturę jako niezmienny dokument źródłowy. Payload nie jest później modyfikowany.
FA(3): mapujemy payload Stripe na ustrukturyzowaną fakturę FA(3) (schemat KSeF). Stripe nie ma wszystkiego: adres sprzedawcy bierzemy z profilu firmy, NIP nabywcy z customer_tax_ids, adres nabywcy z jego adresu rozliczeniowego, a kwoty rozbijamy na pozycje VAT. Przenosimy szczegóły pozycji, nie tylko sumy według stawek: każda linia ze Stripe staje się pozycją FA(3) ze swoją nazwą (z opisu linii), ilością, ceną jednostkową netto, kwotą netto i stawką VAT. Gdy faktura ma więcej pozycji, niż Stripe mieści w jednym zdarzeniu, dopytujemy Stripe o pełną listę; koszt wysyłki dostaje osobną pozycję („Koszt dostawy”).
Sesja online KSeF: otwieramy sesję, szyfrujemy fakturę (RSA-OAEP + AES-256-CBC, dokładnie jak wymaga KSeF), wysyłamy i odpytujemy o status.
UPO: po przyjęciu KSeF zwraca numer KSeF i podpisane UPO (urzędowe poświadczenie odbioru). To jest dowód prawny złożenia.
Zapis zwrotny do Stripe: numer KSeF zapisujemy z powrotem w metadata faktury (maszynowo: ksef_number, a dla eksportu też ksef_verification_url). Stripe blokuje wszystkie pola widoczne dla nabywcy (footer, description, custom_fields) po finalizacji faktury, a numer KSeF powstaje dopiero po złożeniu sfinalizowanej faktury. Dlatego numer nie może pojawić się na PDF ani stronie Stripe. Numer i UPO znajdziesz w panelu; krajowy nabywca B2B otrzymuje fakturę bezpośrednio przez KSeF.

Jak działają reguły automatyczne

Reguły są z góry określone. Klasyfikacja korzysta z danych konkretnego dokumentu, ustawień Twojego konta oraz, w przypadku korekty, z powiązanej faktury pierwotnej. Przeliczenie waluty korzysta z publicznego kursu NBP, a status po wysyłce z odpowiedzi KSeF. Nie używamy modelu AI, oceny prawdopodobieństwa, danych innych klientów ani historii zachowania nabywcy. Aplikacja nie uzupełnia brakujących danych własnymi domysłami. Wynik każdej reguły to wysyłka, wstrzymanie przed wysyłką albo pozostawienie dokumentu poza KSeF.

Co sprawdzamy	Reguła	Co robi aplikacja
Zdarzenie ze Stripe	Sfinalizowana faktura uruchamia `invoice.finalized`. Nota kredytowa uruchamia `credit_note.created` i może zostać przetworzona dopiero po zapisaniu faktury pierwotnej.	Zapisujemy niezmienny dokument źródłowy i dodajemy go do kolejki.
Gotowość konta	Sprawdzamy limit planu, kompletność profilu firmy i aktywne dane dostępowe do wybranego środowiska KSeF.	Jeśli któryś warunek nie jest spełniony, dokument zostaje wstrzymany przed kontaktem z KSeF.
Polska firma	Kraj nabywcy to `PL`, identyfikator to polski NIP albo numer VAT UE zaczynający się od `PL` i zawierający 10 cyfr, a faktura ma jedną obsługiwaną stawkę VAT: 23%, 8% albo 5%.	Tworzymy krajową fakturę B2B z NIP-em nabywcy i kwotami netto oraz VAT. Stawka 0%, zwolnienie, kilka stawek albo NIP nabywcy równy NIP-owi sprzedawcy powodują wstrzymanie.
Firma z innego kraju UE	Kraj nabywcy należy do UE, ale nie jest Polską, a identyfikator ma typ VAT UE.	Klasyfikujemy sprzedaż jako B2B z odwrotnym obciążeniem i mapujemy kwotę netto do odpowiednich pól FA(3).
Firma spoza UE	Kraj nabywcy nie należy do UE, ma zagraniczny identyfikator podatkowy, a polski VAT wynosi zero.	Klasyfikujemy sprzedaż jako eksport usług i mapujemy kwotę netto jako niepodlegającą VAT w Polsce. Jeśli Stripe wykazuje VAT, wstrzymujemy dokument.
Brak pasującej klasyfikacji	Brakuje właściwego identyfikatora firmowego dla kraju nabywcy albo dane wskazują na konsumenta.	Nie wysyłamy dokumentu do KSeF. Oznaczamy go jako sprzedaż poza zakresem tej integracji, w tym jako sprzedaż konsumencką w UE rozliczaną poza KSeF.
Kompletność dokumentu	Zidentyfikowany nabywca musi mieć adres. Lista pozycji musi być kompletna, a suma pozycji i kosztu dostawy musi zgadzać się z kwotą netto faktury.	Brak adresu, niepełna lista pozycji lub nierozliczona różnica kwot powodują wstrzymanie. Dokument nie trafia wtedy do KSeF.
Waluta obca	Dla faktury z polskim VAT ustalamy właściwy dzień i pobieramy średni kurs NBP z poprzedniego dnia roboczego.	Zapisujemy w FA(3) kwotę VAT w złotych oraz użyty kurs i datę tabeli NBP.
Korekta	Pobieramy nabywcę i sposób opodatkowania z faktury pierwotnej, a kwoty z noty kredytowej. Faktura pierwotna musi być wcześniej zapisana i przyjęta przez KSeF.	Tworzymy korektę KOR odnoszącą się do numeru KSeF faktury pierwotnej. Korektę z polskim VAT w walucie obcej obecnie wstrzymujemy.
Poprzednie próby	Sprawdzamy, czy dokument został już przyjęty w tym samym środowisku KSeF albo czy inna próba jest w toku.	Nie wysyłamy drugi raz dokumentu już przyjętego ani równolegle przetwarzanego.
Odpowiedź KSeF	Po wysyłce odpytujemy KSeF o wynik dla zapisanych identyfikatorów sesji i dokumentu.	Przyjęcie zapisuje numer KSeF i UPO. Odrzucenie zapisuje komunikat KSeF. Błąd przejściowy przed wysyłką uruchamia ponowną próbę, a niepewny wynik po wysyłce powoduje dalsze sprawdzanie tej samej próby bez ponownego wysłania.

Dokładne mapowanie podatkowe obsługiwanych scenariuszy opisujemy w tabeli poniżej. Powody wstrzymania i sposób dalszego postępowania znajdziesz w Odrzuceniach i problemach. Zasady dotyczące zautomatyzowanego przetwarzania danych osobowych opisuje również Polityka prywatności.

Co widzisz na ekranie

Każda faktura ma jeden, zrozumiały status. Tyle wystarczy, żeby wiedzieć, co się dzieje:

Status	Co znaczy
W kolejce	Czeka na wysyłkę. Zaraz ją złożymy.
Składanie	Trwa wysyłka do KSeF: sekundy, nie godziny.
Złożona	Przyjęta. Masz numer KSeF i UPO, czyli dowód.
Odrzucona	KSeF nie przyjął. Pokazujemy powód i konkretny następny krok. Faktura czeka i możesz złożyć ponownie.
Wstrzymana	Świadomie nie wysłaliśmy, na przykład z powodu wyczerpanego limitu, niekompletnego profilu, braku danych dostępowych albo danych faktury, których nie możemy jednoznacznie zmapować. Nic nie ginie.

Odrzucona i Wstrzymana to dwie różne rzeczy. Odrzucenie to odpowiedź KSeF: coś w danych lub połączeniu wymaga poprawy. Wstrzymanie to nasza świadoma decyzja, żeby jeszcze nie wysyłać (np. ponad darmowy limit albo zanim uzupełnisz NIP i adres). W obu przypadkach faktura czeka bezpiecznie.

Ważne. Zidentyfikowany nabywca (z NIP-em, numerem VAT UE lub zagranicznym identyfikatorem podatkowym) wymaga adresu. Jeśli Stripe nie ma adresu tego klienta, wstrzymujemy fakturę, zamiast złożyć niekompletną. Uzupełnij adres klienta w Stripe i złóż ponownie. Aby uniknąć tego całkowicie, wymagaj adresu rozliczeniowego w Stripe od początku: zobacz Połączenie z KSeF. Sposób naprawy opisaliśmy w Odrzuceniach i problemach.

Próby = osobne rekordy

Każda próba wysyłki to osobny rekord (Submission), nie nadpisanie. Ponowna próba tworzy nowy wiersz, więc historia jest audytowalna, a podwójna wysyłka niemożliwa. W tle statusy próby to submitting, accepted, rejected, blocked. To one składają się na widoczny status faktury powyżej.

Wysyłka jest blokująca

#submit w bibliotece śpi między odpytaniami o status, więc działa w zadaniu w tle, nigdy w żądaniu webowym. Jeśli proces padnie po otwarciu sesji, #await wznawia ją po zapisanych referencjach (idempotentnie, nie składa dwa razy).

Scenariusze faktur, które obsługujemy

KSeF to system B2B/B2G: nabywcą jest firma albo podmiot publiczny. To, kim jest nabywca, decyduje o sposobie opodatkowania VAT, a sposób opodatkowania decyduje o tym, które pola FA(3) wypełniamy. Oto, na co mapuje się każdy scenariusz i na jakim jest etapie.

Scenariusz	Nabywca	Traktowanie VAT	Mapowanie FA(3)	Status
Krajowy PL B2B	Polska firma (ma NIP)	23%, 8% albo 5% VAT	`NIP` nabywcy; netto + VAT w pozycji ze stawką (`P_13_1`/`P_14_1` dla 23%)	W pełni wspierany
B2B w UE	Firma w innym kraju UE (nr VAT UE)	Odwrotne obciążenie: VAT rozlicza nabywca	`KodUE` + `NrVatUE` nabywcy; pozycja tylko netto `P_13_9`; znacznik odwrotnego obciążenia `P_18`	Wspierany
Firma spoza UE	Firma poza UE (np. polski JDG fakturujący firmę SaaS z USA)	Eksport usług: niepodlegający VAT w PL (NP), rozliczany przez nabywcę	`KodKraju` + `NrID` nabywcy; pozycja tylko netto `P_13_8`	Wspierany
Konsument B2C	Osoba prywatna (bez NIP)	Poza zakresem KSeF	nie dotyczy	Nie w KSeF

Każdy z powyższych scenariuszy B2B jest zbudowany od początku do końca: mapowanie FA(3), znaczniki i przeliczenie kursem NBP. Zanim włączymy traktowanie VAT dla UE i spoza UE na produkcji, doradca podatkowy potwierdza dokładne znaczniki VAT (P_18, pozycje NP) w jednym przeglądzie. To bramka poprawności, a nie stopniowe wdrażanie. W trybie testowym złożysz je wszystkie już dziś.

Konsumenci B2C

KSeF jest dla B2B i B2G. Sprzedaż osobom prywatnym jest w KSeF dobrowolna i praktycznie poza zakresem tego narzędzia. Wystawiaj ją tak jak dotychczas (np. paragon albo zwykła faktura bez KSeF). Jeśli konsument później poprosi o fakturę ze swoim NIP, to jest faktura B2B i przechodzi przez KSeF normalnie.

Waluta obca

Faktury do UE i eksportowe są zwykle w EUR lub USD. Kwotę w złotych, której potrzebuje KSeF, liczymy po kursie średnim NBP z ostatniego dnia roboczego przed momentem powstania obowiązku podatkowego (dla usługi ciągłej jest to koniec okresu rozliczeniowego, a przy fakturze wystawionej z góry data wystawienia). To kurs wymagany prawem (art. 31a), nigdy kurs rozliczeniowy Stripe. Zobacz Waluty i NBP.

To nie jest porada podatkowa. Potwierdź traktowanie VAT swojej konkretnej sprzedaży ze swoją księgową.

Powiadomienia

Piszemy do właściciela konta tylko w dwóch sprawach wartych przerwania: odrzucenie (trzeba zadziałać) oraz złożenie, które właśnie wyczerpało darmowy limit (jeden e-mail, dokładnie raz). Zobacz Plany i limity.

Gdy faktura zostanie odrzucona: Odrzucenia i problemy.