KSeF API — integracja ze Stripe krok po kroku (i dlaczego Stripto robi to za Ciebie)

KSeF API wymaga autoryzacji tokenem sesyjnym. Żeby go uzyskać, musisz się uwierzytelnić jedną z trzech metod:

• Podpis Zaufany (profil zaufany) — interaktywny, nie da się zautomatyzować
• Podpis kwalifikowany — wymaga fizycznego tokenu USB lub karty kryptograficznej
• Pieczęć kwalifikowana — jedyna opcja sensowna do automatyzacji (M2M), ale wymaga zakupu certyfikatu od kwalifikowanego dostawcy

Token sesyjny ma ograniczony czas życia. Musisz zaimplementować odświeżanie, obsługę wygaśnięcia i bezpieczne przechowywanie poświadczeń. To nie jest Authorization: Bearer <token> — flow jest znacznie bardziej skomplikowany niż typowe REST API.

Faktura ustrukturyzowana to plik XML zgodny ze schematem FA(2) opublikowanym przez MF. Schemat definiuje kilkadziesiąt pól — wiele obowiązkowych, z rygorystyczną walidacją. Przykładowa struktura (uproszczona):

<Faktura xmlns="...">
  <Naglowek>
    <KodFormularza>FA</KodFormularza>
    <WariantFormularza>2</WariantFormularza>
    <DataWytworzeniaFa>2026-03-04T10:00:00</DataWytworzeniaFa>
  </Naglowek>
  <Podmiot1>  <!-- Sprzedawca -->
    <DaneIdentyfikacyjne>
      <NIP>1234567890</NIP>
      <Nazwa>Twoja Firma Sp. z o.o.</Nazwa>
    </DaneIdentyfikacyjne>
    <Adres> ... </Adres>
  </Podmiot1>
  <Podmiot2>  <!-- Nabywca -->
    <DaneIdentyfikacyjne> ... </DaneIdentyfikacyjne>
  </Podmiot2>
  <Fa>
    <P_1>2026-03-04</P_1>     <!-- Data wystawienia -->
    <P_2>FV 42/03/2026</P_2>  <!-- Numer faktury -->
    <P_15>500.00</P_15>        <!-- Kwota netto -->
    <P_16>true</P_16>          <!-- Czy jest VAT -->
    <FaWiersz>
      <NrWierszaFa>1</NrWierszaFa>
      <P_7>Usługa SaaS</P_7>
      <P_8A>szt.</P_8A>
      <P_8B>1</P_8B>
      <P_9A>500.00</P_9A>
      <P_11>500.00</P_11>
      <P_12>23</P_12>          <!-- Stawka VAT -->
    </FaWiersz>
  </Fa>
</Faktura>

To wersja uproszczona — pełny schemat ma ponad 300 pól. Pominięcie wymaganego elementu, zły format daty, niepoprawny NIP — i walidacja odrzuca całą fakturę. Musisz znać schemat XSD i testować przeciwko niemu każdą wygenerowaną fakturę.

Po przyjęciu faktury KSeF zwraca UPO — potwierdzenie z unikalnym numerem KSeF i timestampem. Musisz:

• Pobrać UPO asynchronicznie (wysyłka i potwierdzenie to osobne endpointy)
• Przechowywać UPO jako dowód wystawienia
• Obsłużyć scenariusz, gdy UPO nie przychodzi (timeout, awaria KSeF)

MF udostępnia sandbox na ksef-demo.mf.gov.pl. Możesz testować wysyłkę faktur bez skutków prawnych. Autoryzacja w sandboxie działa na uproszczonych tokenach. Przygotuj się na to, że środowisko testowe bywa niestabilne — timeout i błędy 5xx nie są rzadkością.