# Перелік методів API по роботі з порталом EDIN ID

<p class="callout info">Всі запити нижче перерахованих API методів порталу EDIN ID направляються на адресу: [https://id.edin.ua](https://id.edin.ua/)</p>

<p class="callout warning">Для підписання хеш(ів) та/або файлу пароль передається в [зашифрованому вигляді](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/sifruvannia-parolia-za-dopomogoiu-vidkritogo-kliuca-rsa "Шифрування пароля за допомогою відкритого ключа RSA").  
</p>

##### **Авторизація** 

Кожен запит має містити HTTP header:

<div class="c_tableWrapper__a48" id="bkmrk-header-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B8%D0%B9-"><table><thead><tr><th>Header</th><th>Обовʼязковий</th><th>Опис</th></tr></thead><tbody><tr><td>`x-system-id`</td><td>так</td><td>Токен/ідентифікатор зовнішньої системи. Саме цей header використовується для авторизації.</td></tr></tbody></table>

</div>Приклад:

```
curl -X GET 'https://host/api/external/company?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898'
```

##### **Отримання публічного ключа для шифрування паролів** 

Усі секретні значення, які передаються в API, мають бути зашифровані на актуальний публічний RSA-ключ сервера.

Це стосується таких полів:

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A9%D0%BE-%D0%BF%D0%B5%D1%80%D0%B5%D0%B4%D0%B0%D0%B2%D0%B0%D1%82%D0%B8-%D0%9C"><table style="width: 99.6429%;"><thead><tr><th style="width: 33.8731%;">Поле</th><th style="width: 66.0939%;">Що передавати</th></tr></thead><tbody><tr><td style="width: 33.8731%;">[Метод 9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft): `info.caPassPhrase`</td><td style="width: 66.0939%;">`base64(RSA-encrypt(publicKey, caPassPhraseBytes))`</td></tr><tr><td style="width: 33.8731%;">[Метод 9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft): `info.pkPassword`</td><td style="width: 66.0939%;">`base64(RSA-encrypt(publicKey, pkPasswordBytes))`</td></tr><tr><td style="width: 33.8731%;">[Метод 11](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-spivrobitnika-post-apiexternalcompanyemployeestatus): `adminKeyPassword`</td><td style="width: 66.0939%;">`base64(RSA-encrypt(publicKey, adminKeyPasswordBytes))`</td></tr></tbody></table>

</div>[API очікує саме **base64 від зашифрованих bytes**, а не plaintext пароль.](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/sifruvannia-parolia-za-dopomogoiu-vidkritogo-kliuca-rsa "Шифрування пароля за допомогою відкритого ключа RSA")


##### **Інтеграція підписання в облікову систему**

<table id="bkmrk-%D0%A1%D1%82%D0%B2%D0%BE%D1%80%D0%B8%D1%82%D0%B8-%D1%81%D0%B5%D1%80%D1%82%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%82-" style="width: 97.1429%;"><colgroup><col style="width: 5.88813%;"></col><col style="width: 47.1087%;"></col><col style="width: 46.9786%;"></col></colgroup><tbody><tr><td style="background-color: rgb(236,240,241);">1</td><td style="background-color: rgb(236,240,241);">Отримати і зберегти публічний ключ</td><td style="background-color: rgb(236,240,241);">[GET /api/external/key](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-i-zberegti-publicnii-kliuc-get-apiexternalkey)</td></tr><tr><td>2</td><td>Підписати хеш ключем співробітника компанії</td><td>[POST /api/external/company/sign](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/pidpisati-kliucem-spivrobitnika-kompaniyi-post-apiexternalcompanysign "Підписати хеш ключем співробітника компанії POST /api/external/company/sign")</td></tr><tr><td style="background-color: rgb(236,240,241);">3</td><td style="background-color: rgb(236,240,241);">Підписати файл ключем співробітника компанії</td><td style="background-color: rgb(236,240,241);">[POST /api/external/company/sign/file](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/pidpisati-fail-kliucem-spivrobitnika-kompaniyi-post-apiexternalcompanysignfile "Підписати файл ключем співробітника компанії POST /api/external/company/sign/file")</td></tr><tr><td>4</td><td>Верифікувати підпис на файлі</td><td>[POST <span class="token operator">/</span>api<span class="token operator">/</span>external<span class="token operator">/</span>company<span class="token operator">/</span>sign<span class="token operator">/</span>file<span class="token operator">/</span>verify](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/verifikuvati-pidpis-na-faili-post-apiexternalcompanysignfileverify)</td></tr><tr><td style="background-color: rgb(236,240,241);">5</td><td style="background-color: rgb(236,240,241);">Отримати інформацію про сертифікат</td><td style="background-color: rgb(236,240,241);">[GET <span class="token operator">/</span>api<span class="token operator">/</span>external<span class="token operator">/</span>company<span class="token operator">/</span>key<span class="token operator">/</span>certificate](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-sertifikat-get-apiexternalcompanykeycertificate)</td></tr></tbody></table>

<p class="callout info">[Колекція Postman](https://wiki-v2.edin.ua/attachments/94)</p>

##### **Інтеграція управління ключами в облікову систему**

<table id="bkmrk-1-%D0%9E%D1%82%D1%80%D0%B8%D0%BC%D0%B0%D1%82%D0%B8-%D1%96%D0%BD%D1%84%D0%BE%D1%80%D0%BC%D0%B0%D1%86%D1%96" style="width: 97.1429%; height: 500px;"><colgroup><col style="width: 5.39745%;"></col><col style="width: 45.1417%;"></col><col style="width: 49.4363%;"></col></colgroup><tbody><tr style="height: 35.2px;"><td style="background-color: rgb(236,240,241); height: 35.2px;">1</td><td style="background-color: rgb(236,240,241); height: 35.2px;">Отримати інформацію про компанію</td><td style="background-color: rgb(236,240,241); height: 35.2px;">[GET /api/external/company](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-kompaniiu-get-apiexternalcompany)</td></tr><tr style="height: 35.2px;"><td style="height: 35.2px;">2</td><td style="height: 35.2px;">Отримати інформацію про співробітника</td><td style="height: 35.2px;">[GET /api/external/company/employee](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-spivrobitnika-get-apiexternalcompanyemployee "Підписати хеш ключем співробітника компанії POST /api/external/company/sign")</td></tr><tr style="height: 35.2px;"><td style="background-color: rgb(236,240,241); height: 35.2px;">3</td><td style="background-color: rgb(236,240,241); height: 35.2px;">Пошук ключів співробітника</td><td style="background-color: rgb(236,240,241); height: 35.2px;">[POST /api/external/company/employee/pkeys/search](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/posuk-kliuciv-spivrobitnika-post-apiexternalcompanyemployeepkeyssearch "Підписати файл ключем співробітника компанії POST /api/external/company/sign/file")</td></tr><tr style="height: 35.2px;"><td style="height: 35.2px;">4</td><td style="height: 35.2px;">Пошук співробітників компанії</td><td style="height: 35.2px;">[POST /api/external/company/employees/search](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/posuk-spivrobitnikiv-kompaniyi-post-apiexternalcompanyemployeessearch)</td></tr><tr style="height: 35.2px;"><td style="background-color: rgb(236,240,241); height: 35.2px;">5</td><td style="background-color: rgb(236,240,241); height: 35.2px;">Пошук ключів компанії</td><td style="background-color: rgb(236,240,241); height: 35.2px;">[POST /api/external/company/pkeys/search](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/posuk-kliuciv-kompaniyi-post-apiexternalcompanypkeyssearch)</td></tr><tr style="height: 35.2px;"><td style="height: 35.2px;">6</td><td style="height: 35.2px;">Отримати інформацію про ключ</td><td style="height: 35.2px;">[GET /api/external/company/pkey](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-kliuc-get-apiexternalcompanypkey)</td></tr><tr style="height: 35.2px;"><td style="background-color: rgb(236,240,241); height: 35.2px;">7.1</td><td style="background-color: rgb(236,240,241); height: 35.2px;">Отримати документ компанії</td><td style="background-color: rgb(236,240,241); height: 35.2px;">[GET /api/external/company/form](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimannia-dokumenta-kompaniyi-get-apiexternalcompanyform)</td></tr><tr style="height: 35.2px;"><td style="height: 35.2px;">7.2</td><td style="height: 35.2px;">Отримати ідентифікацію співробітника</td><td style="height: 35.2px;">[GET /api/external/company/employee/identification](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-identifikaciiu-spivrobitnika-get-apiexternalcompanyemployeeidentification)</td></tr><tr style="height: 35.2px;"><td style="background-color: rgb(236,240,241); height: 35.2px;">7.3</td><td style="background-color: rgb(236,240,241); height: 35.2px;">Отримати документ ключа</td><td style="background-color: rgb(236,240,241); height: 35.2px;">[GET /api/external/company/pkey/form](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-dokument-kliuca-get-apiexternalcompanypkeyform)</td></tr><tr style="height: 35.2px;"><td style="height: 35.2px;">8</td><td style="height: 35.2px;">Додати співробітника</td><td style="height: 35.2px;">[POST /api/external/company/employee](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/dodati-spivrobitnika-post-apiexternalcompanyemployee)</td></tr><tr style="height: 29.6px;"><td style="background-color: rgb(236,240,241); height: 29.6px;">9.1</td><td style="background-color: rgb(236,240,241); height: 29.6px;">Створити чернетку ключа</td><td style="background-color: rgb(236,240,241); height: 29.6px;">[POST /api/external/company/employee/pkey/generate/draft](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft)</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">9.2</td><td style="height: 29.6px;">Згенерувати PDF-форму для адміністратора компанії</td><td style="height: 29.6px;">[PATCH /api/external/company/employee/pkey/generate/draft](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft)</td></tr><tr style="height: 29.6px;"><td style="background-color: rgb(236,240,241); height: 29.6px;">9.3</td><td style="background-color: rgb(236,240,241); height: 29.6px;">Передати підписи PDF і активувати ключ

</td><td style="background-color: rgb(236,240,241); height: 29.6px;">[POST /api/external/company/employee/pkey/activation](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/peredati-pidpisi-pdf-i-aktivuvati-kliuc-post-apiexternalcompanyemployeepkeyactivation)</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">10</td><td style="height: 29.6px;">Змінити статус ключа

</td><td style="height: 29.6px;">[POST /api/external/company/pkey/status](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-kliuca-post-apiexternalcompanypkeystatus)</td></tr><tr style="height: 29.6px;"><td style="background-color: rgb(236,240,241); height: 29.6px;">11</td><td style="background-color: rgb(236,240,241); height: 29.6px;">Змінити статус співробітника

</td><td style="background-color: rgb(236,240,241); height: 29.6px;">[POST /api/external/company/employee/status](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-spivrobitnika-post-apiexternalcompanyemployeestatus)</td></tr><tr><td>12</td><td>Створити компанію

</td><td>[POST /api/external/company/create](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvorennia-kompaniyi-post-apiexternalcompanycreate)

</td></tr></tbody></table>

**Створення ключа складається з трьох запитів:**

1. [Створити чернетку ключа та отримати PDF для підпису співробітником](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft).
2. [Згенерувати PDF для підпису адміністратором компанії](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft).
3. [Передати detached-підписи всіх PDF і активувати ключ або передати його на активацію КНЕДП](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/peredati-pidpisi-pdf-i-aktivuvati-kliuc-post-apiexternalcompanyemployeepkeyactivation).

**Рекомендований сценарій створення та активації ключа:**

1. Перевірити компанію методом [1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-kompaniiu-get-apiexternalcompany).
2. Якщо співробітника ще немає – створити його методом [8](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/dodati-spivrobitnika-post-apiexternalcompanyemployee).
3. Перевірити співробітника методом [2](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-spivrobitnika-get-apiexternalcompanyemployee).
4. Викликати метод [9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft) і отримати `pKey.uuid` та employee PDF-форми.
5. Співробітник підписує PDF-форми з відповіді [9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft) detached-підписом.
6. Викликати метод [9.2](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft) з `pKeyUuid` та `adminIpn` і отримати admin PDF-форми.
7. Адміністратор/суперадміністратор підписує PDF-форми з відповіді [9.2](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft) detached-підписом.
8. Викликати метод [9.3](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/peredati-pidpisi-pdf-i-aktivuvati-kliuc-post-apiexternalcompanyemployeepkeyactivation), передавши `keyUuid`, `activate` і map підписів за всіма отриманими `formType`.
9. Отримати оновлений `ESSPrivateKey` зі статусом `ACTIVATED` або `COMPANY_ADMIN_APPROVED`.