REST API do fakturowania i KSeF dla twórców oprogramowania
Zbuduj fakturowanie wprost na produkcie, zamiast budować je od zera. REST API Fakturni pozwala wystawiać faktury i wysyłać dokumenty ustrukturyzowane do KSeF z poziomu Twojego kodu, a całą zgodność ze schemą FA(3), certyfikaty i obieg dokumentów bierzemy na siebie.
To rozwiązanie dla zespołów, które wolą jedno wywołanie API od kilku miesięcy walki z wymaganiami Ministerstwa Finansów. Pierwszą fakturę wystawisz w kilka minut, a integrację domkniesz w kilka dni.
W skrócie
- REST API Fakturni pozwala wystawiać faktury i wysyłać je do KSeF bezpośrednio z Twojej aplikacji
- Jest dla twórców SaaS, aplikacji klienckich z wysyłką faktur do KSeF oraz firm automatyzujących własne fakturowanie
- Własna, w pełni zgodna integracja z KSeF i jej rzetelne przetestowanie na produkcji to realnie kilka miesięcy pracy
- Dostajesz lekkie, przyjazne API, gotowy do użycia pakiet TypeScript @fakturnia/api-client i środowisko testowe (sandbox)
- Dokumentacja jest czytelna zarówno dla ludzi, jak i dla agentów AI, dzięki czemu wdrożenie ruszysz od razu
Dla kogo jest REST API Fakturni?
Fakturowanie i KSeF to ten sam, powtarzalny problem niezależnie od tego, co budujesz. Dlatego API zaprojektowaliśmy z myślą o trzech grupach, które najczęściej pytają nas o integrację.
Twórcy SaaS z Polski
Budujesz produkt subskrypcyjny i chcesz, żeby Twoi klienci dostawali poprawne faktury, a Ty obsługiwać własne rozliczenia przez Fakturnię. Podłączasz API i fakturowanie przestaje być Twoim problemem.
Aplikacje klienckie z KSeF
Tworzysz aplikację, w której faktury Twoich klientów muszą trafiać do KSeF. Zamiast budować integrację dla każdego podmiotu osobno, wysyłasz dokumenty ustrukturyzowane przez jedno spójne API.
Firmy automatyzujące fakturowanie
Budujesz narzędzia i oprogramowanie wewnętrzne we własnej firmie i chcesz zautomatyzować wystawianie faktur oraz wysyłkę dokumentów ustrukturyzowanych do KSeF. API wpina się w Twoje procesy bez ręcznej pracy.
Zgodna integracja z KSeF to miesiące pracy
Na papierze brzmi to prosto: wystaw fakturę i wyślij ją do KSeF. W praktyce samodzielne dojście do w pełni zgodnej, stabilnej integracji to jeden z tych projektów, które zawsze trwają dłużej, niż zakłada plan. Nie dlatego, że ktoś źle programuje, tylko dlatego, że wymagań jest naprawdę dużo.
Po drodze trzeba zmierzyć się między innymi z:
- generowaniem poprawnego XML zgodnego ze schemą FA(3) i jej kolejnymi wersjami,
- certyfikatami, ich przeznaczeniem, uprawnieniami i odnawianiem,
- asynchronicznym przyjmowaniem dokumentów, statusami przetwarzania i numerem KSeF,
- obsługą błędów, ponawianiem żądań, limitami zapytań i przypadkami brzegowymi,
- deterministycznym liczeniem kwot i zaokrągleń, tak aby sumy zgadzały się co do grosza.
Samo napisanie kodu to jedno. Drugie, znacznie trudniejsze, to rzetelne przetestowanie integracji w środowisku produkcyjnym, na realnych typach dokumentów, korektach i fakturach zaliczkowych. To etap, który realnie zajmuje kilka miesięcy, zanim zacznie się ufać, że nic nie przepadnie i wszystko jest zgodne z przepisami.
Rozwiązanie: zbuduj swój produkt na Fakturni
Zamiast budować i utrzymywać tę warstwę samodzielnie, oprzyj produkt na gotowej, sprawdzonej infrastrukturze. Ty przesyłasz proste dane faktury, a Fakturnia odpowiada za zgodność ze schemą, obieg dokumentu i komunikację z KSeF.
Dzieli się to na trzy rzeczy, o które nie musisz się już martwić:
Zgodność z KSeF
XML FA(3), certyfikaty, statusy i numer KSeF obsługiwane po naszej stronie.
Obliczenia kwot
Przesyłasz cenę i stawkę VAT, backend liczy netto, VAT i brutto co do grosza.
Lekki interfejs
Czysty REST + JSON, spójna koperta odpowiedzi i stabilne kody błędów.
Efekt jest taki, że zespół skupia się na swoim produkcie, a nie na przepisach. To samo podejście, które znasz z dobrych API płatności: złożoność jest schowana za prostym wywołaniem.
Pierwsza faktura w kilka minut
Nie musisz najpierw tworzyć kontrahenta. Przekazujesz osadzony obiekt nabywcy, a Fakturnia odnajdzie go lub utworzy za Ciebie. Sprzedawca jest zawsze pobierany z profilu Twojej firmy. Poniżej to samo żądanie w czystym HTTP i w SDK.
Odpowiedź zwraca documentNumber oraz wyliczone netSum, vatSum i grossSum w spójnej kopercie. PDF pobierzesz osobnym wywołaniem, a fakturę wyślesz do KSeF przez /send-to-ksef.
Klient sam pobiera i buforuje tokeny OAuth. Nieprawidłowy ładunek nie przejdzie kompilacji, więc wiele błędów wychwycisz, zanim cokolwiek wyślesz.
Typowany SDK TypeScript gotowy do użycia
Oficjalny pakiet @fakturnia/api-client jest generowany z tej samej specyfikacji OpenAPI co API, więc kształty żądań i odpowiedzi nie mogą rozjechać się z backendem. Instalujesz go jedną komendą:
- Automatyczna obsługa tokenów. Klient sam pobiera i buforuje tokeny OAuth 2.0, więc nie zajmujesz się ich rotacją.
- Buildery dla trudniejszych typów.createVatInvoice, korekty z productsFromDocument, buyer.byId / byData i payment.unpaid / paid.
- Unie rozłączne. Niedozwolone stany nie przejdą kontroli typów, na przykład faktura zaliczkowa bez powiązanego zamówienia.
- Czytelne błędy.FakturniaApiError udostępnia .code oraz .fieldErrors z detalami per pole.
Nie pracujesz w TypeScript? API to zwykły REST + JSON z pełną specyfikacją OpenAPI 3, więc klienta wygenerujesz w dowolnym języku albo skorzystasz wprost z fetch czy requests.
Dokumentacja stworzona dla ludzi i agentów AI
Zależy nam, żeby wdrożenie ruszało od razu, niezależnie od tego, czy kod pisze człowiek, czy asystent AI. Dlatego dokumentację zaprojektowaliśmy z myślą o czytelności maszynowej w pierwszej kolejności. Pełna treść każdej strony jest w odpowiedzi HTML renderowanej po stronie serwera, więc nic nie wymaga uruchamiania JavaScriptu.
Dla agentów, botów i generatorów kodu udostępniamy gotowe artefakty:
- /llms-full.txt: cały korpus dokumentacji połączony w jeden plik Markdown, czyli pełny tekst witryny dla agenta.
- /openapi.json: kanoniczny, wykonywalny kontrakt ze ścieżkami, parametrami, schematami i scope’ami.
- Każdy przewodnik dostępny też jako czysty Markdown pod adresem /<slug>.md.
W praktyce wygląda to tak, że wskazujesz swojemu agentowi dokumentację, a on potrafi wygenerować poprawne wywołania API od pierwszego podejścia. Najpierw na sandboxie, żeby potwierdzić, że wszystko działa, a potem na produkcji. Dzięki temu od pomysłu do działającego fakturowania jest naprawdę blisko.
Bezpieczne testy w środowisku sandbox
Zanim cokolwiek uruchomisz na produkcji, zacznij od sandboxa. To pełnoprawna, odizolowana kopia Fakturni, w której przetestujesz całą integrację, łącznie z wysyłką faktur do testowego KSeF, bez żadnych skutków prawnych ani podatkowych.
Jest to szczególnie ważne, gdy kod współtworzy asystent AI: najpierw potwierdzasz, że wszystko działa w sandboxie, a dopiero potem przełączasz się na produkcję. W SDK to po prostu zmiana environment z 'sandbox' na 'production' oraz użycie produkcyjnych danych i certyfikatu.
Dzięki temu masz pewność, że pierwsza prawdziwa faktura wystawiona z Twojej aplikacji jest dokładnie taka, jakiej oczekujesz.
Potrzebujesz wsparcia przy integracji?
Jeśli chcesz omówić swój przypadek, dobrać odpowiednie scope’y, przejść przez konfigurację KSeF albo zweryfikować pierwsze wdrożenie, napisz do nas. Odpowiadają osoby, które na co dzień rozwijają to API, a wsparcie jest po polsku.
kontakt@fakturnia.plNajczęściej zadawane pytania
Nie masz jeszcze konta? Zacznij już dziś
Dołącz do tysięcy przedsiębiorców, którzy wybrali Fakturnię. Załóż konto w 30 sekund, bez zobowiązań.