.. title:: Точка входу "Арбітражний керуючий" для API проекту "Суд на долоні"

.. meta::
    :desctription: Точка входу "Арбітражний керуючий" для API проекту "Суд на долоні"
    :robots: index, follow
    :viewport: width=device-width, initial-scale=1
    :language: uk
    :keywords: Суд на долоні, API, арбітражний керуючий
    :author: Кирило Захаров
    :copyright: Суд на долоні

Арбітражний керуючий
====================

Точка входу "Арбітражний керуючий" повертає інформацію стосовно арбітражних керуючих України.

Загальна інформація
-------------------

Інформація про арбітражних керуючих з даних Єдиного реєстру нотаріусів Міністерства юстиції України, опублікованого на `Національному порталі відкритих даних <https://data.gov.ua/dataset/d7cca6b1-863c-4c7d-a90b-6d024a68a4f7>`_.

Уся інформація щодо юридичних осіб оновлюється один раз на 1-2 тижні.


Кількість арбітражних керуючих
------------------------------

GET-запит за адресою ``https://api.conp.com.ua/api/v1.0/arbitrage`` повертає загальну кількість арбітражних керуючих в системі

.. sourcecode:: http

  GET /arbitrage HTTP/1.0
  Host: https://api.conp.com.ua/api/v1.0

  { "message": 3155 }

-----

Отримання інформації про арбітражного керуючого
-----------------------------------------------

GET-запит за адресою ``https://api.conp.com.ua/api/v1.0/arbitrage/:id`` повертає інормацію про арбітражного керуючого за `відповідною схемою даних <arbitrage.html>`_ `. Де id - номер свідоцтва арбітражного керуючого.

.. sourcecode:: http

  GET /arbitrage/АВ566963 HTTP/1.0
  Host: https://api.conp.com.ua/api/v1.0

  {
    "person": {
      "source": "Балабан Ігор Андрійович",
      "idName": "Балабан І. А.",
      "fullName": "Балабан Ігор Андрійович",
      "familyName": "Балабан",
      "givenName": "Ігор",
      "additionalName": "Андрійович",
      "sex": "чоловік",
      "jobTitle": "Арбітражний керуючий"
    },
    "certificateNumber": "АВ566963",
    "certificateDate": "2011-10-10T00:00:00.000Z",
    "certificateStatus": "Не діє",
    "temporary": "103",
    "updatedAt": "2018-08-07T08:45:38.314Z"
  }

-----


Пошук арбітражних керуючих
--------------------------

POST-запит за адресою ``https://api.conp.com.ua/api/v1.0/arbitrage/search`` дозволяє шукати арбітражних керуючих.

POST-запит має містити JSON з наступними змінними

:query:
    рядок
    
    Перелік термінів для повнотекстового пошуку.

:defaultOperator:
    рядок
    
    Приймає значення ``or`` або ``and``, щоб шукати будь-який з термінів для повнотекстового пошуку або усі терміни.

:filter:
    об'єкт
    
    Об'єкт, який містить перелік усіх пошукових фільтрів, встановлених користувачем.

:sort:
    об'єкт
    
    Об'єкт, який визначає порядок сортування результатів.

:from:
    ціле число (integer)
    
    Кількість об'єктів, яку необхідно пропустити (використовується для пагінації).

:aggregation:
    булеве значення
    
    Якщо встановлено значення ``false``, то в результаті буде отримано перелік арбітражних керуючих, які відповідають повнотекстовому запиту та фільтрам. Якщо встановлено значення ``true``, то повертає перелік агрегацій для фасетного пошуку.

Фільтри
~~~~~~~

Кожен з фільтрів має бути об'єктом з певною назвою (поле, за яким відбувається фільтрація) та будуватися за схемою:

:list:
    масив рядків
    
    Перелік точних значень термінів для фільтрації результату.

:operator:
    рядок
    
    Приймає значення ``or`` або ``and``, щоб у результат попадали сутності з будь-яким зі значень фільтру або усі значення фільтру.

Арбітражних керуючих можна фільтрувати за точними значеннями таких змінних:

* **certificateNumber** - Номер свідоцтва арбітражного керуючого
* **certificateStatus** - Статус свідоцтва арбітражного керуючого
* **sex** - Стать арбітражного керуючого

Приклад використання фільтру - "(1) Діючі арбітражні керуючі, (2) що є чоловіками":

.. sourcecode:: http

  ...
  {"filter": {
    "sex": {
      "list": [
        "чоловік"
      ],
      "operator": "or"
    },
    "certificateStatus": {
      "list": [
        "Діє"
      ],
      "operator": "or"
    }
  }
  ...

Сортування
~~~~~~~~~~

Для арбітражних керуючих дозволено сортування за повним іменем (`person.fullName.sort`) та датою видачі свідоцтва (``certificateDate``). Якщо змінна ``sort`` у запиті має значення ``{}``, то сортування відбуватиметься за релевантністю.

Приклад сортування за датою видачі свідоцтва:

.. sourcecode:: http
  
  ...
  "sort": {
    "certificateDate": { "order": "desc" }
  }
  ...

Агрегація
~~~~~~~~~

Для арбітражних керуючих передбачено агрегацію за такими змінними:

* Поточний статус арбітражного керуючого
* Стать арбітражного керуючого

Агрегації розраховуються автоматично для усіх змінних, для яких встановлено фільтр. Якщо необхідно отримати агрегацію без фільтрації, то необхідно задати "пустий" фільтр таким чином:

.. sourcecode:: http

  ...
  "filter": {
    "sex": {
      "list": [],
      "operator": "or"
    }
  }
  ...


Приклад повного запиту та відповіді
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sourcecode:: http

  POST /arbitrage/search HTTP/1.0
  Host: https://api.conp.com.ua/api/v1.0

  {
    "query": "",
    "defaultOperator": "or",
    "filter": {
      "fullName": {
        "list": [],
        "operator": "or"
      },
      "sex": {
        "list": [
          "чоловік"
        ],
        "operator": "or"
      },
      "certificateNumber": {
        "list": [],
        "operator": "or"
      },
      "certificateStatus": {
        "list": [],
        "operator": "or"
      },
      "certificateDate": {
        "list": [],
        "operator": "or"
      }
    },
    "searchIndex": "arbitrage",
    "aggregation": true
  }

  {
    "aggs": {
      "certificateStatus": [
        {
          "key": "Діє",
          "doc_count": 1483
        },
        {
          "key": "Не діє",
          "doc_count": 840
        }
      ],
      "compound": {},
      "sex": []
    },
    "total": 2323
  }