Пошук інформації про контрагентів безпосередньо в панелі Списку банкрутств на сайті iMSiG.pl є зручним у окремих випадках.
Однак при більших обсягах (наприклад, сотні чи тисячі контрагентів, інтеграція з CRM або системами стягнення боргів) ручна обробка стає неефективною.
У таких випадках ми рекомендуємо використовувати API-інтерфейс, який дозволяє:
- автоматичну перевірку статусу боржників,
- періодичне завантаження вмісту оголошень,
- інтеграцію даних із внутрішніми системами (CRM, ERP, системи стягнення боргів).
У цьому посібнику ви дізнаєтеся, як завантажити повний текст оголошень про банкрутство та реструктуризацію щодо конкретного боржника на підставі реєстраційних номерів (NIP, KRS, REGON, PESEL).
Що таке API списку банкрутств?
API (Application Programming Interface) — це інтерфейс прикладного програмування, тобто набір правил і протоколів, що забезпечують безпосередню взаємодію між різними інформаційними системами.
Він працює як«цифровий міст», що дозволяє вашому програмному забезпеченню (наприклад, CRM або ERP) автоматично використовувати функції та ресурси бази даних MGBI без втручання людини.
Механізм API можна порівняти з віконцем у державній установі, де ваша система «надає» ідентифікаційний номер боржника, а у відповідь одразу отримує комплект документів.
Ключ авторизації
Кожен запит до API має бути автентифікований. Для цього використовується унікальний ключ API (ключ авторизації / токен), який ідентифікує вашу підписку та контролює доступні ліміти запитів.
Щоб отримати ключ API, увійдіть на сайт iMSiG.pl, перейдіть у вкладку «Список банкрутств», а потім відкрийте «Параметри послуги».
У нижній частині сторінки, у розділі«API», ти знайдеш свій ключ авторизації та посилання на повну документацію («Версія API»).
Пам’ятайте, що ключ API є спільним для всіх користувачів в рамках одного абонемента, а це означає, що головний обліковий запис і всі субоблікові записи працюють з одним і тим самим ключем (токен).
Завантаження повідомлень про боржника
Завантаження вмісту оголошень здійснюється за допомогою запитів типу GET (призначених для зчитування даних), що надсилаються до відповідного кінцевого пункту API.
1. Основна кінцева точка
GET /v2/announcements
Цей ендпойнт призначений для пошуку та завантаження оголошень із «Судового та економічного монітора» (MSiG) та Національного реєстру боржників (KRZ).
Детальний опис параметрів можна знайти в технічній документації: Список банкрутств — Документація API.
2. Ідентифікаційний номер боржника
Щоб завантажити оголошення щодо конкретного суб’єкта господарювання, необхідно вказати принаймні один ідентифікаційний номер:
- "nip=" – податковий номер (наприклад, 5213482472).
- "pesel=" – номер PESEL (фізичні особи, у тому числі у справах про банкрутство фізичних осіб).
- "krs=" – номер у Національному судовому реєстрі (товариства, фонди, асоціації),
- "regon=" – номер REGON (9- або 14-значний),
3. Важливий параметр: append_first_entry
У виданні «Monitor Sądowy i Gospodarczy» ідентифікаційні номери боржника (NIP, KRS, REGON) часто вказуються лише в першому оголошенні щодо конкретної справи.
Наступні повідомлення (наприклад, про план погашення боргу, зміну ліквідатора) можуть вже не містити ідентифікаційних номерів.
Тому в запиті обов’язково слід встановити такий параметр:
append_first_entry=true
Завдяки цьому API знаходить перше оголошення у справі, на його основі ідентифікує боржника та повертає всі оголошення, пов’язані з цією справою, навіть якщо вони не містять ідентифікатора в тексті.
Без цього параметра відповідь може бути неповною.
4. Приклад запиту
Припустимо, ви хочете завантажити оголошення про банкрутство та реструктуризацію щодо суб’єкта господарювання за номером податкового ідентифікаційного номера (NIP).
HTTP-запит повинен виглядати так:
GET /v2/announcements?nip=1234567890&append_first_entry=true HTTP/1.1
Host: api.imsig.pl
Authorization: [ключ авторизації]
Аналогічно, замість параметра «nip=» можна використовувати «krs=», «regon=» або «pesel=».
Структура даних
API повертає дані у структурованому форматі JSON, що дозволяє автоматично обробляти їх у будь-яких інформаційних системах.
Основні розділи відповіді
У відповіді API можна виділити такі групи даних:
- id — унікальний ідентифікатор оголошення в базі даних MGBI
- мета — технічна інформація про запис, зокрема дата публікації, а також дати першого та останнього оновлення оголошення в системі.
- суб’єкт — детальні дані про суб’єкта (або суб’єктів), якого стосується справа: назва, організаційно-правова форма, код PKD та адреса місцезнаходження.
- провадження — деталі судового провадження: назва суду, реєстраційні номери справи та дані ліквідатора або наглядача (назва або ім’я та прізвище, посада).
- ухвала— дані щодо конкретного рішення суду, наприклад, його дата.
- krz_entry / msig_entry — детальні параметри публікації залежно від джерела (розділ, підрозділ, посилання на оригінальне оголошення на урядовому порталі).
- content — повний текст оголошення, доступний у двох форматах: текстовому та HTML.
Повний перелік та опис полів можна знайти в документації API, у розділі «GET /v2/announcements»: Переглянути документацію
Коди відповідей HTTP
Найпоширеніші коди відповідей, які має підтримувати ваша система:
- 200 (Успіх): запит виконано правильно.
- 401 / 403 (Помилка авторизації): неправильний або відсутній ключ API.
- 429 (Перевищення ліміту): ви вичерпали весь ліміт запитів на цей місяць.
Приклад відповіді
{
"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"
}
}
Ліміти
Кожен запит API, надісланий на ендпоінт "/v2/announcements", зменшує місячний ліміт запитів, виділений для вашого абонемента.
Система розрізняє два основні ліміти для API залежно від дати публікації оголошень:
1️⃣ Актуальні оголошення — опубліковані до першого дня місяця, в якому активується ваша послуга.
2️⃣ Архівні оголошення — містять дані за період до першого дня місяця, в якому було активовано послугу. Завантаження цих даних витрачає окремий ліміт запитів для архівних оголошень. Його розмір залежить від вашого тарифного плану.
Ліміт зменшується при кожному виклику функції, незалежно від кількості оголошень, повернуті у відповіді, та від того, чи запит стосувався одного суб’єкта, чи всього періоду.
Створення запиту, який не поверне жодних результатів (порожній список), також зменшує доступний ліміт.
Пошук у панелі «Списки банкрутств» та запити, що виконуються автоматично через API, використовують один і той самий пул доступних запитів.
Рекомендуємо регулярно перевіряти стан лімітів, особливо на етапі інтеграційних тестів, під час першого запуску автоматизованих процесів та у разі роботи з великою кількістю ідентифікаторів.
Перевищення ліміту
Після вичерпання доступного ліміту запитів API поверне код відповіді: «429 – Too Many Requests».
Цей код означає, що місячний ліміт вичерпано, і подальші запити не будуть оброблятися до моменту його поновлення в новому розрахунковому періоді або підвищення абонентської плати (у будь-який час).
Це свідоме блокування, зумовлене правилами розрахунків за послугу, і його слід розглядати як сигнал про необхідність припинити подальші запити.
👉 Дізнайтеся більше про ліміти: Як перевірити використання лімітів у «Списку банкрутств»?
👉 Ознайомтеся з актуальною пропозицією та прайс-листом: Список банкрутств — прайс-лист
