Co to jest API?

API to skrót od „Application Programming Interface”, co po polsku można tłumaczyć jako „Interfejs Programowania Aplikacji”. Jest to zestaw reguł i protokołów, które pozwalają różnym systemom informatycznym komunikować się ze sobą.

To rodzaj mostu, który pozwala jednej aplikacji korzystać z funkcji innej, bez konieczności rozumienia całego mechanizmu jej działania.

Aby to wyjaśnić w prosty sposób: wyobraź sobie, że API to menu w restauracji. Menu pokazuje dostępne potrawy (czyli funkcje), ale nie musisz wiedzieć, jak szef kuchni przygotowuje każde danie ani jak działa kuchnia.

Zamawiasz danie z menu, a kuchnia (inna aplikacja) przygotowuje je dla ciebie. W ten sposób korzystasz z menu (API), aby zamówić i otrzymać posiłek, nie martwiąc się o to, co dzieje się w kuchni.

Ogromna liczba odwiedzanych przez nas stron internetowych i aplikacji korzysta z różnych API. Robią to na przykład aplikacje mobilne obsługujące bankowość online.

Dzięki dostępowi do wewnętrznego API banku aplikacja zainstalowana w twoim telefonie może np. pobierać dane o kontach, transakcjach i saldzie, a jednocześnie bank nie musi jej udostępniać całego swojego systemu i wszystkich dostępnych w nim informacji.

Jak API Listy Upadłości MGBI może pomóc w pracy?

Integracja z API Listy Upadłości MGBI umożliwia zewnętrznym systemom IT pobieranie w dowolnym momencie wszystkich ogłoszeń publikowanych w Krajowym Rejestrze Zadłużonych i Monitorze Sądowym i Gospodarczym.

Łącząc systemy wykorzystywane w twojej firmie z naszą usługą będziesz w stanie np.

  • pobierać na bieżąco wszystkie nowe ogłoszenia publikowane w KRZ i MSiG,
  • odpytywać nasze API o ogłoszenia dotyczące pojedynczych dłużników na podstawie i numerów rejestrowych (np. NIP/PESEL),
  • zlecać przygotowanie zbiorczych raportów z ogłoszeniami spełniającymi podane kryteria i pobierać je.

Korzystanie z API Listy upadłości MGBI

Aby móc korzystać z API Listy upadłości MGBI, musisz najpierw zdobyć klucz do API (zwany też tokenem).

Klucz do API to rodzaj identyfikatora używanego do autoryzacji dostępu do danego interfejsu programowania aplikacji (API). Jest to element zabezpieczenia, który pomaga kontrolować, które aplikacje lub usługi mają uprawnienia do korzystania z API.

Aby uzyskać klucz, zaloguj się do usługi i wejdź w zakładkę „Parametry usługi”.

Dysponując kluczem możesz rozpocząć korzystanie z API Listy upadłości MGBI.

Odpytywanie API o pojedynczych dłużników

Aby uzyskać poprzez API odpowiedź na temat pojedynczego podmiotu gospodarczego, powinieneś znać przynajmniej jeden jego numer rejestrowy np. NIP.

Jeśli chcesz pobrać ogłoszenia upadłościowe i restrukturyzacyjne dotyczące podmiotu, żądanie HTTP wykonane przy użyciu programu CURL powinno wyglądać następująco:

curl https://api.imsig.pl/v2/announcements/?nip=5213482472&append_first_entry=true -H "Authorization: <klucz-api>"

W powyższym przykładzie https://api.imsig.pl/ oznacza adres serwera API, v2/ wersję API, a announcements pojedynczą funkcję API (tzw. endpoint) umożliwiającą pobieranie treści ogłoszeń z MSiG i KRZ w formacie JSON.

Klucz do API przekazywany jest w parametrze HTTP “Authorization”, a parametr “nip” oznacza oczywiście numer NIP interesującego nas podmiotu.

W zapytaniu ustawiliśmy wartość “true” w parametrze append_first_entry, co umożliwia uwzględnienie przy wyszukiwaniu danych podmiotu opublikowanych w pierwszym ogłoszeniu w ramach tego samego postępowania.

Jest to o tyle istotne, że w przypadku ogłoszeń publikowanych w MSiG numery rejestrowe dłużnika pojawiają się zazwyczaj tylko w pierwszym dotyczącym go ogłoszeniu. Odpytując API bez ustawiania tego parametru ryzykujemy pominięcie części ogłoszeń w zwracanej odpowiedzi.

Jeśli autoryzacja wspomnianym tokenem odbędzie się prawidłowo, to API zwróci listę ogłoszeń dotyczących postępowań prowadzonych wobec wskazanej firmy - oczywiście zakładając, że ogłosiła wcześniej upadłość albo rozpoczęła restrukturyzację.

Przykładowa treść pojedynczego ogłoszenia:

{
    "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"
    }
}

Struktura obiektu JSON z treścią ogłoszenia składa się z kilku grup informacji:

  • entity - informacje o podmiocie (lub podmiotach), których dotyczy ogłoszenie
  • proceeding - informacje o postępowaniu
  • order - informacje o postanowieniu sądu
  • msig_entry - informacje o źródle, jeśli ogłoszenie opublikowano w MSiG
  • krz_entry - informacje o źródłe danych, jeśli ogłoszenie opublikowano w KRZ
  • content - nieprzetworzona treść ogłoszenia
  • meta - dodatkowe informacje o ogłoszeniu

Pola dostępne w poszczególnych grupach informacji, a także wszystkie parametry, na podstawie których można wyszukiwać ogłoszenia, opisane są w dokumentacji API Listy upadłości dla endpointu GET /v2/announcements.

Pobieranie wszystkich nowych ogłoszeń przez API

Integracja z API Listy upadłości MGBI świetnie sprawdza się w sytuacji, gdy istnieje potrzeba regularnego importowania do wewnętrznego systemu informatycznego wszystkich ogłoszeń publikowanych na bieżąco w KRZ i MSiG.

Aby nie pominąć żadnego nowego lub zaktualizowanego ogłoszenia, przy każdym uruchomieniu programu do pobierania danych z API należy najpierw odpytać endpoint GET /v2/updates o wszystkie nowe aktualizacje, od poprzedniego sprawdzenia do chwili obecnej.

W zależności od źródła danych aktualizacje w Liście upadłości MGBI wprowadzane są z określoną częstotliwością:

  • Krajowy Rejestr Zadłużonych - co godzinę od 7:00 do 21:00
  • Monitor Sądowy i Gospodarczy - raz dziennie około godziny 11:00

Przykładowe zapytanie o listę aktualizacji ze wskazanego okresu wygląda następująco:

curl https://api.imsig.pl/v2/updates?creation_datetime_from=2023-09-22T00:00:00Z&creation_datetime_to=2023-09-23T00:00:00Z -H "Authorization: <klucz-api>"

W odpowiedzi na nie otrzymamy listę wszystkich aktualizacji danych, które zostały wprowadzone w naszej usłudze w dniu 22 września 2023 r:

[
  {
    'id': 8002,
    'creation_datetime': '2023-09-22T22:17:13.915000+02:00',
    'issue_date': '2023-09-22',
    'announcements_count': 1,
    'source': 'krz'
  },
  {
    'id': 8001,
    'creation_datetime': '2023-09-22T20:17:25.733000+02:00',
    'issue_date':'2023-09-22',
    'announcements_count': 5,
    'source': 'krz'
  },
  {
    'id': 8000,
    'creation_datetime': '2023-09-22T18:17:25.001000+02:00',
    'issue_date': '2023-09-22',
    'announcements_count': 5,
    'source': 'krz'
  },
  {
    'id': 7999,
    'creation_datetime': '2023-09-22T17:17:24.751000+02:00',
    'issue_date': '2023-09-22',
    'announcements_count': 5,
    'source': 'krz'
  },
  ...
]

Gdy API zwróci nam listę aktualizacji, możemy ustalić, dla których z nich nie pobieraliśmy jeszcze ogłoszeń. W tym celu powinniśmy zapisać ich identyfikatory z parametru “id”.

W następnym kroku dla każdego nieznanego wcześniej identyfikatora aktualizacji wywołujemy endpoint GET /v2/announcements z identyfikatorem przekazanym w parametrze "update_id":

curl https://api.imsig.pl/v2/announcements?update_id=8002 -H "Authorization: <klucz-api>"

W odpowiedzi otrzymamy listę wszystkich ogłoszeń wprowadzonych przez aktualizację o wskazanym identyfikatorze:

[
    {
        "id": "650df6494634a8d43457cad8",
        "meta": {
            "issue_date": "2023-09-22",
            "category": "K.0.8.48",
            "first_update_date": "2023-09-22",
            "last_update_date": "2023-10-23",
            "is_administrator_data_consistent": true,
            "is_correction": false,
            "is_entity_data_consistent": true
        },
        "entity": [
            {
                "info": {
                    "cleaned_name": "Geo-Term Polska SA",
                    "legal_form": "spółki akcyjne",
                    "ownership_type": "własność mieszana w sektorze prywatnym z przewagą własności krajowych osób fizycznych",
                    "primary_business": "74.10.Z Działalność w zakresie specjalistycznego projektowania",
                    "commencement_date": "1995-06-20"
                },
                "numbers": {
                    "nip": "9540020399",
                    "regon": "272624250",
                    "krs": "0000426336"
                },
                "address": {
                    "state": "małopolskie",
                    "powiat": "oświęcimski",
                    "gmina": "Oświęcim",
                    "town": "Oświęcim",
                    "street": "ul. Chemików",
                    "house_number": "1",
                    "zip_code": "32-600"
                }
            }
        ],
        "proceeding": {
            "court_name": "Sąd Rejonowy dla Krakowa-Śródmieścia w Krakowie",
            "court_department": "VIII Wydział Gospodarczy dla spraw upadłościowych i restrukturyzacyjnych",
            "signatures": [
                "KR1S/GRz-nu/49/2023",
                "KR1S/GRz/71/2023"
            ],
            "administrator_name": "Wojciech Zymek",
            "administrator_function": "syndyk",
            "administrator_licence_number": 104,
            "administrator_address": "Doradca Restrukturyzacyjny Wojciech Zymek  ul. Jesionowa 22",
            "administrator_zip_code": "40-158",
            "administrator_town": "Katowice",
            "administrator_source_url": "https://krz-rdr-gui-krz-rdr-prod.apps.ocp.prod.ms.gov.pl/rdr-api/wyszukiwarka/doradcy/103"
        },
        "order": {
            "order_date": "2023-09-22"
        },
        "krz_entry": {
            "chapter": 0,
            "section": 8,
            "subsection": 48,
            "signature": "20230922/00445",
            "issue_date": "2023-09-22",
            "url": "https://krz.ms.gov.pl/#!/application/KRZPortalPUB/1.4/KrzRejPubGui.SzczegolyObwieszczenia?params=JTdCJTIyaWRaZXduZXRyem55JTIyJTNBJTIyZjI2NmQwNzItNWNlMC00OGNhLTg2MjItMjFkN2UzZGMzM2Q0JTIyJTdE"
        },
        "content": {
            "text": "Sąd Rejonowy dla Krakowa-Śródmieścia w Krakowie VIII Wydział Gospodarczy dla spraw upadłościowych i restrukturyzacyjnych ul. Przy Rondzie 7, 31-547 Kraków, obwieszcza, że postanowieniem z 22 września 2023 r. wydanym w sprawie po wpłynięciu wniosku o zatwierdzenie układu w postępowaniu o zatwierdzenie układu dłużnika, którym jest GEO-TERM POLSKA spółka akcyjna z siedzibą w Oświęcimiu (KRS 0000426336), sygnatura akt KR1S/GRz/71/2023, postanowił:\n\nna podstawie art. 165 ust. 1 w zw. z art. 223 ust. 1 ustawy z dnia 15 maja 2015 r. Prawo restrukturyzacyjne odmówić zatwierdzenia układu.\n\nNa niniejsze postanowienie przysługuje zażalenie do Sądu Okręgowego w Krakowie XII Wydział Gospodarczy Odwoławczy za pośrednictwem Sądu Rejonowego dla Krakowa-Śródmieścia w Krakowie VIII Wydział Gospodarczy dla spraw upadłościowych i restrukturyzacyjnych. Zażalenie należy wnieść w terminie dwóch tygodni od dnia niniejszego obwieszczenia. Zażalenie podlega opłacie w wysokości 200,00 zł. Sąd odrzuci zażalenie, jeżeli będzie ono spóźnione, nieopłacone lub dotknięte brakami, które nie zostaną usunięte mimo wezwania.",
            "html": "
Sąd Rejonowy dla Krakowa-Śródmieścia w Krakowie VIII Wydział Gospodarczy dla spraw upadłościowych i restrukturyzacyjnych ul. Przy Rondzie 7, 31-547 Kraków, obwieszcza, że postanowieniem z 22 września 2023 r. wydanym w sprawie po wpłynięciu wniosku o zatwierdzenie układu w postępowaniu o zatwierdzenie układu dłużnika, którym jest GEO-TERM POLSKA spółka akcyjna z siedzibą w Oświęcimiu (KRS 0000426336), sygnatura akt KR1S/GRz/71/2023, postanowił:
na podstawie art. 165 ust. 1 w zw. z art. 223 ust. 1 ustawy z dnia 15 maja 2015 r. Prawo restrukturyzacyjne odmówić zatwierdzenia układu.
Na niniejsze postanowienie przysługuje zażalenie do Sądu Okręgowego w Krakowie XII Wydział Gospodarczy Odwoławczy za pośrednictwem Sądu Rejonowego dla Krakowa-Śródmieścia w Krakowie VIII Wydział Gospodarczy dla spraw upadłościowych i restrukturyzacyjnych. Zażalenie należy wnieść w terminie dwóch tygodni od dnia niniejszego obwieszczenia. Zażalenie podlega opłacie w wysokości 200,00 zł. Sąd odrzuci zażalenie, jeżeli będzie ono spóźnione, nieopłacone lub dotknięte brakami, które nie zostaną usunięte mimo wezwania.
",
            "url": "https://www.imsig.pl/lista-upadlosci/ogloszenia/650df6494634a8d43457cad8"
        }
    },
    ...
]

Aby upewnić się, że wszystkie ogłoszenia z danej aktualizacji zostały poprawnie pobrane, warto porównać liczbę zwróconych z endpointu ogłoszeń z wartością parametru "announcements_count" dla tej aktualizacji.

Jeśli wszystko się zgadza, to pobrane ogłoszenia można zaimportować do bazy w wewnętrznym systemie IT.

Szczegółowe informacje o innych możliwościach API Listy upadłości MGBI dostępne są w dokumentacji dostępnej na stronie:

https://www.imsig.pl/inne/dokumentacja-api#tag/announcements_iapi