MGBI надає комплексний API для отримання даних із державних реєстрів та облікових баз, зокрема з Реєстру платників ПДВ (Білого списку). Перелік джерел даних, доступних у цій службі, можна знайти на сторінці:
👉 Державні реєстри API
Цей посібник стосується API для Реєстру платників ПДВ (Білого списку), який ми надаємо в рамках продукту:
👉 API Реєстру платників ПДВ (API Білого списку)
Нижче ми описали, як за допомогою API можна завантажити актуальний перелік банківських рахунків суб’єкта господарювання з Реєстру платників ПДВ на підставі його ідентифікаційного номера платника податків (NIP).
Крок 1: Отримати ключ авторизації в API
Щоб отримати ключ авторизації, необхідний для виклику кінцевих точок, доступних в MGBI API, зв’яжіться з нами за допомогою контактної форми на сторінці продукту:
👉 Перелік платників ПДВ API (Білий список API)
Крок 2: Викличте кінцеву точку Create Refresh
Дані, що містяться у Реєстрі платників ПДВ, ми надаємо в MGBI API у вигляді набору даних з ідентифікатором pl-wpv-record.
Ця модель синхронізується за запитом, що означає, що в наших базах даних ми не маємо повної копії даних, доступних у вихідному реєстрі.
Щоб отримати з моделі актуальні дані щодо вказаного боржника, спочатку потрібно створити запит на їх завантаження з Реєстру платників ПДВ за допомогою ендпойнту Create Refresh.
👉 Документація ендпойнту Create Refresh
Приклад виклику ендпойнту Create Refresh з номером NIP:
POST /v1/refresh HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]
{
"query: {
"model": "pl-wpv-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-wpv-record надає кінцеву точку Get Records, яка повертає записи з повним текстом відповіді з Реєстру платників ПДВ щодо вказаного боржника.
👉 Документація кінцевої точки Get Records для моделі pl-wpv-record
Щоб отримати дані, витягнуті з вихідного реєстру у раніше створеному запиті, викличте кінцеву точку Get Records, передавши ідентифікатор запиту в параметрі refresh_id.
Приклад виклику кінцевої точки Get Records із ідентифікатором запиту:
GET /v1/models/pl-wpv-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.subject.
Приклад вмісту словника content.subject:
{
"name": [nazwa podmiotu],
"nip": [numer NIP],
"statusVat": [status podatnika VAT],
"regon": [numer REGON],
"krs": [numer KRS],
"workingAddress": [adres siedziby],
"representatives": [dane reprezentantów],
"authorizedClerks": [dane pełnomocników],
"partners": [dane wspólników],
"registrationLegalDate": [data rejestracji podanika VAT],
"accountNumbers": [lista numerów rachunków bankowych],
"hasVirtualAccounts": [informacja, czy podatnik posiada rachunki wirtualne]
}
Актуальний перелік банківських рахунків зазначеного суб’єкта господарювання, опублікований у Реєстрі платників ПДВ, можна переглянути у полі content.subject.accountNumbers.
Дізнайтеся більше:
👉 Структура даних у моделі pl-wpv-record
👉 Документація щодо кінцевих точок для моделі pl-wpv-record
