Як за допомогою API отримати список фактичних бенефіціарів суб’єкта господарювання з CRBR?

MGBI надає комплексний API для отримання даних із державних реєстрів та облікових баз, зокрема з Центрального реєстру фактичних бенефіціарів (CRBR).

Перелік джерел даних, доступних у цій службі, можна знайти на сторінці:
👉 API публічних реєстрів

Цей посібник стосується API для пошукової системи суб’єктів CRBR, яку ми надаємо в рамках продукту:
👉 Центральний реєстр фактичних бенефіціарів API (CRBR API) — Пошукова система суб’єктів

Нижче ми описали, як за допомогою API можна завантажити список фактичних бенефіціарів суб’єкта господарювання з CRBR на основі його податкового номера.

Крок 1: Отримати ключ авторизації в API

Щоб отримати ключ авторизації, необхідний для виклику кінцевих точок, доступних в MGBI API, зв’яжіться з нами за допомогою контактної форми на сторінці продукту:
👉 API Центрального реєстру фактичних бенефіціарів (CRBR API) — Пошукова система суб’єктів

Крок 2: Викличте кінцеву точку Create Refresh

Дані, доступні в Пошуковій системі суб’єктів CRBR, ми надаємо в MGBI API у вигляді моделі даних з ідентифікатором pl-crbr-wp-record.

Ця модель синхронізується за запитом, що означає, що в наших базах даних ми не маємо повної копії даних, доступних у вихідному реєстрі.

Щоб отримати з моделі актуальні дані щодо вказаного боржника, спочатку потрібно створити запит на їх отримання з CRBR за допомогою ендпойнту Create Refresh.
👉 Документація ендпойнту Create Refresh

Приклад виклику ендпойнту Create Refresh з номером NIP:

POST /v1/refresh HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]

{
    "query: {
        "model": "pl-crbr-wp-record",
        "identifiers.pl_nip": [numer NIP]
    }
}

При правильному виклику кінцевої точки Create Refresh у відповідь повертається словник, що містить ідентифікатор запиту в полі id.

Крок 3: Викличте кінцеву точку Get Refresh

Запити на отримання даних із вихідного реєстру зазвичай виконуються протягом від кількох до кількох десятків секунд з моменту їх створення за допомогою ендпойнту Create Refresh.

Щоб перевірити поточний статус замовлення, викличте ендпоінт Get Refresh, вказавши в URL-адресі його ідентифікатор, отриманий на попередньому кроці.
👉 Документація ендпоінту Get Refresh

Приклад виклику ендпойнту Get Refresh з ідентифікатором запиту:

GET /v1/refresh/[ідентифікатор запиту] HTTP/1.1
Host: api.mgbi.pl
Authorization: [ключ авторизації]

Якщо у повернутому словнику поле status має значення pending, запит ще виконується, і через кілька секунд слід знову викликати кінцеву точку Get Refresh.

Якщо поле «статус» має значення «success», це означає, що запит виконано, а дані щодо вказаного боржника вже отримано з вихідного реєстру.

Крок 4: Викличте кінцеву точку Get Records

API для моделі pl-crbr-wp-record надає кінцеву точку Get Records, яка повертає записи з повним текстом відповіді з Пошукової системи суб’єктів CRBR щодо вказаного боржника.
👉 Документація кінцевої точки Get Records для моделі pl-crbr-wp-record

Щоб отримати дані, витягнуті з вихідного реєстру у раніше створеному запиті, викличте кінцеву точку Get Records, передавши ідентифікатор запиту в параметрі refresh_id.

Приклад виклику ендпойнту Get Records з ідентифікатором запиту:

GET /v1/models/pl-crbr-wp-record/records?refresh_id=[ідентифікатор запиту] HTTP/1.1
Host: api.mgbi.pl
Authorization: [ключ авторизації]

Крок 5: З’ясуйте зі відповіді список фактичних бенефіціарів

При правильному виклику кінцевої точки Get Records у відповідь повертається список записів, що відповідають заданим критеріям.

У наведеному вище прикладі кінцева точка повинна повернути список результатів, що містить один запис:

{
    "count": 1,
    "pages": 1,
    "results": [
        {
            "id": [identyfikator rekordu],
            "identifiers": [identyfikatory podmiotu],
            "version": [informacje o wersji rekordu],
            "content": [treść odpowiedzi z wyszukiwarki],
            "meta": [metadane rekordu]
        }
    ]
}

Список фактичних бенефіціарів суб’єкта господарювання доступний у полі content.raw_result.listaBeneficjentow.

Кожен елемент списку містить дані про окремого бенефіціара, такі як ім’я та прізвище, країни громадянства або інформацію про частку чи інші права.

Приклад вмісту елемента:

{
    "pesel": [numer PESEL],
    "dataUrodzenia": [data urodzenia],
    "imiePierwsze": [pierwsze imię],
    "imieDrugieINastepne": [drugie imię],
    "nazwisko": [nazwisko],
    "obywatelstwo": [kraje obywatelstwa],
    "panstwoZamieszkania": [państwo zamieszkania],
    "nazwaBeneficjentaGrupowego": [nazwa beneficjenta grupowego],
    "informacjeOUprawnieniachTrust": [informacje o uprawnieniach w truście],
    "informacjeOUdzialeLubUprawnieniach": [informacje o udziale lub innych uprawnieniach],
    "idTech": [wewnętrzny identyfikator beneficjenta]
}

Дізнайтеся більше:
👉 Структура даних у моделі pl-crbr-wp-record
👉 Документація щодо кінцевих точок для моделі pl-crbr-wp-record