Czym jest KSeF API i do czego służy firmie
Interfejs programistyczny KSeF udostępnia Ministerstwo Finansów. Służy do tego, żeby oprogramowanie firmy mogło rozmawiać z systemem bez ręcznego logowania do aplikacji podatnika. Przez interfejs można wysłać fakturę sprzedaży, sprawdzić jej status oraz zapytać o faktury, które wystawili na firmę kontrahenci.
Dla działu finansów najważniejsza jest druga funkcja, czyli odbiór faktur kosztowych. Według obecnych przepisów obowiązek odbioru faktur w KSeF obejmuje największych podatników od 1 lutego 2026, a pozostałych od 1 kwietnia 2026. Faktura wystawiona w KSeF dociera do nabywcy właśnie przez system, a nie przez wiadomość e-mail, więc ktoś albo coś musi ją stamtąd pobrać.
Interfejs działa na kilku środowiskach. Środowisko testowe służy do prób bez skutków prawnych, a produkcyjne obsługuje prawdziwe faktury. Firma, która zleca integrację, powinna sprawdzić aktualną dokumentację techniczną opublikowaną przez Ministerstwo Finansów, bo specyfikacja jest rozwijana.
Token KSeF i certyfikat, czyli jak interfejs poznaje firmę
Zanim program pobierze jakąkolwiek fakturę, musi się uwierzytelnić. Według obecnych zasad robi to na dwa główne sposoby. Pierwszy to token KSeF, czyli ciąg znaków wygenerowany przez osobę z odpowiednimi uprawnieniami w aplikacji podatnika. Drugi to certyfikat KSeF, którego używa się podobnie jak klucza do podpisywania żądań.
Token ma jedną dużą zaletę praktyczną. Można nadać mu wąski zakres uprawnień, na przykład wyłącznie do odczytu faktur. Dzięki temu osoba albo narzędzie, które go używa, nie wystawi faktury w imieniu firmy i nie zmieni jej ustawień. W Oplacam stosujemy dokładnie taką zasadę, a szczegóły opisujemy na stronie bezpieczeństwo tokenu KSeF.
Kilka zasad ostrożności dotyczy każdego tokenu:
- generuj go tylko z uprawnieniem do odczytu faktur, jeśli samo pobieranie wystarcza,
- zapisz datę wygenerowania i osobę, która go utworzyła,
- unieważnij token, gdy zmienia się osoba odpowiedzialna za finanse,
- nie wysyłaj tokenu e-mailem ani komunikatorem w jawnej postaci.
Jak wygląda pobieranie faktur zakupowych przez interfejs
Pobieranie opiera się na zapytaniu o faktury, w którym podaje się rolę podmiotu i zakres dat. Dla faktur kosztowych firma występuje jako nabywca. System zwraca listę faktur wraz z numerami KSeF, a potem można pobrać treść każdej z nich w formacie XML, zgodnym ze schematem FA(3).
Numer KSeF to unikalny identyfikator faktury nadany przez system, składający się z 35 znaków. Zawiera między innymi numer NIP sprzedawcy i datę. Jest ważny z dwóch powodów. Po pierwsze, jednoznacznie wskazuje dokument, więc pozwala uniknąć dublowania zapłat. Po drugie, według obecnych przepisów trafia do tytułu przelewu przy płatnościach z mechanizmem podzielonej płatności od 2026 roku, a w pozostałych od 1 stycznia 2027. Więcej o tym piszemy w poradniku numer KSeF w przelewie.
Przy pobieraniu trzeba pamiętać o kilku praktycznych kwestiach:
- zapytania wykonuje się cyklicznie, bo faktury pojawiają się przez cały dzień,
- zakres dat powinien się lekko nakładać, żeby żadna faktura nie umknęła,
- te same faktury nie mogą być przetwarzane dwa razy,
- system ma limity liczby zapytań, więc masowe pobieranie wymaga rozsądnego tempa.
Własna integracja czy gotowe narzędzie
Firma, która ma programistów, może napisać własne połączenie z interfejsem. To sensowne wtedy, gdy faktury mają trafiać prosto do systemu ERP o niestandardowej budowie. Trzeba jednak policzyć koszt, który nie kończy się na pierwszej wersji. Specyfikacja zmienia się, schemat faktury ma kolejne wersje, a ktoś musi pilnować tokenów, limitów i błędów odpowiedzi.
Druga droga to gotowe narzędzie, które pobiera faktury w imieniu firmy po otrzymaniu tokenu. Takie rozwiązanie opisujemy w tekście o odbiorze faktur zakupowych z KSeF. Księgowa dostaje listę faktur bez pisania kodu i bez śledzenia zmian w dokumentacji.
Do wyboru warto zadać sobie pytania:
- ile faktur kosztowych firma odbiera miesięcznie,
- czy potrzebny jest eksport do programu księgowego, a w jakim formacie,
- kto ma zatwierdzać faktury przed zapłatą,
- czy pobranie faktury ma się kończyć na liście, czy na gotowym przelewie.
Jeśli odpowiedź na ostatnie pytanie brzmi, że na przelewie, to sam interfejs nie wystarczy. Zwraca on dokumenty, ale nie sprawdza rachunków kontrahentów ani nie układa plików dla banku.
Co zrobić z fakturą po pobraniu przez API
Pobrana faktura to plik XML, czyli tekst, którego nikt nie chce czytać gołym okiem. Najpierw trzeba z niego zrobić czytelny dokument z danymi sprzedawcy, pozycjami, kwotami, terminem płatności i rachunkiem. Taki podgląd opisuje strona o wizualizacji faktury KSeF.
Następnie zaczyna się część, której interfejs nie obejmuje, a która decyduje o pieniądzach:
- sprawdzenie, czy rachunek sprzedawcy figuruje w wykazie podatników VAT na dzień zapłaty,
- ocena, czy płatność podlega mechanizmowi podzielonej płatności,
- wpisanie numeru KSeF do tytułu przelewu tam, gdzie wymagają tego przepisy,
- wykrycie duplikatu albo zmiany rachunku względem poprzednich faktur tego kontrahenta,
- przygotowanie pliku do importu w bankowości firmowej.
Oplacam łączy te kroki w jedną ścieżkę. Faktura z KSeF zamienia się w sprawdzoną paczkę przelewów, a plik w formacie Elixir-O, CSV albo XML ISO 20022 importujesz i zatwierdzasz w swoim banku. Nie prosimy o dostęp do konta bankowego. Dokładny przebieg opisuje strona jak to działa, a sam plik opisuje podstrona o paczce przelewów.
Jak wybrać sposób korzystania z KSeF API
Prosty schemat decyzji wygląda tak. Jeśli firma wystawia i odbiera niewiele faktur, a księgowa i tak przepisuje przelewy, wystarczy narzędzie do odbioru z gotową paczką przelewów. Jeśli faktur jest setki i trzeba je akceptować w kilku rolach, potrzebny jest obieg z progami kwot, o którym piszemy w materiale o obiegu faktur kosztowych. Własną integrację warto rozważyć dopiero wtedy, gdy dane mają płynąć automatycznie do systemu, którego żadne gotowe narzędzie nie obsługuje.
W każdym wariancie pamiętaj o trzech sprawach. Token powinien mieć minimalne uprawnienia. Pobieranie trzeba monitorować, bo brak faktury w systemie księgowym to realny problem z terminem płatności. A płatność powinna przechodzić kontrolę przed wysłaniem, ponieważ błąd w rachunku kosztuje więcej niż czas poświęcony na sprawdzenie.
Plany z cennika zaczynają się od 249 zł netto miesięcznie za jeden NIP i do 300 faktur kosztowych, a szczegóły znajdziesz na stronie cennika. Informacje prawne w tym wpisie mają charakter ogólny i według obecnych przepisów, więc w razie wątpliwości sprawdź aktualne komunikaty Ministerstwa Finansów albo zapytaj doradcę podatkowego.