Jak pobrać przez API wybrane pola sprawozdania finansowego spółki z KRS?

Sprawozdania finansowe w Repozytorium Dokumentów Finansowych KRS są składane w XML zgodnym ze strukturami logicznymi Ministerstwa Finansów. Struktur jest kilka (jednostka inna, mała, mikro, konsolidacja), a każda ma inne nazwy i inne zagnieżdżenie pozycji.

API KRData zwraca znormalizowane dane, bez konieczności samodzielnej analizy. W tym poradniku pokazujemy, jak pobrać wybrane wielkości finansowe wskazanej spółki.

Czego potrzebujesz

• konta w planie Pro lub wyższym,
• klucza API z panelu (Ustawienia → Klucze API),
• numeru KRS, NIP, REGON albo identyfikatora podmiotu w KRData.

Adres bazowy: https://api.krdata.pl. Klucz przekazujesz w nagłówku x-api-key.

Krok 1: Wywołaj endpoint danych finansowych

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

Domyślnie dostajesz jeden wiersz na okres sprawozdawczy, posortowany od najnowszego. Korekty są zwinięte do najnowszej wersji, a jeżeli spółka złożyła za ten sam rok sprawozdanie jednostkowe i skonsolidowane, w szeregu pozostaje jednostkowe – dzięki temu zakres danych nie zmienia się w połowie serii.

Wywołanie zużywa 1 jednostkę puli RDF, niezależnie od liczby zwróconych lat.

Krok 2: Odczytaj metryki z odpowiedzi

[
  {
    "document_id": 184213,
    "krs": "0000000001",
    "schema": {
      "name": "JednostkaInna",
      "version": "1-0",
      "rzis_variant": "kalkulacyjny"
    },
    "period_start": "2024-01-01",
    "period_end": "2024-12-31",
    "prepared_date": "2025-03-28",
    "metrics": {
      "revenue": 18422100.0,
      "revenue_prior": 16110400.0,
      "operating_profit": 1240300.0,
      "ebitda": 1988700.0,
      "net_profit": 902400.0,
      "total_assets": 14203900.0,
      "equity": 6120700.0
    },
    "checks": {
      "balance_ok": true,
      "net_profit_ok": true
    }
  }
]

Każda metryka ma odpowiednik za poprzedni rok obrotowy z sufiksem _prior(np. revenue i revenue_prior), więc jedno wywołanie daje od razu dane porównawcze. Wartości są w złotych – również wtedy, gdy spółka złożyła sprawozdanie w tysiącach.

Dostępne metryki:

Obiekt checks zawiera flagi spójności: balance_ok (aktywa równe pasywom) oraz net_profit_ok (wynik netto z RZiS zgodny z bilansem). Warto je logować – wychwytują błędy w samym sprawozdaniu, nie w parsowaniu.

Krok 3: Zawęź zakres danych

Endpoint przyjmuje kilka parametrów sterujących:

Przykład – dane za 2024 rok wraz z pełną strukturą pozycji:

curl -s "https://api.krdata.pl/v1/rdf/financials?nip=5252248481&year=2024&positions=true" \
  -H "x-api-key: TWOJ_KLUCZ"

Pole positions to słownik, w którym kluczem jest nazwa pozycji ze struktury logicznej, a wartością para liczb [rok bieżący, rok poprzedni]. Używaj go, gdy potrzebujesz pozycji spoza zestawu metryk – np. konkretnej linii kosztów rodzajowych.

Kiedy sięgnąć po oryginalny plik

Metryki wystarczają do scoringu, monitoring1u i analiz porównawczych. Oryginalny plik XML lub PDF przyda się, gdy potrzebujesz informacji dodatkowej, sprawozdania zarządu, uchwał albo podpisów elektronicznych. Opisujemy to w poradniku Jak pobrać przez API sprawozdanie finansowe spółki z KRS.

Najczęstsze problemy

• Pusta lista mimo złożonego sprawozdania – dokument istnieje, ale nie został sparsowany (skan PDF zamiast XML). Sprawdź pole has_financials w /v1/rdf/documents.
• Brakujące metryki (null) – nie każdy wariant struktury zawiera każdą pozycję. Sprawozdania jednostki mikro nie mają np. wyniku brutto ani rozbudowanego RZiS.
• Skok wartości rok do roku – sprawdź schema.name. Zmiana wariantu sprawozdania (np. z „mała” na „inna”) zmienia poziom szczegółowości pozycji.
• Dwa wiersze za ten sam rok przy latest_only=false – to korekta albo sprawozdanie skonsolidowane. Rozróżnisz je po prepared_date i schema.name.

Pełna specyfikacja: dokumentacja endpointu.