Jak pobrać przez API sprawozdanie finansowe spółki z KRS?

Repozytorium Dokumentów Finansowych (RDF) przy Krajowym Rejestrze Sądowym zawiera roczne sprawozdania finansowe spółek – w oryginalnej postaci, w jakiej zostały złożone: XML e-Sprawozdania, PDF, czasem skany. Ręczne pobieranie działa dobrze przy kilku spółkach. Przy kilkuset potrzebne jest API.

Poniżej pokazujemy, jak pobrać plik sprawozdania finansowego wskazanej spółki na podstawie numeru KRS, NIP lub REGON.

Czego potrzebujesz

• konta KRData w planie Pro lub wyższym (RDF nie jest dostępny w planie Standard),
• klucza API wygenerowanego w panelu, w zakładce Ustawienia → Klucze API,
• dowolnego klienta HTTP – w przykładach używamy curl.

Adres bazowy API to https://api.krdata.pl, a klucz przekazujesz w nagłówku x-api-key.

Krok 1: Wypisz dostępne sprawozdania spółki

Endpoint GET /v1/rdf/documents zwraca metadane wszystkich sprawozdań zgromadzonych dla spółki. Podmiot wskazujesz dokładnie jednym parametrem: krs, nip, regon albo id (UUID podmiotu w KRData).

curl -s "https://api.krdata.pl/v1/rdf/documents?krs=0000000001" \
  -H "x-api-key: TWOJ_KLUCZ"

W odpowiedzi dostajesz listę dokumentów:

[
  {
    "id": 184213,
    "krs": "0000000001",
    "name": "SF_0000000001_2024.xml",
    "format": "xml",
    "byte_size": 148322,
    "sha256": "…",
    "period_start": "2024-01-01",
    "period_end": "2024-12-31",
    "filing_date": "2025-06-30",
    "is_correction": false,
    "fetched_at": "2025-07-02T04:12:08Z",
    "has_financials": true
  }
]

Najważniejsze pola:

Wywołanie zużywa 1 jednostkę puli RDF.

Krok 2: Pobierz plik dokumentu

Identyfikator z pola id przekazujesz do GET /v1/rdf/documents/{id}. Endpoint zwraca surową treść pliku wraz z nagłówkiem Content-Disposition, więc curl -O -J zapisze go pod oryginalną nazwą.

curl -s -O -J "https://api.krdata.pl/v1/rdf/documents/184213" \
  -H "x-api-key: TWOJ_KLUCZ"

Plik wraca dokładnie taki, jaki spółka złożyła w repozytorium – razem z podpisami elektronicznymi. Nagłówek Content-Type(application/xml, application/pdf) możesz przekazać dalej do przeglądarki użytkownika swojej aplikacji.

Pobranie jednego dokumentu zużywa 5 jednostek puli RDF i jest ograniczone do jednego pobrania na 3 sekundy na konto. Przy większych wsadach zaplanuj kolejkę zamiast równoległych żądań.

Krok 3 (opcjonalnie): Pobierz wszystkie sprawozdania naraz

Jeśli potrzebujesz kompletu dokumentów spółki, zamiast iterować po liście możesz pobrać jedno archiwum ZIP:

curl -s -O -J "https://api.krdata.pl/v1/rdf/archive?nip=5252248481" \
  -H "x-api-key: TWOJ_KLUCZ"

Archiwum zawiera wszystkie zapisane pliki nazwane wg schematu SF_<KRS>_<rok>.<format>. Endpoint wymaga planu Enterprise, zużywa 5 jednostek puli RDF za każdy dokument w archiwum i jest ograniczony do jednego archiwum na minutę.

Jak to zautomatyzować

Typowy proces wsadowy wygląda tak:

1. Dla każdej spółki z Twojej listy wywołaj /v1/rdf/documents.
2. Odfiltruj dokumenty, których sha256 masz już u siebie.
3. Dla pozostałych wywołaj /v1/rdf/documents/{id} z odstępem co najmniej 3 sekund.
4. Zapisz plik razem z period_end i filing_date – to one, a nie data pobrania, wyznaczają rok obrotowy.

Jeżeli nie potrzebujesz oryginalnych plików, tylko liczb (przychody, wynik netto, suma bilansowa), pomiń pobieranie i sięgnij po dane znormalizowane – opisujemy je w poradniku Jak pobrać przez API wybrane pola sprawozdania finansowego.

Najczęstsze problemy

• 404 przy pobieraniu dokumentu – dokument widoczny na liście nie ma jeszcze zapisanej treści. Ponów próbę później albo pobierz archiwum ZIP, które zawiera wyłącznie dokumenty z treścią.
• Spółka bez sprawozdań – nie każdy podmiot składa sprawozdania do RDF (np. spółki cywilne, oddziały). Pusta lista jest prawidłową odpowiedzią.
• Kilka dokumentów za ten sam rok – to zwykle korekta (is_correction: true) albo sprawozdanie skonsolidowane obok jednostkowego. Wybieraj świadomie, zamiast brać pierwszy element listy.
• Przekroczona pula RDF – aktualne zużycie sprawdzisz w GET /v1/usage/summary.

Pełny opis parametrów i odpowiedzi znajdziesz w dokumentacji API.