API KSeF — jak podłączyć własne oprogramowanie

Każdy program księgowy, który wysyła faktury do KSeF, robi to przez API — interfejs programistyczny, który pozwala systemom informatycznym "rozmawiać" ze sobą. Dla większości przedsiębiorców API działa w tle — niewidocznie i bezproblemowo. Ale jeśli masz niestandardowe oprogramowanie, budujesz własne integracje lub po prostu chcesz zrozumieć, jak KSeF działa "pod maską" — ten artykuł jest dla Ciebie.

Czym jest API KSeF

API (Application Programming Interface) to zestaw reguł i narzędzi, które pozwalają jednemu systemowi informatycznemu komunikować się z drugim. API KSeF to interfejs udostępniony przez Ministerstwo Finansów, przez który programy zewnętrzne (programy księgowe, systemy ERP, narzędzia do monitoringu) mogą wystawiać faktury w KSeF, pobierać je i sprawdzać ich status.

Nie musisz znać API, żeby korzystać z KSeF. Jeśli używasz programu księgowego z wbudowaną integracją — API działa w tle. Ale jeśli masz własne oprogramowanie, budujesz niestandardowy obieg dokumentów lub chcesz zintegrować KSeF z narzędziem do monitoringu płatności czy windykacji — znajomość API jest niezbędna.

Co możesz zrobić przez API KSeF

API KSeF udostępnia zestaw operacji, które pokrywają pełny cykl życia faktury — od wystawienia po archiwizację. Oto najważniejsze z nich.

Wystawianie faktur

Wysyłasz dokument XML (zgodny ze schematem FA(2)) do KSeF. System waliduje go, nadaje numer KSeF i zwraca potwierdzenie. Od tego momentu faktura jest oficjalnie wystawiona i doręczona nabywcy.

Pobieranie faktur

Jako nabywca możesz automatycznie pobierać faktury zakupowe wystawione na Twój NIP. API pozwala filtrować faktury po dacie, NIP-ie sprzedawcy i zakresie czasowym. To fundament automatycznego importu faktur zakupowych do programu księgowego.

Sprawdzanie statusu

Po wysłaniu faktury możesz sprawdzić, czy została przyjęta (nadano numer) czy odrzucona (z komunikatem błędu). Możesz też pobrać UPO — urzędowe poświadczenie odbioru, które potwierdza przyjęcie dokumentu.

Pobieranie UPO

Urzędowe poświadczenie odbioru to elektroniczny dokument potwierdzający, że KSeF przyjął Twoją fakturę. UPO zawiera numer KSeF, datę i godzinę przyjęcia oraz skrót kryptograficzny dokumentu. To Twój dowód, że faktura została wystawiona i doręczona.

Zarządzanie uprawnieniami

Przez API możesz nadawać i odbierać tokeny autoryzacyjne — uprawnienia do wystawiania i pobierania faktur w imieniu Twojej firmy. To ważne przy automatyzacji: system (np. program księgowy) uwierzytelnia się tokenem, nie loginem i hasłem.

Kto potrzebuje bezpośredniej integracji z API

Nie każda firma musi samodzielnie integrować się z API KSeF. W większości przypadków wystarczy program księgowy z wbudowanym modułem. Bezpośrednia integracja z API ma sens w specyficznych sytuacjach.

Potrzebujesz API, jeśli:

• Masz własne oprogramowanie — autorski system ERP, CRM z modułem fakturowym lub niestandardowe narzędzie, które nie korzysta z gotowych programów księgowych
• Budujesz narzędzie dla klientów — tworzysz SaaS, platformę e-commerce lub system dla branży, który musi wystawiać faktury w imieniu użytkowników
• Potrzebujesz niestandardowego obiegu — np. automatyczne wystawianie faktur na podstawie zamówień w sklepie internetowym, integracja KSeF z systemem monitoringu płatności czy CRM
• Wystawiasz bardzo dużo faktur — tysiące miesięcznie, gdzie wysyłka wsadowa (batch) przez API jest konieczna ze względu na wydajność

Nie potrzebujesz API, jeśli:

• Korzystasz z programu księgowego z modułem KSeF — program obsługuje API w tle, Ty korzystasz z interfejsu graficznego
• Wystawiasz kilkadziesiąt faktur miesięcznie — standardowa integracja przez program księgowy wystarczy
• Nie masz zespołu IT — integracja z API wymaga programisty. Jeśli go nie masz, korzystaj z gotowych rozwiązań

Jak wygląda integracja z API — krok po kroku

Jeśli zdecydujesz się na bezpośrednią integrację (bo masz własne oprogramowanie lub budujesz narzędzie), oto jak przebiega ten proces.

1. Zapoznaj się z dokumentacją — Ministerstwo Finansów publikuje pełną dokumentację API KSeF, zawierającą specyfikację endpointów, parametry zapytań, formaty odpowiedzi i schemat FA(2). To Twój punkt wyjścia.
2. Zarejestruj się w środowisku testowym — KSeF udostępnia środowisko demo (sandbox), w którym możesz testować integrację bez ryzyka. Wystawiasz testowe faktury, sprawdzasz odpowiedzi API i debugujesz problemy.
3. Zaimplementuj autoryzację — API wymaga uwierzytelniania. Musisz zaimplementować obsługę tokenów autoryzacyjnych — generowanie, odnawianie i przechowywanie. To krytyczny element bezpieczeństwa.
4. Zbuduj generowanie XML — Twój system musi tworzyć faktury w formacie XML zgodnym ze schematem FA(2). To najczęstsze źródło błędów — testuj generowany XML walidatorem zanim wyślesz do KSeF.
5. Zaimplementuj wysyłkę i odbiór — wystawianie faktur (POST), pobieranie faktur (GET), sprawdzanie statusu, pobieranie UPO. Obsłuż zarówno odpowiedzi pozytywne, jak i błędy.
6. Dodaj obsługę błędów i retry — API może zwrócić błąd (np. serwer KSeF niedostępny). Twój system musi obsłużyć takie sytuacje — ponawiać próby, logować błędy, powiadamiać administratora.
7. Przetestuj kompleksowo — faktura zwykła, korekta, faktura walutowa, split payment, wysyłka wsadowa. Pokryj wszystkie scenariusze zanim przejdziesz na produkcję.
8. Przejdź na środowisko produkcyjne — po pozytywnych testach przełącz integrację na produkcyjne API KSeF. Monitoruj pierwsze faktury szczególnie uważnie.

Środowisko testowe vs. produkcyjne

Ministerstwo Finansów udostępnia dwa środowiska API KSeF — testowe (sandbox) i produkcyjne. Różnica jest kluczowa.

API KSeF a narzędzia do monitoringu i windykacji

API KSeF to nie tylko narzędzie do wystawiania faktur. To źródło danych, które zasila cały ekosystem zarządzania należnościami — od monitoringu płatności po automatyczną windykację.

Jak Paido wykorzystuje API KSeF

Paido korzysta z API KSeF do automatycznego pobierania faktur sprzedażowych. Proces wygląda tak:

• Paido regularnie odpytuje API KSeF o nowe faktury wystawione na Twój NIP (jako sprzedawca)
• Nowe faktury są automatycznie importowane do systemu monitoringu
• System odczytuje termin płatności, kwotę, dane kontrahenta z XML
• Uruchamia sekwencję monitoringową — przypomnienia, wezwania, odsetki
• Aktualizuje dane przy korektach pobranych z KSeF

Dla Ciebie jako użytkownika cały ten proces jest niewidoczny — aktywujesz integrację jednym kliknięciem i system zaczyna działać. Ale "pod spodem" to właśnie API KSeF dostarcza dane, które napędzają monitoring i windykację.

Bezpieczeństwo API KSeF

API KSeF przetwarza wrażliwe dane finansowe — NIP-y, kwoty, dane kontrahentów. Bezpieczeństwo integracji to nie opcja, to konieczność.

Mechanizmy bezpieczeństwa

• Szyfrowanie transmisji (TLS/SSL) — komunikacja między Twoim systemem a API KSeF jest szyfrowana. Dane nie mogą być przechwycone w trakcie przesyłania.
• Autoryzacja tokenem — każde zapytanie do API musi zawierać ważny token autoryzacyjny. Bez tokena — brak dostępu.
• Podpis kryptograficzny — faktury wysyłane do KSeF mogą być podpisane elektronicznie, co gwarantuje ich integralność (nikt nie zmienił treści po wysłaniu).
• Logi i audyt — KSeF rejestruje każdą operację: kto, kiedy i jaką fakturę wystawił lub pobrał. To ścieżka audytowa na wypadek sporów.

Twoje obowiązki bezpieczeństwa

• Przechowuj tokeny bezpiecznie — nie w kodzie źródłowym, nie w e-mailu, nie w arkuszu. Używaj bezpiecznych magazynów (np. menedżer haseł, vault).
• Odnawiaj tokeny regularnie — wygasły token to zablokowany dostęp. Automatyzuj odnawianie lub ustaw przypomnienia.
• Ograniczaj uprawnienia — nadawaj tokeny tylko osobom i systemom, które ich potrzebują. Stosuj zasadę minimalnych uprawnień.
• Monitoruj aktywność — sprawdzaj, kto i kiedy korzystał z API w imieniu Twojej firmy. Nietypowa aktywność może oznaczać naruszenie bezpieczeństwa.

Alternatywy dla bezpośredniej integracji z API

Jeśli nie chcesz (lub nie możesz) budować bezpośredniej integracji z API KSeF, masz kilka alternatyw.

Program księgowy z wbudowaną integracją

Najprostsza opcja — wybierasz program, który obsługuje KSeF "z pudełka". Ty wystawiasz faktury w interfejsie graficznym, program obsługuje API w tle. Szczegółowy przegląd programów znajdziesz w artykule o integracji KSeF z programem księgowym.

Bramka KSeF (middleware)

Usługi pośredniczące, które przyjmują faktury z Twojego systemu (w prostszym formacie — np. CSV, JSON) i formatują je do XML zgodnego z KSeF. To opcja dla firm z niestandardowym oprogramowaniem, które nie chcą budować pełnej integracji.

Aplikacja webowa Ministerstwa Finansów

Darmowe narzędzie do ręcznego wystawiania faktur w KSeF — bez API, bez integracji. Wpisujesz dane w formularz na stronie, system generuje XML. Sprawdza się przy kilku fakturach miesięcznie, ale nie nadaje się do automatyzacji.

FAQ — najczęściej zadawane pytania