Dane gospodarcze
jako endpoint.

Kompleksowy przewodnik po API do danych o polskich firmach

1. Dane firmy (/api/dane)

Przegląd

API dostarcza kompleksowych danych o polskich firmach, obejmujących informacje rejestrowe, dane finansowe, opisy działalności, powiązania korporacyjne oraz strukturę udziałowców.

Endpoint

https://api.bizraport.pl/api/dane?email=abc@xyz.pl&password=qwe&krs=123

https://api.bizraport.pl/api/dane?email=abc@xyz.pl&password=qwe&nip=1234567890

Uwierzytelnienie

Wybierz jeden z dwóch sposobów:

• parametry URL email i password — jak w przykładzie wyżej
• nagłówek HTTP Basic Auth

Parametry żądania

Format danych

Wszystkie dane są zwracane w formacie JSON (UTF-8). Pola zagnieżdżone to gotowe tablice i obiekty, które nie wymagają dodatkowego parsowania po stronie klienta.

Struktura główna

Odpowiedź ze statusem 200 ma jedno pole data z tablicą firm. Zapytanie po krs zwraca najwyżej jeden element, po nip może zwrócić kilka - jeden NIP bywa przypisany do kilku numerów KRS. Brak trafienia to status 200 i pusta tablica, a nie 404.

{
  "data": [
    {
      "krs": "0000795513_",
      "nip": 8971868567,
      "...": "pozostałe pola z tabeli niżej"
    }
  ]
}

Pola główne

Sekcja, dla której firma nie ma danych, jest null, a nie pustą tablicą - krz jest null dla zdecydowanej większości spółek. Sprawdzaj null przed iteracją.

Szczegółowy opis pól

1. informacje_o_firmie

Zawiera tablicę obiektów z podstawowymi informacjami o firmie.

Struktura:

[
  {
    "nazwa_pola": "string",
    "wartosc": "string"
  }
]

Dostępne pola (nazwa_pola):

• cel_dzialalnosci - Cel działalności spółki
• data_wpisu_do_rejestru - Data wpisu do rejestru KRS (YYYY-MM-DD)
• data_wykreslenia_z_krs - Data wykreślenia z rejestru, jeśli dotyczy (DD.MM.YYYY)
• kod_pocztowy - Kod pocztowy siedziby
• miejscowosc - Miejscowość siedziby
• organ_rejestrowy - Organ rejestrowy prowadzący KRS
• regon - Numer REGON
• ulica - Ulica siedziby
• adres_strony_internetowej - Adres strony WWW firmy
• email - Adres email kontaktowy
• kapital_zakladowy - Wartość i waluta kapitału zakładowego
• wojewodztwo - Województwo
• forma_prawna - Forma prawna podmiotu
• nip - Numer NIP
• nazwa - Pełna nazwa firmy
• data_rozpoczecia_dzialalnosci - Data rozpoczęcia działalności (YYYY-MM-DD)
• forma_wlasnosci - Forma własności
• numer_nieruchomosci - Numer nieruchomości
• kraj - Kraj oddziału (jednostki terenowej), nie siedziby
• organ_reprezentujacy - Organ reprezentujący spółkę
• organ_nadzoru - Organ nadzoru
• sposob_reprezentacji - Sposób reprezentacji spółki
• status_opp - Status organizacji pożytku publicznego
• postepowanie_likwidacyjne - Informacja o postępowaniu likwidacyjnym
• postepowanie_upadlosciowe - Informacja o postępowaniu upadłościowym
• postepowanie_restrukturyzacyjne - Informacja o postępowaniu restrukturyzacyjnym
• postepowanie_ukladowe - Informacja o postępowaniu układowym

2. dane_finansowe

Zawiera tablicę danych finansowych dla różnych okresów sprawozdawczych.

Struktura:

[
  {
    "okres_sprawozdawczy": "string",
    "kwota": number,
    "nazwa_wskaznika": "string",
    "rok": number
  }
]

Dostępne wskaźniki (nazwa_wskaznika):

Aktywa i Kapitał:

• aktywa_trwale - Aktywa trwałe
• aktywa_obrotowe - Aktywa obrotowe
• suma_bilansowa - Suma bilansowa
• kapital_wlasny - Kapitał własny
• zobowiazania_i_rezerwy - Zobowiązania i rezerwy na zobowiązania

Wielkość firmy:

• przychody - Przychody całkowite
• przychody_operacyjne - Przychody operacyjne
• przychody_ze_sprzedazy - Przychody ze sprzedaży
• zatrudnienie / zatrudnienie_estymowane - Zatrudnienie

Koszty:

• koszty_operacyjne - Koszty operacyjne
• koszty_sprzedanych_produktow - Koszty sprzedanych produktów
• koszty_sprzedazy_i_zarzadu - Koszty sprzedaży i zarządu
• wynagrodzenia - Wynagrodzenia
• podatek_dochodowy - Podatek dochodowy
• amortyzacja - Amortyzacja

Zyski i Straty:

• zysk_brutto_ze_sprzedazy - Zysk (strata) brutto ze sprzedaży
• zysk_ze_sprzedazy - Zysk (strata) ze sprzedaży
• zysk_operacyjny - Zysk (strata) z działalności operacyjnej
• zysk_brutto - Zysk brutto
• zysk_netto - Zysk netto

Wskaźniki rentowności:

• ebit - EBIT (zysk przed odsetkami i podatkami)
• ebitda - EBITDA (zysk przed odsetkami, podatkami, deprecjacją i amortyzacją)
• marza_operacyjna - Marża operacyjna
• marza_netto - Marża netto
• roe - ROE (zwrot z kapitału własnego)
• roa - ROA (zwrot z aktywów)
• wskaznik_zadluzenia - Wskaźnik zadłużenia

Modele ryzyka:

• niewyplacalnosc_lub_restrukturyzacja_24m - Prawdopodobieństwo niewypłacalności lub restrukturyzacji w ciągu 24 miesięcy
• wiarygodnosc - Ocena wiarygodności podmiotu

Wycena i kredyt kupiecki:

• wartosc_firmy_minimalna - Szacowana wartość spółki (wariant minimalny)
• wartosc_firmy_srednia - Szacowana wartość spółki (wariant średni)
• wartosc_firmy_maksymalna - Szacowana wartość spółki (wariant maksymalny)
• kredyt_kupiecki_minimalny - Sugerowany kredyt kupiecki (wariant minimalny)
• kredyt_kupiecki_sredni - Sugerowany kredyt kupiecki (wariant średni)
• kredyt_kupiecki_maksymalny - Sugerowany kredyt kupiecki (wariant maksymalny)

3. opisy_firmy

Zawiera opisy tekstowe działalności firmy oraz punkty kluczowe.

Struktura:

[
  {
    "opis": "string",
    "punkt_kluczowy_1": "string",
    "punkt_kluczowy_2": "string",
    "punkt_kluczowy_3": "string",
    "punkt_kluczowy_4": "string",
    "punkt_kluczowy_5": "string"
  }
]

4. powiazania

Zawiera informacje o powiązaniach korporacyjnych i osobowych firmy.

Typy powiązań:

• reprezentacja - Osoba/podmiot reprezentujący spółkę
• wspólnik - Wspólnik spółki
• organ nadzoru - Członek organu nadzoru
• prokurent - Prokurent
• powiązanie zwrotne - Kierunek odwrotny: ta firma jest powiązana z podmiotem z listy
• Pozostałe: pełnomocnik, likwidator, syndyk, kurator, komitet założycielski, powstanie organizacji, podmioty o identycznym NIP, podmioty o identycznym REGON, inne

Struktura:

[
  {
    "typ_podmiotu": "string",
    "nazwa": "string",
    "typ_powiazania": "string",
    "id_podmiotu": "string | null",
    "organ": "string | null",
    "funkcja": "string | null"
  }
]

id_podmiotu to numer KRS dla organizacji, a wewnętrzny identyfikator dla osoby.

Pole powiazania_rozszerzone (patrz „Rozszerzenie powiązań" na końcu rozdziału) ma cztery pola: typ_podmiotu, nazwa, typ_powiazania i id_podmiotu.

5. udzialy

Zawiera informacje o strukturze właścicielskiej firmy.

Uwaga: Dane są sortowane malejąco według procentu udziałów.

procent_udzialow jest liczbą w skali 0-100 (51 oznacza 51%). Suma udziałów nie musi dawać 100.

Struktura:

[
  {
    "typ_podmiotu": "string",
    "nazwa": "string",
    "procent_udzialow": number | null,
    "id_podmiotu": "string | null"
  }
]

6. monitor_sadowy

Ogłoszenia z Monitora Sądowego i Gospodarczego (MSiG) powiązane z KRS: wpisy do KRS, upadłości, restrukturyzacje, likwidacje, ogłoszenia wymagane przez KSH/KPC/prawo upadłościowe.

Struktura:

[
  {
    "numer_ogloszenia": "string",
    "sygnatura_sprawy": "string",
    "tresc_naglowka": "string",
    "nr_monitora": "string (numer/rok)",
    "rozdzial": "string | null",
    "tresc_ogloszenia": "string",
    "data_publikacji": "string (YYYY-MM-DD)",
    "nazwa_podmiotu": "string",
    "poziom_istotnosci": "string ('UWAGA' | 'Rzuć okiem' | 'Zmiana formalna')"
  }
]

7. krz

Zawiera obwieszczenia z Krajowego Rejestru Zadłużonych, w których dłużnikiem jest sama spółka (głównie w postępowaniach upadłościowych i restrukturyzacyjnych). Wpisów dotyczących osób powiązanych ze spółką sekcja nie zawiera.

Struktura:

[
  {
    "data_krz": "string (YYYY-MM-DD)",
    "grupa_kategorii_tytul": "string",
    "kategoria_tytul": "string",
    "poziom_istotnosci": "string ('UWAGA' | 'Rzuć okiem' | 'Zmiana formalna')",
    "numer_obwieszczenia": "string",
    "tytul_obwieszczenia": "string",
    "sygnatura_akt": "string",
    "sad": "string",
    "wydzial_sadu": "string",
    "dluznik_typ": "string",
    "tresc": "string",
    "id_osoby": "string | null",
    "przypisanie_do_krs": "string"
  }
]

Pola dluznik_typ i przypisanie_do_krs mają zawsze wartość podmiot, a id_osoby wartość null.

8. historia_sprawozdan

Historia sprawozdań finansowych złożonych do KRS: okresy sprawozdawcze, ustawowy termin złożenia oraz faktyczna data wpływu dokumentu. Najnowszy okres jest pierwszy. Pole okres_sprawozdawczy jest wspólne z sekcją dane_finansowe, więc obie można po nim złączyć.

Struktura:

[
  {
    "okres_sprawozdawczy": "string (DD-MM-YYYY_DD-MM-YYYY)",
    "rok": number,
    "termin_zlozenia": "string (DD-MM-YYYY)",
    "data_dodania_do_krs": "string (DD-MM-YYYY)"
  }
]

9. pozycja_na_tle_branzy

Pozycja spółki na tle grupy PKD, osobno dla każdego okresu i wskaźnika. Grupę tworzą spółki, które na koniec danego okresu sprawozdawczego miały w KRS to samo PKD główne (podklasa, w formacie jak kod_pkd). Pole kod_pkd podaje dzisiejsze PKD główne spółki, więc w latach, w których spółka miała w KRS inne PKD główne, grupa porównawcza różni się od kod_pkd. Za lata bez wpisu PKD głównego w KRS (w tym wszystkie sprzed grudnia 2014 r.) sekcja nie ma wierszy.

Struktura:

[
  {
    "okres_sprawozdawczy": "string (DD-MM-YYYY_DD-MM-YYYY)",
    "rok": number,
    "nazwa_wskaznika": "string",
    "percentyl_w_pkd": number
  }
]

percentyl_w_pkd to ułamek od 0 do 1, a nie procent: 0.9507 znaczy, że 95,07% firm w tej grupie PKD ma niższą wartość tego wskaźnika.

nazwa_wskaznika używa tych samych nazw co dane_finansowe, więc obie sekcje można złączyć po parze (okres_sprawozdawczy, nazwa_wskaznika) i mieć kwotę obok percentyla. Dostępne wskaźniki:

• przychody
• zysk_netto
• suma_bilansowa
• marza_netto
• marza_operacyjna
• roa
• roe
• wskaznik_zadluzenia
• podatek_dochodowy
• wartosc_firmy_srednia

Wiersz dla wskaźnika przychody ma dodatkowo trzy pola opisujące udział spółki w rynku:

Przy pozostałych wskaźnikach tych trzech pól nie ma w ogóle - nie są null, po prostu nie występują w obiekcie.

Obie liczby branżowe rosną, w miarę jak spływają sprawozdania, więc za ostatnie lata są zaniżone.

Wartości NULL

Pola mogą przyjmować wartość null w następujących przypadkach:

• Brak danych dla danej firmy
• Dane niedostępne w źródle
• Nieaplikowalne dla danego typu firmy

Pola z zagnieżdżonymi strukturami JSON zwracają null zamiast pustego ciągu, jeśli brak danych.

Uwagi techniczne

1. Struktury zagnieżdżone: Pola informacje_o_firmie, dane_finansowe, opisy_firmy, powiazania, udzialy, monitor_sadowy, krz, historia_sprawozdan i pozycja_na_tle_branzy są zwracane jako gotowe tablice JSON. Nie wywołuj na nich JSON.parse().

2. Encoding: Wszystkie dane są zwracane w kodowaniu UTF-8.

3. Typy i skale:

• wartości procentowe są ułamkami (0.15 to 15%). Wyjątek: procent_udzialow w sekcji udzialy jest w skali 0-100
• wiarygodnosc przyjmuje wartości od 1 do 5, gdzie 1 to najwyższa wiarygodność płatnicza
• format daty jest podany przy każdym polu z datą

4. Sortowanie:

• dane_finansowe: sortowane malejąco po okresie sprawozdawczym (najnowszy pierwszy), a w obrębie okresu rosnąco po nazwa_wskaznika
• powiazania: sortowane według typ_powiazania i nazwa
• udzialy: sortowane malejąco według procent_udzialow

5. Okresy sprawozdawcze: Mogą mieć różną długość w zależności od roku obrotowego firmy.

Rozszerzenie powiązań

Parametr rozszerz_polaczenia=tak dokłada do każdego elementu powiazania pole powiazania_rozszerzone - powiązania danej osoby lub podmiotu, jeden poziom głębiej.

2. Katalog firm (/api/katalog)

Przegląd

API umożliwia filtrowanie i wyszukiwanie firm według różnych kryteriów finansowych, lokalizacyjnych i klasyfikacyjnych. Zwraca listę numerów KRS firm spełniających zadane kryteria. Może służyć jako narzędzie do wyszukiwania leadów B2B.

Endpoint

https://api.bizraport.pl/api/katalog?email=abc@xyz.pl&password=qwe&przychody_od=10000000&przychody_do=11000000

Uwierzytelnienie

Wybierz jeden z dwóch sposobów:

• parametry URL email i password — jak w przykładzie wyżej
• nagłówek HTTP Basic Auth

Odpowiedź

Struktura JSON

{
  "data": [{ "krs": "0000123456_" }, ...],
  "count": 12345,
  "fetchedCount": 1000
}

Gdy count przekracza milion, fetchedCount zatrzymuje się na milionie i reszty nie da się pobrać - endpoint nie ma paginacji. Zawęź kryteria, jeśli wynik jest większy.

Parametry filtrowania

Filtry finansowe (zakresy)

Wymagany jest co najmniej jeden filtr - żądanie bez żadnego kończy się błędem 400.

Wszystkie filtry finansowe przyjmują wartości liczbowe. Użyj sufiksu _od dla minimum i _do dla maksimum. Wartość zawierająca litery (10mln, 1e6) kończy żądanie błędem 400.

Filtry czasowe

Filtry procentowe

WAŻNE: Wszystkie wskaźniki procentowe (ROA, ROE, marże, CAGR, wskaźnik zadłużenia) podawane są jako liczby całkowite reprezentujące procenty. Na przykład: roa_od=15 oznacza ROA ≥ 15%, a nie 0.15.

Filtry klasyfikacji PKD

Filtry lokalizacyjne siedziby / tekstowe

Filtry boolowskie

Akceptowane wartości: "tak"

Przykłady użycia

Firmy z przychodami powyżej 10 mln zł:

https://api.bizraport.pl/api/katalog?email=abc@xyz.pl&password=qwe&przychody_od=10000000

Firmy IT w województwie mazowieckim:

https://api.bizraport.pl/api/katalog?email=abc@xyz.pl&password=qwe&pkd_sekcja=J&wojewodztwo=MAZOWIECKIE

Aktywne firmy z ROE powyżej 15%:

https://api.bizraport.pl/api/katalog?email=abc@xyz.pl&password=qwe&roe_od=15&nie_wykreslona=tak

3. Wyszukiwanie firm (/api/szukaj)

Przegląd

API umożliwia wyszukiwanie firm po nazwie.

Endpoint

https://api.bizraport.pl/api/szukaj?email=abc@xyz.pl&password=qwe&q=abc

Uwierzytelnienie

Wybierz jeden z dwóch sposobów:

• parametry URL email i password — jak w przykładzie wyżej
• nagłówek HTTP Basic Auth

Parametry żądania

Odpowiedź

Struktura JSON

{
  "data": [{ "krs": "0000123456_" }, ...],
  "dane_uciete": false
}

Lista jest sortowana rosnąco po długości nazwy, a nie po trafności. Wyjątek: przy frazie z cyframi i literami na pierwszym miejscu stoi najlepsze dopasowanie.

Brak dopasowań to status 200 z pustą tablicą data, a nie 404. Endpoint nie ma paginacji.

4. Sprawozdania finansowe (/api/sprawozdania)

Przegląd

Zwraca pełną treść sprawozdań finansowych spółki. To co innego niż dane_finansowe w /api/dane. Tam są gotowe wskaźniki finansowe, tutaj sprawozdanie w takiej postaci, w jakiej spółka je złożyła, pozycja po pozycji.

Endpoint

https://api.bizraport.pl/api/sprawozdania?email=abc@xyz.pl&password=qwe&krs=0000566918

Uwierzytelnienie

Wybierz jeden z dwóch sposobów:

• parametry URL email i password — jak w przykładzie wyżej
• nagłówek HTTP Basic Auth

Parametry żądania

Odpowiedź

Struktura JSON

{
  "data": [{
      "krs": "0000566918_",
      "okresy": [{
          "okres_sprawozdawczy": "01-01-2024_31-12-2024",
          "rok": 2024,
          "sekcje": [{
              "sekcja": "Bilans",
              "pozycje": [{
                  "pozycja_szczegolowa": "Aktywa",
                  "kod_pozycji": "Aktywa_B_II_A_1",
                  "poziom_zaglebienia": 5,
                  "nazwa_pozycji": "– do 12 miesięcy",
                  "kwota": 114370.32
                }]
          }]
    }]
}]
}

Pola odpowiedzi

Uwagi

Hierarchię odtwarzaj z kolejności wierszy i poziom_zaglebienia: rodzicem jest najbliższy wcześniejszy wiersz o mniejszym poziomie, a wcięcie to poziom_zaglebienia minus 1. Nie buduj jej z kod_pozycji: pozycje dopisane przez spółkę poza wzorem nie mają w nim ścieżki.

Każdy okres to osobne sprawozdanie: spółka może w różnych latach składać je w różnych formach, więc zestaw sekcji, pozycji i etykiet potrafi się różnić. Nie buduj mapy kod_pozycji na nazwę raz dla całej spółki.

Kwoty są w złotych, po przeliczeniu sprawozdań podanych w tysiącach. W części sprawozdań suma aktywów nie równa się sumie pasywów. To stan złożonego dokumentu, nie błąd odczytu.

Brak spółki w zbiorze sprawozdań zwraca puste data: [] ze statusem 200. Takie odpytanie jest bezpłatne.

5. Zużycie danych (/api/zuzycie)

Przegląd

Pozwala sprawdzić liczbę odpytań i koszt netto za wybrany miesiąc, a przy pakiecie albo abonamencie kupionym online - saldo pakietu i bieżący okres rozliczeniowy. Wywołanie /api/zuzycie jest bezpłatne i nie wlicza się do rozliczenia.

Endpoint

https://api.bizraport.pl/api/zuzycie?email=abc@xyz.pl&password=qwe

Uwierzytelnienie

Wybierz jeden z dwóch sposobów:

• parametry URL email i password — jak w przykładzie wyżej
• nagłówek HTTP Basic Auth

Parametry żądania

Parametry są opcjonalne. Gdy pominięte, system zwróci dane o zużyciu za bieżący miesiąc.

Odpowiedź

Struktura JSON

{
  "miesiac": "2026-07",
  "model": "standard",
  "zuzycie": {
    "/dane": 820,
    "/katalog": 45,
    "/szukaj": 130,
    "/sprawozdania": 210
  },
"pula": 1000,
"odpytania_razem": 1205,
"odpytania_w_abonamencie": 1000,
"odpytania_ponad_abonament": 205,
"koszt_abonamentu_pln": 100,
"koszt_ponad_abonament_pln": 18.45,
"koszt_netto_pln": 118.45,
"pakiet": null,
"abonament": null
}

Przy planie kupionym online (model pakiet albo abonament) pola najwyższego poziomu pula, odpytania_w_abonamencie, odpytania_ponad_abonament i koszt_* mają wartość null. Pola model, pakiet i abonament opisują stan w chwili wywołania, niezależnie od parametrów month i year.

Konto testowe

Konto z wartością konto testowe w polu model ma limit 100 bezpłatnych odpytań, liczonych łącznie ze wszystkich endpointów i narastająco od założenia konta - bez resetu na początku miesiąca.

Po wyczerpaniu limitu każdy płatny endpoint zwraca status 402. Klucze pozostają te same.

Uwaga: pola pula i koszt_* dotyczą abonamentu, nie tego limitu - na koncie testowym pula pokaże 1000.

Klucze API

Klucze odbierasz na https://www.bizraport.pl/api - zaloguj się i kliknij raz. Pierwsze 100 odpytań jest bezpłatnych. Tym samym jednym kliknięciem wymieniasz klucze na nowe, bez względu na to, czy zakładasz konto, czy już je masz: e-mail zostaje ten sam, zmienia się hasło.

Poprzednie hasło przestaje działać od razu, więc jeśli masz je wpisane w jakimś narzędziu, wpisz tam nowe.

6. Kody odpowiedzi

Naliczane jest wyłącznie odpytanie, które zwróciło dane. Każda odpowiedź inna niż 200 jest bezpłatna, tak samo jak odpowiedź 200 z pustą tablicą data.

Odpowiedź inna niż 200 zawiera pole error z opisem po polsku - bez data i bez count. Część odpowiedzi niesie dodatkowo request_id; jeśli piszesz do nas w sprawie konkretnego żądania, podanie go pozwala nam je znaleźć od razu:

{ "error": "Podaj identyfikator spółki: 'krs' (1-10 cyfr) albo 'nip' (10 cyfr)." }

Treść komunikatu jest przeznaczona dla człowieka i może się zmieniać. Logikę swojej integracji buduj na kodzie HTTP, nie na treści error.

Wszystkie endpointy przyjmują wyłącznie metodę GET.

7. Wsparcie

W przypadku pytań lub problemów technicznych prosimy o kontakt z zespołem wsparcia.

Kontakt: kontakt@bizraport.pl