# Dokumentacja API BizRaport

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

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `krs` | String | Numer KRS firmy (wymagany jeśli brak nip) |
| `nip` | String | Numer NIP firmy (wymagany jeśli brak krs) |

### 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.

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

#### Pola główne

| **Pole** | **Typ** | **Opis** |
| --- | --- | --- |
| `krs` | String | Numer KRS firmy (klucz główny). 10 cyfr zakończonych podkreślnikiem, np. `0000795513_` |
| `nip` | Number \| null | Numer identyfikacji podatkowej (NIP). |
| `kod_pkd` | String \| null | Kod PKD działalności gospodarczej, np. `62.01.Z`. Bywa `null` albo `Brak` |
| `opis_pkd` | String \| null | Słowny opis działalności według PKD |
| `informacje_o_firmie` | Array \| null | Podstawowe informacje rejestrowe o firmie |
| `dane_finansowe` | Array \| null | Dane finansowe i wskaźniki ekonomiczne |
| `opisy_firmy` | Array \| null | Opisy działalności i punkty kluczowe |
| `powiazania` | Array \| null | Powiązania korporacyjne i osobowe |
| `udzialy` | Array \| null | Struktura właścicielska i udziałowcy |
| `monitor_sadowy` | Array \| null | Informacje z Monitora Sądowego |
| `krz` | Array \| null | Informacje z KRZ |
| `historia_sprawozdan` | Array \| null | Historia sprawozdań finansowych: okresy, terminy i faktyczne daty złożenia do KRS |
| `pozycja_na_tle_branzy` | Array \| null | Pozycja firmy na tle branży: percentyle wskaźników finansowych w grupie spółek o tym samym PKD głównym na koniec danego okresu |

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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

| **Pole** | **Typ** | **Opis** |
| --- | --- | --- |
| `udzial_w_rynku` | Number | Ułamek przychodów grupy PKD, jaki generuje ta spółka (`0.0032` to 0,32%) |
| `przychody_calej_branzy` | Number \| null | Suma przychodów w tej grupie PKD za dany rok, w złotych |
| `liczba_firm_w_branzy` | Number | Liczba sprawozdań w tej grupie PKD za dany rok |

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

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

| **Pole** | **Typ** | **Opis** |
| --- | --- | --- |
| `data` | Array | Lista obiektów z numerami KRS |
| `data[].krs` | String | Numer KRS (10 cyfr + "_") |
| `count` | Number | Całkowita liczba wyników spełniających kryteria |
| `fetchedCount` | Number | Liczba zwróconych rekordów (max 1 000 000) |

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.

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `przychody_od / przychody_do` | Number | Przychody całkowite |
| `zysk_netto_od / zysk_netto_do` | Number | Zysk netto |
| `zobowiazania_i_rezerwy_na_zobowiazania_od / _do` | Number | Zobowiązania i rezerwy |
| `przychody_operacyjne_od / przychody_operacyjne_do` | Number | Przychody operacyjne |
| `aktywa_obrotowe_od / aktywa_obrotowe_do` | Number | Aktywa obrotowe |
| `gotowka_od / gotowka_do` | Number | Gotówka, czyli środki pieniężne z ostatniego sprawozdania |
| `kapital_wlasny_od / kapital_wlasny_do` | Number | Kapitał własny |
| `suma_bilansowa_od / suma_bilansowa_do` | Number | Suma bilansowa |
| `kapital_zakladowy_liczbowo_od / _do` | Number | Kapitał zakładowy |
| `podatek_dochodowy_od / podatek_dochodowy_do` | Number | Podatek dochodowy |
| `zysk_z_dzialalnosci_operacyjnej_od / _do` | Number | Zysk z działalności operacyjnej |
| `aktywa_trwale_od / aktywa_trwale_do` | Number | Aktywa trwałe |
| `koszty_operacyjne_od / koszty_operacyjne_do` | Number | Koszty operacyjne |
| `estymowana_wartosc_firmy_od / _do` | Number | Estymowana wartość firmy |
| `wynagrodzenia_od / wynagrodzenia_do` | Number | Wynagrodzenia |
| `amortyzacja_od / amortyzacja_do` | Number | Amortyzacja |
| `ebit_od / ebit_do` | Number | EBIT |
| `ebitda_od / ebitda_do` | Number | EBITDA |
| `zatrudnienie_od / zatrudnienie_do` | Number | Zatrudnienie |

#### Filtry czasowe

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `ostatni_rok_sprawozdania_od / _do` | Number | Rok ostatniego sprawozdania (np. 2023) |
| `rok_wpisu_do_rejestru_od / _do` | Number | Rok wpisu do rejestru |
| `rok_rozpoczecia_dzialalnosci_od / _do` | Number | Rok rozpoczęcia działalności |
| `ostatni_krz` | Number | Istotny wpis w KRZ w ostatnich N dniach (np. 90) |
| `ostatni_monitor` | Number | Istotny wpis w MSiG w ostatnich N dniach |

#### 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.

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `roa_od / roa_do` | Number | ROA - zwrot z aktywów (%) |
| `roe_od / roe_do` | Number | ROE - zwrot z kapitału własnego (%) |
| `marza_netto_od / marza_netto_do` | Number | Marża netto (%) |
| `marza_operacyjna_od / marza_operacyjna_do` | Number | Marża operacyjna (%) |
| `wskaznik_zadluzenia_od / _do` | Number | Wskaźnik zadłużenia (%) |
| `srednioroczny_wzrost_przychodow_1_rok_od / _do` | Number | CAGR przychodów (1 rok) (%) |
| `srednioroczny_wzrost_przychodow_3_lata_od / _do` | Number | CAGR przychodów (3 lata) (%) |
| `srednioroczny_wzrost_przychodow_5_lat_od / _do` | Number | CAGR przychodów (5 lat) (%) |

#### Filtry klasyfikacji PKD

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `pkd_sekcja` | String | Sekcja PKD (np. C, G, J) - wielkie litery |
| `pkd_dzial` | String | Dział PKD (np. 62, 47) |
| `pkd_podklasa` | String | Podklasa PKD (np. 62.01.Z) - wielkie litery |

#### Filtry lokalizacyjne siedziby / tekstowe

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `wojewodztwo` | String | Województwo (wielkie litery, bez myślinków, np. MAZOWIECKIE, WARMINSKOMAZURSKIE) |
| `miasto` | String | Miejscowość (wyszukiwanie częściowe) |
| `adres` | String | Ulica (wyszukiwanie częściowe) |
| `gmina` | String | Gmina (wyszukiwanie częściowe) |
| `powiat` | String | Powiat (wyszukiwanie częściowe) |
| `kod_pocztowy_poczatek` | String | Początek kodu pocztowego (np. 00) |
| `kod_pocztowy_koncowka` | String | Końcówka kodu pocztowego (np. 001) |
| `opis` | String | Wyszukiwanie firm bazują na ich opisie, np. opis=erp |

#### Filtry boolowskie

Akceptowane wartości: "tak"

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `czy_ma_jednostke_terenowa` | Boolean | Czy firma ma jednostkę terenową |
| `czy_ma_jednostke_terenowa_poza_polska` | Boolean | Czy firma ma jednostkę poza Polską |
| `czy_status_opp` | Boolean | Czy firma ma status OPP |
| `czy_wiekszosciowy_udzialowiec` | Boolean | Czy firma ma większościowego udziałowca |
| `nie_wykreslona` | Boolean | Tylko firmy aktywne (niewykreślone z KRS) |
| `cit_estonski` | Boolean | Prawdopodobnie CIT estoński |

### 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

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| q | String | Fraza wyszukiwania (nazwa firmy, NIP, KRS, REGON). Musi zawierać słowo o długości co najmniej 3 znaków |

### Odpowiedź

#### Struktura JSON

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

| **Pole** | **Typ** | **Opis** |
| --- | --- | --- |
| data | Array | Lista obiektów z numerami KRS |
| dane_uciete | Boolean | true jeśli zwrócona lista nie jest kompletna; wyszukiwarka pobiera najwyżej 100 tys. dopasowań |

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

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| `krs` | String | Numer KRS firmy (wymagany jeśli brak nip) |
| `nip` | String | Numer NIP firmy (wymagany jeśli brak krs) |

### Odpowiedź

#### Struktura JSON

```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

| **Pole** | **Typ** | **Opis** |
| --- | --- | --- |
| data[] | Array | Zero albo jeden element przy zapytaniu po `krs`; przy zapytaniu po `nip` może być kilka |
| data[].krs | String | Numer KRS (10 cyfr + "_") |
| data[].okresy[] | Array | Okresy sprawozdawcze, najnowszy pierwszy |
| okresy[].okres_sprawozdawczy | String | Okres w formacie DD-MM-YYYY_DD-MM-YYYY |
| okresy[].rok | Number \| null | Rok okresu. Okresy identyfikuj po okres_sprawozdawczy |
| okresy[].sekcje[] | Array | Sekcje złożone w danym okresie. Sekcji niezłożonej nie ma w tablicy |
| sekcje[].sekcja | String | `Bilans`, `Rachunek zysków i strat`, `Rachunek przepływów pieniężnych` albo `Zestawienie zmian w kapitale`, zawsze w tej kolejności |
| sekcje[].pozycje[] | Array | Pozycje sekcji w kolejności ze źródła |
| pozycje[].pozycja_szczegolowa | String \| null | Aktywa albo Pasywa w Bilansie; Kalkulacyjny albo Porównawczy w Rachunku zysków i strat; null w pozostałych sekcjach |
| pozycje[].kod_pozycji | String \| null | Kod pozycji ze schemy sprawozdania, np. Aktywa_B_II_A_1 |
| pozycje[].poziom_zaglebienia | Number \| null | Głębokość pozycji w obrębie swojej sekcji |
| pozycje[].nazwa_pozycji | String \| null | Nazwa pozycji; przy null użyj kod_pozycji |
| pozycje[].kwota | Number \| null | Kwota w złotych; null to pozycja nadrzędna bez własnej kwoty |

#### 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.

| **Parametr** | **Typ** | **Opis** |
| --- | --- | --- |
| month | Number | Miesiąc za który sprawdzane zużycie |
| year | Number | Rok za który sprawdzane zużycie |

### Odpowiedź

#### Struktura JSON

```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
}
```

| **Pole** | **Typ** | **Opis** |
| --- | --- | --- |
| miesiac | String | Miesiąc (YYYY-MM) |
| zuzycie["<path>"] | Integer | Liczba odpytań, które zwróciły dane, w rozbiciu na endpointy. Zawsze te same cztery klucze |
| pula | Integer \| null | Ile odpytań mieści się w abonamencie |
| odpytania_razem | Integer | Suma odpytań ze wszystkich endpointów |
| koszt_netto_pln | Number \| null | Łączny koszt netto w PLN |
| model | String | standard, legacy, pakiet, abonament albo konto testowe |
| odpytania_w_abonamencie | Integer \| null | Ile z wykonanych odpytań mieści się w puli zawartej w abonamencie |
| odpytania_ponad_abonament | Integer \| null | Ile odpytań wykracza ponad pulę; tylko te są dodatkowo płatne |
| koszt_abonamentu_pln | Number \| null | Miesięczny abonament netto |
| koszt_ponad_abonament_pln | Number \| null | Koszt netto odpytań ponad pulę |
| pakiet | Object \| null | Pakiet odpytań kupiony online: odpytania_lacznie, odpytania_zuzyte, odpytania_pozostale, pierwszy_zakup, zamrozony (true, gdy trwa abonament). null, gdy konto nie ma pakietu |
| abonament | Object \| null | Abonament kupiony online, bieżący okres: status, okres_od, okres_do, anulowanie_na_koniec_okresu, pula, odpytania_w_okresie, odpytania_w_abonamencie, odpytania_ponad_abonament, koszt_ponad_abonament_pln, nastepne_obciazenie_pln (netto). null, gdy konto go nie ma |

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

| **Kod** | **Znaczenie** |
| --- | --- |
| 200 | Sukces. Brak wyników również jest sukcesem: `"data": []` |
| 400 | Coś jest nie tak z żądaniem - brakujący albo nieprawidłowy parametr. Ponowienie bez poprawki nic nie da |
| 401 | Nieprawidłowe albo brakujące dane uwierzytelniające |
| 402 | Wyczerpany limit bezpłatnych odpytań konta testowego. Stan trwały, ponawianie nie pomoże |
| 403 | Żądanie niedostępne dla tego konta. Ponowienie nic nie da |
| 429 | Żądanie odrzucone chwilowo. Ponów po krótkiej przerwie - odstęp podpowiada nagłówek `Retry-After` |
| 500 | Błąd po naszej stronie. Żądanie można ponowić |

**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:

```json
{ "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