Jak działa składanie

Faktura ze Stripe trafia do KSeF bez Twojego udziału. Oto cały przepływ.

Kto jest nabywcą? To pierwsza rzecz, którą rozstrzygamy. Jeśli klient ma identyfikator podatkowy (polski NIP, numer VAT UE albo zagraniczny identyfikator podatkowy), to faktura B2B i trafia do KSeF. Jeśli identyfikatora nie ma, to konsument prywatny (B2C) — poza zakresem KSeF, więc jej nie składamy.

Pipeline

1. 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.
2. 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”).
3. Sesja online KSeF — otwieramy sesję, szyfrujemy fakturę (RSA-OAEP + AES-256-CBC, dokładnie jak wymaga KSeF), wysyłamy i odpytujemy o status.
4. UPO — po przyjęciu KSeF zwraca numer KSeF i podpisane UPO (urzędowe poświadczenie odbioru). To jest dowód prawny złożenia.
5. 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 — więc 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.

Co widzisz na ekranie

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

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 razach 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 — 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 — 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.

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, 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 — koniec okresu rozliczeniowego; 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

Mailujemy właściciela tylko o dwóch rzeczach wartych przerwania: odrzucenie (trzeba zadziałać) oraz złożenie, które właśnie wyczerpało darmowy limit (raz, na granicy). Zobacz Plany i limity.

Gdy faktura zostanie odrzucona: Odrzucenia i problemy.