Інформація для розробників

Використання API eRepository

Перед кожним шляхом з документації необхідно вказати https://guide.diia.gov.ua/api/v1/

Вивантаження даних ЦНАП до репозиторія

Для вивантаження замовлених послуг до репозиторія, ЦНАП має створити ендпоінт, за яким еРепозиторій може отримувати актуальну інформацію за певний період часу. Схема запиту та відповіді описана в документації. Кожен постачальник має строго дотримуватися схеми. Доступ до такого ендпоінту має бути обмеженим Basic Auth.
Приклад:
Ціль
Зібрати дані з 1 грудня 2019 року по 10 грудня 2019 року (включно)
Базовий URL ендпоінту ЦНАП
https://some_asc.gov.ua/appeals/
Логін та пароль (BasicAuth)
erepository, pa$$word
1. Ми робимо запит на URL https://some_asc.gov.ua/appeals/?start_date=2019-12-01&end_date=2019-12-10:
start_date = 2019-12-01 - перший день обраного діапазону у форматі "YYYY-MM-DD";
end_date = 2019-12-10 - останній день обраного діапазону у форматі "YYYY-MM-DD".
Додаємо HTTP-заголовок Authorization: Basic ZXJlcG9zaXRvcnk6cGEkJHdvcmQ=, де "ZXJlcG9zaXRvcnk6cGEkJHdvcmQ=" - результат кодування "erepository:pa$$word" у Base64
ЦНАП отримує всі створені або оновлені заяви в обраний період та серіалізує їх згідно з схемою. Наприклад, послуга, що була зареєстрована 1 листопада, а надана 5 грудня має входити до даного переліку.
Сервер повертає дані клієнту:
{
    "success": true,
    "next_page": "https://some_asc.gov.ua/appeals/?start_date=2019-12-01&end_date=2019-12-10&page=2",
    "entries": [
        {
        "appealId": "414060",
        "cnapCode": "123",
        "serviceCode": "00001",
        "appealRegDateTime": "2019-12-03T15:13:25.130Z",
        "appealStatus": "успішно надано",
        "answerReceiveDateTime": "2019-12-09T15:13:25.130Z",
        "applicantType": "фізична",
        "paymentAmount": "1092.5",
        "applicantGender": "жіноча",
        "applicantSocialStatus": "Безробітний",
        "applicantPhone": "+380987654321"
        },
        {...},
        {...}
    ]
}
                                
Якщо провайдер підтримує пагінацію - повний URL наступної сторінки має бути вказаний у next_page. При зверненні за цією адресою, клієнт має отримати наступну частину набору даних, серіалізовану ідентичним чином.
еРепозиторій зберігає дані до власне репозиторія.

Платформа для роботи з API

Для роботи з API зручно використовувати платформи такі як Postman або аналоги. У цій документації всі приклади наведені з використанням Postman.
Для початку роботи з API треба надати параметри авторизації: У розділі Authorization обираємо тип авторизації Type: Basic Auth та надаємо логін та пароль.
У обраного ендпоінту може бути два методи:
GET - запит на отримання даних. Достатньо вказати тип запиту "GET", параметри авторизації, посилання на ендпоінт та натиснути кнопку Send
POST - запит на додавання данних до системи. Наприклад - створення запису у репозиторії послуг (замовлення послуги). Такі запити потребують JSON-тіла з додатковими даними. Для POST запиту достатньо вказати тип "POST", параметри авторизації, посилання на ендпоінт, додати заголовок, що описує тип тіла - JSON: Content-Type: application/json
Також необхідно надати додаткові параметри відповідно до API документації. Та вказати тип даних raw, а праворуч обрати JSON та натиснути кнопку Send.

Робота з API Реєстру

Реєстр послуг - база даних, де зберігається інформація про послуги, доступ до редагування інформації про послуги має лише Адміністратор реєстру. Для отримання інформації про послуги з реєстру необхідно скористуватися запитами з API, що наведені у розділі "register" документації.
Детальна інформація про послугу з реєстру: https://guide.diia.gov.ua/api/v1/register/detail/{service_id}/. Тут service_id - унікальний ідентифікатор електронної послуги, що має вигляд 10001
Отримати список усіх сутностей реєстру: https://guide.diia.gov.ua/api/v1/register​/list​/
Отримати записи реєстру створені в певний день: https://guide.diia.gov.ua/api/v1/register/list/{date}/
date - дата створення запису у формі рррр-мм-дд. Наприклад 2019-09-18

Робота з API Репозиторія

Після того як громадяднин замовив деяку електронну послугу інформація про це потрапляє до репозиторія. Щоб замовити Послугу необхідно надати ідентифікатор послуги, свої паспортні дані, для деяких послуг також необхідно надати результат замовлення інших послуг. У репозиторії до роботи з послугою має доступ організація-власник, яка має право замовляти послугу, змінювати статуси її надання та надавати результат роботи послуги. Для детальної інформації про всі ендпоінти зверніться до розділу "repository" документації.
Створити запис у репозиторії послуг - Замовити послугу https://guide.diia.gov.ua/api/v1/repository/create/
{
    "public_service_identifier": "0200006001",
    "service_foreign_id": "14888",
    "client_inn": "0000000016",
    "client_unzr": "19860606-11616",
    "client_passport": "АВ123456"
}
                            
Деталі про замовлення певної послуги по її id та ідентифікатору користувача https://guide.diia.gov.ua/api/v1/repository/detail/{person_identifier}/{service_id}/
Деталі про замовлення певної послуги https://guide.diia.gov.ua/api/v1/repository/detail/{service_id}/
Список замовлених послуг, до яких має доступ проект: https://guide.diia.gov.ua/api/v1/repository/list/
Список замовлених послуг, до яких має доступ проект за певний день: https://guide.diia.gov.ua/api/v1/repository/list/{date}/
Список замовлених послуг, певним користувачем за певний день: https://guide.diia.gov.ua/api/v1/repository​/list​/{person_identifier}​/{date}/
Послуги замовлені певним користувачем https://guide.diia.gov.ua/api/v1/repository​/list​/{person_identifier}​/
Список замовлених послуг по внутрішньому ідентифікатору: https://guide.diia.gov.ua/api/v1/repository/detail/internal/{service_foreign_id}/
Список послуг замовлених певним користувачем по внутрішньому ідентифікатору: https://guide.diia.gov.ua/api/v1/repository/detail/{person_identifier}/internal/{service_foreign_id}/
Змінити статус замовленої послуги: https://guide.diia.gov.ua/api/v1/repository/statuses/create/ Приклад запиту:
{
    "service_id": "2b45eb6e-3e2a-4e4b-964f-234d7f9bc6f5",
    "service_status": "1",
    "service_status_comment": "Передано на перевірку",
    "representative": "Гершун Н.О."
}
                            
Отримати інформацію про статус деякої послуги: https://guide.diia.gov.ua/api/v1/repository/statuses/detail/{status_id}/

Повідомлення та діалоги

Створити діалог та надіслати повідомлення: https://guide.diia.gov.ua/api/v1/messages/create/ Приклад запиту:
{
    "dialog": {
        "id": 0,
        "repository_item": { },
        "repository_item_id": "5b6687b1-2b21-4d75-8dfd-c0558e0ac181",
        "recipient": "string"
    },
    "created_by": "provider",
    "type": 1,
    "subject": "dialog",
    "short_text": "head",
    "full_text": "text"
}
                        
Інформація про повідомлення https://guide.diia.gov.ua/api/v1/messages/detail/{message_id}/
Список усіх повідомлень https://guide.diia.gov.ua/api/v1/messages/list/
Список усіх повідомлень за певну дату https://guide.diia.gov.ua/api/v1/messages/list/{date}/
Інформація про діалог https://guide.diia.gov.ua/api/v1/dialogs​/detail​/{dialog_id}​/
Діалоги певного користувача https://guide.diia.gov.ua/api/v1/dialogs/list/{person_identifier}/

Тематичні області

Список всіх доступних категорій https://guide.diia.gov.ua/api/v1/categories/list/
Інформація про конкретну категорію https://guide.diia.gov.ua/api/v1/categories/detail/{thematic_area_id}/