KSeF API — dokumentacja, integracja, przykłady

Krajowy System e-Faktur udostępnia REST API, które pozwala programom zewnętrznym wystawiać, pobierać i wyszukiwać faktury. Jeśli budujesz integrację z KSeF — czy to we własnym systemie ERP, czy w SaaS-ie dla klientów — ten artykuł jest Twoim punktem wejścia.

Omówimy: środowiska, autoryzację, główne endpointy, przykłady kodu w JavaScript/Node.js, rate limity i typowe problemy.

Czym jest KSeF API?

KSeF API to interfejs REST udostępniany przez Ministerstwo Finansów. Pozwala na:

• Wyszukiwanie faktur — filtrowanie po dacie, NIP kontrahenta, typie (przychodzące/wychodzące)
• Pobieranie faktur — ściągnięcie pełnego XML faktury po numerze KSeF
• Wystawianie faktur — wysyłanie nowej faktury w formacie XML FA(3)
• Zarządzanie uprawnieniami — nadawanie/odwoływanie uprawnień do NIP-u

API jest bezpłatne. Nie ma opłat za liczbę zapytań. Jedyne ograniczenia to rate limity (opisane niżej).

Środowiska: test i produkcja

KSeF udostępnia dwa środowiska API:

Podczas developmentu zawsze używaj środowiska testowego. Przełącz na produkcję dopiero gdy integracja jest przetestowana i stabilna.

Autoryzacja — jak otworzyć sesję

Dostęp do API KSeF wymaga autoryzacji w dwóch krokach:

Krok 1: Wygeneruj token uwierzytelniający

Token generujesz ręcznie w Aplikacji Podatnika (ap.ksef.mf.gov.pl). Szczegółowa instrukcja: Token KSeF — jak wygenerować krok po kroku.

Krok 2: Otwórz sesję (programowo)

Z tokenem uwierzytelniającym wysyłasz request do endpointu inicjalizacji sesji. W odpowiedzi dostajesz session token (krótkoterminowy), którego używasz we wszystkich kolejnych requestach.

Endpoint inicjalizacji sesji:

Request wymaga podpisania challenge'a tokenem uwierzytelniającym. Po pomyślnej autoryzacji API zwraca:

• sessionToken — używany w nagłówku SessionToken kolejnych requestów
• referenceNumber — numer referencyjny sesji

Główne endpointy

Poniżej najważniejsze endpointy API KSeF, które będziesz potrzebować przy integracji.

Wyszukiwanie faktur

Pozwala wyszukać faktury wg kryteriów. Kluczowy parametr to subjectType:

• subject1 — faktury, w których jesteś sprzedawcą (wychodzące)
• subject2 — faktury, w których jesteś nabywcą (przychodzące)

Przykładowy request body:

{
  "queryCriteria": {
    "subjectType": "subject2",
    "type": "incremental",
    "acquisitionTimestampThresholdFrom": "2026-07-01T00:00:00",
    "acquisitionTimestampThresholdTo": "2026-07-22T23:59:59"
  }
}

Odpowiedź zawiera listę faktur z metadanymi: numer KSeF, NIP sprzedawcy, kwota brutto, data wystawienia.

Pobranie XML faktury

Pobiera pełny XML faktury po jej numerze KSeF. Zwraca dokument XML w formacie FA(3) — oficjalnym schemacie e-faktur.

Wystawienie faktury

Wysyła nową fakturę do KSeF. Wymaga przesłania poprawnego XML faktury w formacie FA(3). Po przyjęciu faktura otrzymuje numer KSeF i jest natychmiast widoczna dla nabywcy.

Przykład kodu: wyszukiwanie faktur przychodzących

Poniżej kompletny przykład w JavaScript (Node.js) — wyszukanie faktur przychodzących z ostatnich 7 dni:

const KSEF_BASE = 'https://ksef.mf.gov.pl/api';

async function queryIncomingInvoices(sessionToken) {
  const now = new Date();
  const weekAgo = new Date(now - 7 * 24 * 60 * 60 * 1000);

  const response = await fetch(
    `${KSEF_BASE}/v2/invoices/query`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'SessionToken': sessionToken,
      },
      body: JSON.stringify({
        queryCriteria: {
          subjectType: 'subject2',
          type: 'incremental',
          acquisitionTimestampThresholdFrom:
            weekAgo.toISOString(),
          acquisitionTimestampThresholdTo:
            now.toISOString(),
        },
      }),
    }
  );

  if (!response.ok) {
    throw new Error(
      `KSeF query failed: ${response.status}`
    );
  }

  const data = await response.json();
  return data.invoiceHeaderList || [];
}

// Użycie:
const invoices = await queryIncomingInvoices(token);
console.log(`Znaleziono ${invoices.length} faktur`);

for (const inv of invoices) {
  console.log(
    `${inv.invoicingDate} | ` +
    `${inv.subjectBy.issuedByName} | ` +
    `${inv.net} PLN netto | ` +
    `KSeF: ${inv.ksefReferenceNumber}`
  );
}

Pobranie XML faktury — przykład

Gdy znasz numer KSeF faktury, możesz pobrać jej pełny XML:

async function downloadInvoiceXml(
  sessionToken,
  ksefNumber
) {
  const response = await fetch(
    `${KSEF_BASE}/invoices/ksef/${ksefNumber}`,
    {
      headers: {
        'SessionToken': sessionToken,
        'Accept': 'application/xml',
      },
    }
  );

  if (!response.ok) {
    throw new Error(
      `Download failed: ${response.status}`
    );
  }

  return await response.text(); // XML string
}

Zwrócony XML zawiera wszystkie dane faktury: sprzedawca, nabywca, pozycje, stawki VAT, kwoty. Możesz go sparsować i zaimportować do swojego systemu księgowego.

Rate limity i ograniczenia

API KSeF ma ograniczenia, o których warto wiedzieć:

• Limit sesji — jedna aktywna sesja na token. Otwarcie nowej sesji zamyka poprzednią
• Timeout sesji — sesja wygasa po określonym czasie nieaktywności
• Rate limiting — zbyt wiele requestów w krótkim czasie może skutkować blokadą. MF nie publikuje dokładnych limitów, ale w praktyce odpytywanie co 10-15 minut nie sprawia problemów
• Rozmiar odpowiedzi — endpoint query zwraca wyniki stronicowane. Paginacja pozwala pobrać kolejne strony wyników
• Format danych — API przyjmuje i zwraca XML (faktury) oraz JSON (metadane, query). Musisz obsłużyć oba formaty

Typowe problemy przy integracji

Błąd 401 — Unauthorized

Token jest nieprawidłowy, wygasły lub sesja została zamknięta. Wygeneruj nowy token uwierzytelniający i otwórz nową sesję.

Błąd 400 — Bad Request

Nieprawidłowy format requestu. Sprawdź strukturę JSON/XML. Częsty błąd: zły format daty (KSeF wymaga ISO 8601).

Pusta odpowiedź z query

Sprawdź zakres dat i parametr subjectType. Jeśli szukasz faktur przychodzących, użyj subject2. Jeśli wychodzących — subject1.

Różnice między środowiskiem test a prod

Tokeny, dane i faktury w środowisku testowym są niezależne od produkcji. Nie mieszaj URLi i tokenów — to częsta przyczyna błędów "token not found".

Oficjalna dokumentacja

Pełna specyfikacja API KSeF jest dostępna na stronie Ministerstwa Finansów:

• Swagger / OpenAPI: ksef.mf.gov.pl/api
• Środowisko testowe: ksef-test.mf.gov.pl/api
• Schemat faktury FA(3): dostępny w repozytorium MF na ePUAP

Dokumentacja jest techniczna i nie zawsze czytelna. Jeśli masz problemy z integracją, możesz sprawdzić nasze inne artykuły:

• Token KSeF — jak wygenerować krok po kroku
• Jak sprawdzić fakturę w KSeF — 3 sposoby

Alternatywa: gotowe narzędzia

Budowanie integracji z KSeF API od zera to dni lub tygodnie pracy programisty. Musisz obsłużyć autoryzację, sesje, paginację, parsowanie XML, error handling i monitoring.

Jeśli potrzebujesz jedynie powiadomień o nowych fakturach przychodzących, nie musisz budować tego samemu. FakturyKSeF robi dokładnie to — odpytuje API KSeF co 15 minut i wysyła email z danymi każdej nowej faktury.

Konfiguracja trwa 2 minuty: podaj NIP, wklej token KSeF i email. Resztą zajmuje się system.