Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak płatność w Stripe zamienia się w fakturę w Fakturowni
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 wysyła do API Fakturowni (POST /invoices.json) gotową fakturę: nabywcę z NIP-em, pozycje z ilością, ceną i stawką VAT, walutę i status opłaconej. Płatności bez faktury w Stripe (na przykład Checkout Sessions bez włączonego tworzenia faktur) obsługuję osobno, ze zdarzenia o udanej płatności. Do Stripe integracja łączy się kluczem z ograniczonymi uprawnieniami (restricted key), a do Fakturowni kodem API z Twojego konta.
NIP nabywcy pochodzi z pola Tax ID klienta w Stripe albo z Twojej aplikacji, jeśli tam trzymasz dane firm. Jeśli firma jest już w Fakturowni, integracja podaje jej client_id, żeby nie mnożyć kontrahentów. Proporcjonalne rozliczenia 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.
KSeF zostaje w Fakturowni
Nie buduję własnej wysyłki do KSeF. Fakturownia ma ją wbudowaną: faktura z oznaczeniem, że nabywca jest firmą (buyer_company), idzie do KSeF automatycznie według ustawień konta albo na zlecenie z API (gov_save_and_send). Numer KSeF (gov_id) i status wysyłki (gov_status) przychodzą w webhooku Fakturowni, a integracja zapisuje je w metadanych płatności lub faktury w Stripe razem z numerem faktury i linkiem do PDF.
Zwroty i korekty
Credit note w Stripe (credit_note.created) albo zwrot płatności (charge.refunded) uruchamia w Fakturowni fakturę korygującą powiązaną z fakturą pierwotną (invoice_id). Fakturownia dopisuje do niej numer KSeF faktury korygowanej i wysyła korektę do KSeF. Korekta obejmuje tylko te pozycje i kwoty, które zawiera credit note lub zwrot. Moment wystawienia faktury przy usługach ciągłych ustalamy z księgową przed startem, bo to decyzja podatkowa, a nie techniczna.
Duplikaty i błędy
Identyfikator faktury lub płatności ze Stripe trafia do pola numeru zamówienia (oid) z włączoną unikalnością, więc ponowione zdarzenie ze Stripe nie wystawi drugiej faktury. Każde wywołanie przechodzi przez kolejkę z ponowieniami. Gdy Fakturownia odrzuci dane (np. brak NIP-u albo niepoprawna stawka VAT) lub KSeF zwróci błąd (gov_error_messages), faktura czeka, a Ty dostajesz alert e-mail z opisem błędu.