Jak pobrać przez API treść ogłoszeń o upadłości i restrukturyzacji dłużnika?

Wyszukiwanie informacji o kontrahentach bezpośrednio w panelu Listy upadłości w serwisie iMSiG.pl jest wygodne przy pojedynczych sprawach.

Przy większej skali (np. setkach lub tysiącach kontrahentów, integracji z CRM lub systemami windykacyjnymi), ręczna obsługa staje się jednak nieefektywna.

W takich przypadkach rekomendujemy wykorzystanie interfejsu API, który umożliwia:

• automatyczną weryfikację statusu dłużników,
• cykliczne pobieranie treści ogłoszeń,
• integrację danych z systemami wewnętrznymi (CRM, ERP, systemy windykacyjne).

W tym poradniku dowiesz się jak pobrać pełną treść ogłoszeń o upadłości i restrukturyzacji dla konkretnego dłużnika na podstawie numerów rejestrowych (NIP, KRS, REGON, PESEL).

Czym jest API Listy upadłości?

API (Application Programming Interface) to interfejs programowania aplikacji, czyli zestaw reguł i protokołów umożliwiających różnym systemom informatycznym bezpośrednią komunikację między sobą.

Działa on jak "cyfrowy most", który pozwala Twojemu oprogramowaniu (np. CRM lub ERP) automatycznie korzystać z funkcji i zasobów bazy MGBI bez udziału człowieka.

Mechanizm API można porównać do okienka w urzędzie, w którym Twój system "podaje" identyfikator dłużnika, a w odpowiedzi natychmiast otrzymuje komplet dokumentów.

Klucz autoryzacji

Każde zapytanie do API musi być uwierzytelnione. Służy do tego unikalny klucz API (klucz autoryzacji / token), który identyfikuje Twój abonament i kontroluje dostępne limity zapytań.

Aby pozyskać klucz API zaloguj się w serwisie iMSiG.pl, wejdź w zakładkę "Lista upadłości", a następnie otwórz "Parametry usługi".

Na dole strony, w segmencie „API” znajdziesz swój klucz autoryzacji oraz link do pełnej dokumentacji ("Wersja API").

Pobieranie ogłoszeń o dłużniku

Pobieranie treści ogłoszeń odbywa się za pomocą zapytań typu GET (służących do odczytu danych) kierowanych do odpowiedniego endpointu API.

1. Główny endpoint

GET /v2/announcements

Powyższy endpoint służy do wyszukiwania i pobierania ogłoszeń z Monitora Sądowego i Gospodarczego (MSiG) oraz Krajowego Rejestru Zadłużonych (KRZ).

Szczegółowy opis parametrów znajdziesz w dokumentacji technicznej: Lista upadłości - Dokumentacja API.

2. Identyfikator dłużnika

Aby pobrać ogłoszenia dotyczące konkretnego podmiotu, należy podać co najmniej jeden numer identyfikacyjny:

• "nip=" – numer identyfikacji podatkowej (np. 5213482472).
• "pesel=" – numer PESEL (osoby fizyczne, w tym upadłość konsumencka).
• "krs=" – numer Krajowego Rejestru Sądowego (spółki, fundacje, stowarzyszenia),
• "regon=" – numer REGON (9- lub 14-cyfrowy),

3. Ważny parametr: append_first_entry

W Monitorze Sądowym i Gospodarczym identyfikatory dłużnika (NIP, KRS, REGON) często występują wyłącznie w pierwszym ogłoszeniu dla danej sprawy.

Kolejne obwieszczenia (np. o planie spłaty, zmianie syndyka) mogą już nie zawierać numerów identyfikacyjnych.

Dlatego w zapytaniu koniecznie należy ustawić parametr:

append_first_entry=true

Dzięki temu API odnajduje pierwsze ogłoszenie w sprawie, na jego podstawie identyfikuje dłużnika i zwraca wszystkie ogłoszenia powiązane z tym postępowaniem, nawet jeśli nie zawierają identyfikatora w treści.

4. Przykładowe zapytanie

Załóżmy, że chcesz pobrać ogłoszenia upadłościowe i restrukturyzacyjne dotyczące podmiotu na podstawie numeru NIP.

Żądanie HTTP powinno wyglądać tak:

GET /v2/announcements?nip=1234567890&append_first_entry=true HTTP/1.1
Host: api.imsig.pl
Authorization: [klucz autoryzacji]

Analogicznie zamiast parametru "nip=" możesz użyć "krs=", "regon=" lub "pesel=".

Struktura danych

API zwraca dane zwracane są w ustrukturyzowanym formacie JSON, co umożliwia ich automatyczne przetwarzanie w dowolnych systemach informatycznych.

Główne sekcje odpowiedzi

W odpowiedzi API można wyróżnić następujące grupy danych:

• id - unikalny identyfikator ogłoszenia w bazie MGBI

• meta - informacje techniczne o rekordzie, m.in. data publikacji oraz daty pierwszej i ostatniej aktualizacji ogłoszenia w systemie.

• entity - szczegółowe dane podmiotu (lub podmiotów), którego dotyczy sprawa: nazwa, forma prawna, kod PKD oraz adres siedziby.

• proceeding - szczegóły postępowania sądowego: nazwa sądu, sygnatury akt oraz dane syndyka lub nadzorcy (nazwa bądź imię i nazwisko, funkcja).

• order - dane dotyczące konkretnego postanowienia sądu, np. jego data.

• krz_entry / msig_entry - szczegółowe parametry publikacji w zależności od źródła (rozdział, sekcja, link do oryginalnego obwieszczenia w portalu rządowym).

• content - pełna treść ogłoszenia udostępniana w dwóch formatach: tekstowym oraz HTML.

Pełny wykaz i opis pól znajdziesz w dokumentacji API, w sekcji "GET /v2/announcements": Sprawdź dokumentację

Kody odpowiedzi HTTP

Najczęstsze kody odpowiedzi, które powinien obsłużyć Twój system:

• 200 (Sukces): zapytanie wykonane poprawnie.
• 401 / 403 (Błąd autoryzacji): niepoprawny lub brakujący klucz API.
• 429 (Przekroczenie limitu): wykorzystałeś całą pulę zapytań w danym miesiącu.

Przykładowa odpowiedź

{
"id": "651d667e2323c65e8e17e295",
"meta": {
    "issue_date": "2023-10-04",
    "category": "K.0.3.16",
    "first_update_date": "2023-10-04",
    "last_update_date": "2023-11-05",
    "is_administrator_data_consistent": true,
    "is_correction": false,
    "is_entity_data_consistent": true
},
"entity": [
    {
    "info": {
        "cleaned_name": "VB Leasing SA",
        "legal_form": "spółki akcyjne",
        "ownership_type": "własność prywatna krajowa pozostała",
        "primary_business": "64.91.Z Leasing finansowy",
        "commencement_date": "2008-04-02"
     },
    "numbers": {
        "nip": "5213482474",
         "regon": "141374292",
         "krs": "0000307665"
     },
    "address": {
         "state": "dolnośląskie",
         "powiat": "Wrocław",
         "gmina": "Wrocław-Fabryczna",
         "town": "Wrocław",
         "street": "ul. Fabryczna",
         "house_number": "6",
         "zip_code": "53-609"
     }
   }
],
"proceeding": {
    "court_name": "Sąd Rejonowy dla Wrocławia-Fabrycznej we Wrocławiu",
    "court_department": "VIII Wydział Gospodarczy",
    "signatures": [
        "WR1F/GR/16/2023",
        "WR1F/GRs/5/2023"
    ],
    "administrator_name": "Ams Restrukturyzacje sp. z o.o.",
    "administrator_function": "syndyk",
    "administrator_address": "ul. Pawła Włodkowica 10 lok. 3",
    "administrator_zip_code": "50-072","administrator_town": "Wrocław"
  },
  "order": {},
  "krz_entry": {
    "chapter": 0,
    "section": 3,
    "subsection": 16,
    "signature": "20231004/00341",
    "issue_date": "2023-10-04",
    "url": "https://krz.ms.gov.pl/#!/application/KRZPortalPUB/1.4/KrzRejPubGui.SzczegolyObwieszczenia?params=JTdCJTIyaWRaZXduZXRyem55JTIyJTNBJTIyZWMzYTllODctOTljZC00YTg2LTljNzQtOThkZDQxZmI1MjFhJTIyJTdE"
  },
  "content": {
    "text": "Sąd Rejonowy dla Wrocławia-Fabrycznej we Wrocławiu, VIII Wydział Gospodarczy, ul. Poznańska 16, 53-630 Wrocław, obwieszcza, że Postanowienie Sądu o otwarciu postępowania sanacyjnego wydane w postępowaniu WR1F/GR/16/2023, w dniu 25 lipca 2023 r., o oznaczeniu WR1F/GR/16/2023/39, w zakresie rozstrzygnięcia w przedmiocie otwarcia postępowania restrukturyzacyjnego jest prawomocne z dniem 25 lipca 2023 r.",
    "html": "Sąd Rejonowy dla Wrocławia-Fabrycznej we Wrocławiu, VIII Wydział Gospodarczy, ul. Poznańska 16, 53-630 Wrocław, obwieszcza, że Postanowienie Sądu o otwarciu postępowania sanacyjnego wydane w postępowaniu WR1F/GR/16/2023, w dniu 25 lipca 2023 r., o oznaczeniu WR1F/GR/16/2023/39, w zakresie rozstrzygnięcia w przedmiocie otwarcia postępowania restrukturyzacyjnego jest prawomocne z dniem 25 lipca 2023 r.",
    "url": "https://www.imsig.pl/lista-upadlosci/ogloszenia/651d667e2323c65e8e17e295"
  }
}

Limity

Każde zapytanie API skierowane do endpointu "/v2/announcements" pomniejsza miesięczną pulę zapytań przypisaną do Twojego abonamentu.

System rozróżnia dwa podstawowe limity dla API, w zależności od daty publikacji ogłoszeń:

1️⃣ Ogłoszenia aktualne - opublikowane przed pierwszym dniem miesiąca aktywacji Twojej usługi.

2️⃣ Ogłoszenia archiwalne - obejmują dane sprzed pierwszego dnia miesiąca aktywacji usługi. Ich pobieranie zużywa osobny limit zapytań dla ogłoszeń archiwalnych. Jego wysokość zależy od Twojego planu abonamentowego.

Limit jest pomniejszany przy każdym wywołaniu funkcji, niezależnie od liczby ogłoszeń zwróconych w odpowiedzi oraz faktu, czy zapytanie dotyczyło jednego podmiotu, czy całego okresu.

Wygenerowanie zapytania, które nie zwróci żadnych wyników (pusta lista), również pomniejsza dostępny limit.

Przekroczenie limitu

Po wykorzystaniu dostępnej puli zapytań API zwróci kod odpowiedzi: "429 – Too Many Requests".

Kod ten oznacza, że miesięczny limit został wyczerpany i kolejne zapytania nie będą realizowane do momentu jego odnowienia w nowym okresie rozliczeniowym lub podniesienia abonamentu (w dowolnym momencie).

👉 Dowiedz się więcej o limitach: Jak sprawdzić wykorzystanie limitów w Liście upadłości?

👉 Sprawdź aktualną ofertę i cennik: Lista upadłości - cennik