Wprowadzenie
Samodzielna integracja z KSeF to sporo roboty technicznej: po Twojej stronie leży XML w formacie FA(3), uwierzytelnianie, szyfrowana wysyłka i pilnowanie statusów. Gotowe API przyjmuje zwykły JSON i zdejmuje z Ciebie całą resztę. Dla sklepu internetowego czy zespołu SaaS to zwykle szybsza i tańsza droga, a własna budowa opłaca się dopiero wtedy, gdy fakturowanie elektroniczne jest sercem Twojego produktu.
Co tak naprawdę trzeba zrobić
KSeF (Krajowy System e-Faktur) to państwowa platforma e-fakturowania prowadzona przez Ministerstwo Finansów. Żeby wysłać fakturę programowo, trzeba po kolei:
- utworzyć ustrukturyzowany dokument w formacie FA(3), zgodny ze schematem XSD opublikowanym na crd.gov.pl (pola takie jak P_1 data wystawienia, P_2 numer faktury, P_15 kwota do zapłaty);
- uwierzytelnić się w KSeF — podpisując wyzwanie uwierzytelniające podpisem XAdES (kwalifikowanym podpisem lub pieczęcią albo certyfikatem KSeF) albo tokenem KSeF zaszyfrowanym kluczem publicznym Ministerstwa Finansów wraz ze znacznikiem czasu;
- otworzyć sesję i wysłać fakturę — uwaga, sam plik XML faktury nie jest podpisywany, tylko szyfrowany i wysyłany w sesji interaktywnej;
- odczytywać status aż do UPO, czyli urzędowego potwierdzenia odbioru.
Do tego dochodzi codzienne utrzymanie: archiwizacja faktur, reakcja na błędy, ponawianie wysyłki i nadążanie za nowymi wersjami schematu, które Ministerstwo od czasu do czasu publikuje. To stały koszt, a nie jednorazowy projekt.
Dlaczego zespoły wybierają gotowe API
Dostawca taki jak Notaly sprowadza cały ten proces do jednego wywołania. Wysyłasz fakturę w JSON na POST /invoices, a resztą zajmuje się on: generuje XML FA(3), waliduje go wobec XSD, uwierzytelnia się Twoim tokenem z Connect KSeF (bez pieczęci kwalifikowanej), wysyła zaszyfrowany dokument i zwraca status oraz UPO przez webhook. Nie piszesz XML-a ani XAdES-a i nie musisz śledzić zmian schematu.
Różnica sprowadza się do kontroli i pieniędzy. Własna budowa nie ma opłaty za pojedynczą fakturę, ale kosztuje tygodnie pracy programistów i wymaga stałego serwisu. Abonament API to wydatek, ale zwraca się od pierwszego dnia — dla zespołu, którego główny produkt nie jest e-fakturowaniem, to zwykle lepszy wybór.
Kiedy własna integracja ma sens
Buduj sam, jeśli prowadzisz w Polsce produkt do fakturowania albo księgowości, masz ludzi od XML-a i kryptografii oraz potrzebujesz rzeczy spoza standardowej wysyłki — na przykład własnego archiwum lub trybu offline. W innych przypadkach — sklep WooCommerce albo Shopify, silnik billingowy SaaS, dział finansów — API jest bezpieczniejszym domyślnym wyborem. Niezależnie od drogi, zacznij od środowiska testowego KSeF: wystawia ono faktury testowe według tego samego schematu FA(3), bez dotykania danych produkcyjnych.
Zastrzeżenie
Notaly nie jest doradcą podatkowym, księgowym ani prawnym. Ten artykuł ma charakter informacyjny, nie stanowi porady podatkowej i może być nieaktualny. Ponosisz odpowiedzialność za własne rozliczenia VAT; w razie potrzeby skonsultuj się z wykwalifikowanym księgowym.
Źródła
Źródło: www.podatki.gov.pl