Jak działa składanie

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

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, a kwoty rozbijamy na pozycje VAT.
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 na fakturze: w metadata (maszynowo) i dopisany do footer (widoczny dla nabywcy na PDF/stronie). custom_fields jest niemodyfikowalne po finalizacji, więc świadomie go nie używamy.

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.

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.