API KSeF — jak działa i jak zacząć integrację

Krótka odpowiedź: API KSeF to interfejs REST (HTTPS, komunikaty XML), przez który oprogramowanie wystawia i pobiera faktury bez logowania do portalu MF. Przepływ: uwierzytelnienie (token wygenerowany przez uprawnionego użytkownika lub podpis w sesji interaktywnej) → wysyłka faktury w FA(3) → walidacja → numer KSeF-ID i UPO → pobieranie dokumentów zakupowych zapytaniami. Poniżej elementy integracji i typowe pułapki.

Budowa integracji — z czego się składa

• Uwierzytelnienie: sesja tokenowa (standard automatyzacji — token generuje użytkownik z uprawnieniami w KSeF) albo interaktywna (podpis/pieczęć); token podróżuje w nagłówkach żądań.
• Wysyłka i status: żądania typu SendInvoice + odpytywanie o status przetworzenia; dokument przyjęty dostaje KSeF-ID i UPO.
• Pobieranie zakupowych: zapytania (Query) filtrowane datami/kontrahentem — podstawa automatycznego odbioru kosztów.
• Sesje i logi: każda operacja ma identyfikator — przechowuj je, to dowód w sporach o moment wystawienia.

Środowiska i testy

MF udostępnia środowiska testowe (demo/przedprodukcyjne) z fikcyjnymi danymi — integrację buduje się tam, produkcja na końcu. Dokumentacja API, schemy XSD FA(3) i przykładowe komunikaty są publikowane na podatki.gov.pl/ksef; przykładowe pliki faktur omawiamy w artykule o przykładowym pliku XML, a architekturę całości — w przewodniku po architekturze KSeF.

Typowe pułapki integracji

Najczęstsze problemy zgłaszane przez zespoły: wygasające sesje przy wolumenach (potrzebne odnawianie), rozjazd wersji schemy po przejściu FA(2)→FA(3), brak obsługi trybów offline (kolejkowanie i dosyłanie), traktowanie odpowiedzi „przyjęto do przetworzenia” jak „wystawiono” (status trzeba odpytać do końca). Dobra integracja loguje pełny cykl życia dokumentu.

Budować samemu czy wziąć gotowe?

Własna integracja ma sens przy ERP i niestandardowych procesach. Jeśli potrzebujesz po prostu wystawiać i odbierać faktury — Mizzox ma tę integrację gotową i utrzymywaną (zmiany schem po naszej stronie) — pierwsza faktura przez API w 3 minuty od rejestracji, bez pisania kodu.

Szerzej w przewodniku: KSeF 2026 — kompletny przewodnik.

W praktyce: jak Mizzox obsługuje KSeF.

FAQ

Jak uwierzytelnia się w API KSeF?

Tokenem wygenerowanym przez uprawnionego użytkownika (sesje automatyczne) albo podpisem/pieczęcią w sesji interaktywnej; token przesyła się w nagłówkach żądań.

Gdzie testować integrację z KSeF?

W środowiskach testowych MF (demo/przedprodukcyjne) na fikcyjnych danych — dokumentacja i schemy FA(3) są na podatki.gov.pl/ksef.

Kiedy faktura wysłana przez API jest wystawiona?

Po przyjęciu przez system i nadaniu KSeF-ID — odpowiedź „przyjęto do przetworzenia” to jeszcze nie wystawienie; status trzeba odpytać.