Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak płatność w Stripe zamienia się w fakturę FA(3)
Stripe wysyła zdarzenie invoice.paid, gdy faktura za subskrypcję lub jednorazowy zakup zostanie opłacona. Integracja pobiera pełną fakturę przez API Stripe, razem z pozycjami, rabatami, podatkiem i danymi klienta, i buduje z niej dokument w schemie FA(3). Płatności bez faktury w Stripe (na przykład jednorazowe Checkout Sessions bez włączonego tworzenia faktur) obsługuję osobno, ze zdarzenia o udanej płatności. Do Stripe łączę się kluczem z ograniczonymi uprawnieniami (restricted key), a do KSeF tokenem lub certyfikatem z Twojego KSeF, z uprawnieniem tylko do wystawiania faktur.
NIP nabywcy pochodzi z pola Tax ID klienta w Stripe. Integracja sprawdza go w wykazie podatników VAT (Biała lista) dla firm z Polski i w VIES dla firm z UE, a nazwę i adres firmy uzupełnia z rejestru. Dzięki temu literówka z formularza nie trafia na fakturę.
Co wraca do Stripe
Po przyjęciu faktury KSeF nadaje jej numer. Integracja zapisuje go w metadanych faktury w Stripe razem z datą przyjęcia i linkiem do PDF. Obok zapisuje UPO, czyli urzędowe poświadczenie odbioru faktury przez KSeF. Obsługa i Twoja aplikacja widzą numer KSeF bez logowania do KSeF, a klient dostaje e-mail z fakturą w PDF i kodem QR do weryfikacji.
Subskrypcje, zmiany planów i korekty
Odnowienie subskrypcji to po prostu kolejna opłacona faktura, więc przechodzi tą samą drogą. Proporcjonalne rozliczenia (proration) przy zmianie planu, okresy próbne, kupony i saldo klienta przechodzą na fakturę jako osobne pozycje, tak żeby suma zgadzała się z kwotą pobraną przez Stripe. Rozliczenie za zużycie (metered billing) też kończy się fakturą w Stripe, więc idzie tą samą drogą.
Credit note w Stripe (credit_note.created) uruchamia fakturę korygującą, która wskazuje numer KSeF faktury pierwotnej. Korekta obejmuje tylko te pozycje i kwoty, które zawiera credit note. Moment wystawienia faktury przy usługach ciągłych i ewentualne faktury zaliczkowe ustalamy z księgową przed startem, bo to decyzja podatkowa, a nie techniczna.
Gdy KSeF nie działa
Każda faktura przechodzi przez kolejkę z ponowieniami. Chwilowy błąd API oznacza kolejną próbę, a nie zgubioną fakturę. Gdy fakturę trzeba wydać bez KSeF, integracja wystawia ją w trybie offline. Tryby offline24, niedostępności i awarii to technicznie ta sama ścieżka z innym terminem dosłania. Faktura dostaje dwa kody QR, z których drugi jest podpisany certyfikatem KSeF, a integracja pilnuje terminu i dosyła ją sama.