Вітаємо на сайті документації по openprocurement.integrations.edr!¶
Будь ласка повідомляйте про всі проблеми та поради покращень через розсилку або через issue tracker.
Зміст:
Огляд¶
Integrations EDR процедура це плагін до Open Procurement API software.
REST-ful інтерфейс для плагіна відповідає основним принципам дизайну програмного забезпечення.
Домовленості¶
Цей плагін підтримує домовленності Open Procurement API.
Основні задачі¶
Процедура інтеграції з ЄДР створена для отримання інформації з Единого Державного Реєстру юридичних осіб та фізичних осіб-підприємців (надалі ЕДР) за номером Єдиного державного реєстру підприємств та організацій України(надалі ЄДРПОУ) для юридичних осіб або Індивідуального податкового номеру ( надалі ІПН ) для фізичної особи-підприємця. Якщо треба знайти фізичну особу-підприємця, яка не має ІПН - пошук проводиться по серії та номеру паспорта).
Стан проекту¶
Цей проект активно розробляється і має пілотні встановлення.
Репозиторій цього проекту є на GitHub: https://github.com/openprocurement/openprocurement.integrations.edr
Повідомляйте про всі проблеми та поради через issue tracker (реєстрація на GitHub обов’язкова). Загальне обговорення відбувається через розсилку Open Procurement General .
Стабільність API¶
API є дуже нестабільним. Хоча точки входу API будуть відносно стабільними, формати обміну даними будуть часно змінюватись. Зміни в API обговорюються через Open Procurement API розсилку.
Туторіал¶
Базовий запит¶
Для того щоб отримати інформацію з Єдиного Державного реєстру за допомогою ЄДРПОУ Вам необхідно зробити запит до точки входу api/1.0/verify, передаючи даний ЄДРПОУ як GET параметр:
GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
"meta": {
"sourceDate": "2017-04-25T11:56:36+00:00"
},
"data": [
{
"registrationStatusDetails": "зареєстровано",
"x_edrInternalId": 2842335,
"registrationStatus": "registered",
"identification": {
"url": "https://zqedr-api.nais.gov.ua/1.0/subjects/2842335",
"schema": "UA-EDR",
"id": "14360570",
"legalName": "АКЦІОНЕРНЕ ТОВАРИСТВО КОМЕРЦІЙНИЙ БАНК \"ПРИВАТБАНК\""
}
}
]
}
Відповідь складається з наступних полів: x_edrInternalId, registrationStatusDetails, registrationStatus, identification.schema, identification.id, identification.legalName, identification.url.
x_edrInternalId - унікальний ідентифікатор суб’єкта ,
registrationStatusDetails - текстове відображення стану суб’єкта(укр),
registrationStatus - текстове відображення стану суб’єкта,
- identification.schema - “UA-EDR”
identification.id - ЄДРПОУ; якщо суб’єкт - фізична особа підприємець - замість ІПНа система поверне десять нулів, бо ці дані є конфіденційною інформацією,
identification.legalName - назва,
identification.url - посилання на екземпляр з деталізованою інформацію.
Також відповідь містить поле meta.sourceDate - дата отримання інформації від ЄДР API.
Запит з індивідуальним податковим номером¶
Якщо Вам необхідно отримати інформацію для фізичних осіб-підприємців тоді необхідно відправити запит з ІПН:
GET /api/1.0/verify?id=1234567891 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
"meta": {
"sourceDate": "2017-04-25T11:56:36+00:00"
},
"data": [
{
"registrationStatusDetails": "зареєстровано",
"x_edrInternalId": 2842335,
"registrationStatus": "registered",
"identification": {
"url": "https://zqedr-api.nais.gov.ua/1.0/subjects/2842335",
"schema": "UA-EDR",
"id": "1234567891",
"legalName": "АКЦІОНЕРНЕ ТОВАРИСТВО КОМЕРЦІЙНИЙ БАНК \"ПРИВАТБАНК\""
}
}
]
}
Помилки¶
Відповідь на невдалий запит містить список з текстовим відображенням помилками, коду помилки в тілі відповіді та статусу.
API повертає таку відповідь, коли вичерпано обмеження запитів до ресурсу:
GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 429 Too Many Requests
Content-Type: application/json; charset=UTF-8
Retry-After: 26
{
"status": "error",
"errors": [
{
"description": [
{
"message": "Retry request after 26 seconds."
}
],
"name": "data",
"location": "body"
}
]
}
Відповідь матиме відповідний текст та час, через який сплине це обмеження.
Коли даний ЄДРПОУ (ІПН або серія на номер паспорту) не знайдений, відповідь містить повідомлення EDRPOU not found.
GET /api/1.0/verify?id=123 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 404 Not Found
Content-Type: application/json; charset=UTF-8
{
"status": "error",
"errors": [
{
"description": [
{
"meta": {
"sourceDate": "2017-04-25T11:56:36+00:00"
},
"error": {
"errorDetails": "Couldn't find this code in EDR.",
"code": "notFound"
}
}
],
"name": "data",
"location": "body"
}
]
}
Якщо GET-параметр code або passport відсутній в запиті, то ЕДР-проксі поверне наступну помилку:
GET /api/1.0/verify HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 403 Forbidden
Content-Type: application/json; charset=UTF-8
{
"status": "error",
"errors": [
{
"description": [
{
"message": "Wrong name of the GET parameter"
}
],
"name": "data",
"location": "body"
}
]
}
Інші помилки виникають на стороні ЕДР-проксі та можуть мати вигляд одної з наступних помилок:
GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 403 Forbidden
Content-Type: application/json; charset=UTF-8
{
"status": "error",
"errors": [
{
"description": [
{
"message": "Invalid or expired token.",
"code": 2
}
],
"name": "data",
"location": "body"
}
]
}
або
GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cGxhdGZvcm06cGxhdGZvcm0=
Host: api-sandbox.openprocurement.org
Response: 403 Forbidden
Content-Type: application/json; charset=UTF-8
{
"status": "error",
"errors": [
{
"description": [
{
"message": "Payment required.",
"code": 5
}
],
"name": "data",
"location": "body"
}
]
}
Ці помилки не зв’язані з данними із запиту.
Ідентифікація за допомогою бота¶
Файл-довідка¶
Для користувачів групи robot вихідна точка api/1.0/verify буде повертати розширену інформацію. Запит має наступний вигляд:
GET /api/1.0/verify?id=14360570 HTTP/1.0
Authorization: Basic cm9ib3Q6cm9ib3Q=
Host: api-sandbox.openprocurement.org
Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
"meta": {
"sourceDate": "2017-04-25T11:56:36+00:00",
"detailsSourceDate": ["2017-04-25T11:56:36+00:00"]
},
"data": [{
"additionalActivityKinds": [
{
"scheme": "КВЕД",
"id": "64.92",
"description": "Інші види кредитування"
},
{
"scheme": "КВЕД",
"id": "64.99",
"description": "Надання інших фінансових послуг (крім страхування та пенсійного забезпечення), н. в. і. у."
},
{
"scheme": "КВЕД",
"id": "66.11",
"description": "Управління фінансовими ринками"
},
{
"scheme": "КВЕД",
"id": "66.12",
"description": "Посередництво за договорами по цінних паперах або товарах"
},
{
"scheme": "КВЕД",
"id": "66.19",
"description": "Інша допоміжна діяльність у сфері фінансових послуг, крім страхування та пенсійного забезпечення"
}
],
"management": "ЗАГАЛЬНІ ЗБОРИ",
"name": "ПАТ КБ \"ПРИВАТБАНК\"",
"registrationStatusDetails": "зареєстровано",
"registrationStatus": "registered",
"identification": {
"scheme": "UA-EDR",
"id": "14360570",
"legalName": "АКЦІОНЕРНЕ ТОВАРИСТВО КОМЕРЦІЙНИЙ БАНК \"ПРИВАТБАНК\""
},
"address": {
"postalCode": "49094",
"countryName": "УКРАЇНА",
"streetAddress": "Дніпропетровська обл., місто Дніпропетровськ, Жовтневий район"
},
"founders": [
{
"role_text": "засновник",
"role": 4,
"name": "АКЦІОНЕРИ - ЮРИДИЧНІ ТА ФІЗИЧНІ ОСОБИ"
}
],
"activityKind": {
"scheme": "КВЕД",
"id": "64.19",
"description": "Інші види грошового посередництва"
}
}]
}
Файл-довідка має назву edr_identification.yaml та завантажується окремою компонентою при настанні статусу` active.pre-qualification` для тендерів з procurementMethodType: aboveThresholdEU, competitiveDialogueUA, competitiveDialogueEU та ` active.qualification` для тендерів з procurementMethodType: aboveThresholdUA, aboveThresholdUA.defense, aboveThresholdEU, competitiveDialogueUA.stage2, competitiveDialogueEU.stage2 за умови, що identifier.scheme має значення UA-EDR. Витяг завантажується в об’єкт award/qualification зі статусом pending та має тип documentType: registerExtract. Якщо identifier:id не знайдено в Єдиному Державному реєстрі, то файл містить наступну помилку {error: {code: notFound, errorDetails: Couldn’t find this code in EDR.}}.
Також файл містить службову інформацію в блоці meta.
author - автор файлу-довідки, має значення IdentificationBot,
id - унікальний ідентифікатор довідки,
sourceDate - дата відповіді від Єдиного Державного реєстру,
sourceRequests -список з номерами запитів до API, EDR-proxy, за допомогою яких було сформовано довідку,
version - версію формату довідки.
Значення поля meta.version зараз дорівнює 1.1.1. Перше число відповідає за major версію (наприклад видалення елемента, перейменування, переміщення), друге число відповідає за minor версію (додавання додаткових атрибутів), третє - bugfix версія (зміни, що не змінюють об’єм чи атрибути інформації, але виправляють помилки). Наприклад зміна назви файлу з edr_request.yaml на edr_identification.yaml це збільшення major версії, а додавання поля meta.author це збільшення minor версії.
Змінено значення поля meta.version на 1.2.1 у зв’язку з додаванням в файл-довідку наступних полів
registrationStatusDetails - текстове відображення стану суб’єкта(укр),
registrationStatus - текстове відображення стану суб’єкта.
Аутентифікація¶
Для аутентифікації EDR Proxy використовується схема базової аутентифікації (див. RFC 2617#section-2).
У цій схемі:
Ім’я користувача - ідентифікатор майданчика
Пароль - API ключ для EDR Proxy
Індекси та таблиці¶
Індекс
Пошук