# Методи API

# Отримати і зберегти публічний ключ GET /api/external/key

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%C2%A0-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-g"><table class="colwidths-given docutils align-default" style="width: 98.0952%;"><tbody><tr class="row-odd"><td style="width: 21.6284%;">**URL**

</td><td style="width: 78.3726%;"> </td></tr><tr class="row-even"><td style="width: 21.6284%;">Метод запиту

</td><td style="width: 78.3726%;">GET

</td></tr><tr class="row-odd"><td style="width: 21.6284%;">URL запиту

</td><td style="width: 78.3726%;">**/api/external/key**

</td></tr><tr><td style="width: 21.6284%;">**Authorization**

</td><td style="width: 78.3726%;">  
</td></tr><tr><td style="width: 21.6284%;">Auth type

</td><td style="width: 78.3726%;">API key</td></tr><tr><td style="width: 21.6284%;">Key / Value

</td><td style="width: 78.3726%;">**x-system-id** / токен, отриманий при підключенні</td></tr><tr><td style="width: 21.6284%;">**Params**

</td><td style="width: 78.3726%;"></td></tr><tr><td style="width: 21.6284%;">type

</td><td style="width: 78.3726%;">тип відповіді JSON|PEM|XML (якщо параметр не передавати за замовченням буде JSON)

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

</div>##### **RESPONSE**

В тілі **відповіді** повертається ключ у вказаному форматі:

- якщо type = JSON – повертається масив байт
- якщо type = PEM – повертається PEM-файл у вигляді ```json
    -----BEGIN PUBLIC KEY-----
    MIGfMA0GCSqGSIb3DQEBAQ9QIDAQAB
    -----END PUBLIC KEY-----
    ```
- якщо type = XML – повертається XML-файл у вигляді ```markdown
    <?xml version="1.0"?>
    <RSAKeyValue>
      <Modulus>wxWy8iReusbmiadsULVLSD36+l5k6cZ0=</Modulus>
      <Exponent>AQAB</Exponent>
    </RSAKeyValue>
    
    ```

**Для type in (PEM, XML) в reponse-header** передається параметр `x-key-ttl`, в якому передається термін життя відкритого ключа.

# Підписати ключем співробітника компанії POST /api/external/company/sign

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%C2%A0-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-g"><table class="colwidths-given docutils align-default" style="width: 98.0952%;"><tbody><tr class="row-odd"><td style="width: 21.6213%;">**URL**

</td><td style="width: 78.3469%;"> </td></tr><tr class="row-even"><td style="width: 21.6213%;">Метод запиту

</td><td style="width: 78.3469%;">POST

</td></tr><tr class="row-odd"><td style="width: 21.6213%;">URL запиту

</td><td style="width: 78.3469%;">**/api/external/company/sign**

</td></tr><tr class="row-odd"><td style="width: 21.6213%;">**Headers**

</td><td style="width: 78.3469%;"> </td></tr><tr class="row-even"><td style="width: 21.6213%;">Authorization

</td><td style="width: 78.3469%;">**x-system-id** - токен, отриманий при підключенні

</td></tr><tr class="row-odd"><td style="width: 21.6213%;">Content-Type

</td><td style="width: 78.3469%;">aplication/json

</td></tr><tr><td style="width: 21.6213%;">**Request body**

</td><td style="width: 78.3469%;"><div><div>{</div><div> "key": "{{id ключа}}",</div><div> "password": "{{зашифрований пароль від ключа}}",</div><div> "algorithm": "DSTU4145_GOST34311",</div><div> "hashes": [</div><div> {"hash": "{{хеш документа, що підписується}}", "description": "опис документа, що підписується"}</div><div> ]</div><div> "SignType": "{{CADES_BES (за замовчуванням)<span class="token punctuation">,</span> CADES_T<span class="token punctuation">,</span> CADES_C<span class="token punctuation">,</span> CADES_X_LONG<span class="token punctuation">,</span> CADES_X_LONG_TRUSTED<span class="token punctuation">;</span>}}",</div><div>}</div></div></td></tr></tbody></table>

</div>##### **RESPONSE**

В тілі **відповіді** повертається масив підписів.

# Підписати файл ключем співробітника компанії POST /api/external/company/sign/file

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%C2%A0-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-g"><table class="colwidths-given docutils align-default" style="width: 98.0952%;"><tbody><tr class="row-odd"><td style="width: 21.6285%;">**URL**

</td><td style="width: 78.3397%;"> </td></tr><tr class="row-even"><td style="width: 21.6285%;">Метод запиту

</td><td style="width: 78.3397%;">POST

</td></tr><tr class="row-odd"><td style="width: 21.6285%;">URL запиту

</td><td style="width: 78.3397%;">**/api/external/company/sign/file**

</td></tr><tr><td style="width: 21.6285%;">**Authorization**

</td><td style="width: 78.3397%;">  
</td></tr><tr><td style="width: 21.6285%;">Auth type

</td><td style="width: 78.3397%;">API key</td></tr><tr><td style="width: 21.6285%;">Key / Value

</td><td style="width: 78.3397%;">**x-system-id** / токен, отриманий при підключенні</td></tr><tr class="row-odd"><td style="width: 21.6285%;">**Headers**

</td><td style="width: 78.3397%;"> </td></tr><tr class="row-odd"><td style="width: 21.6285%;">Content-Type

</td><td style="width: 78.3397%;">[multipart/form-data](https://tools.ietf.org/html/rfc7578)

</td></tr><tr><td style="width: 21.6285%;">**Request body**

</td><td style="width: 78.3397%;">Параметри тіла запиту:

- **password** – [зашифрований пароль.](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/sifruvannia-parolia-za-dopomogoiu-vidkritogo-kliuca-rsa "Шифрування пароля за допомогою відкритого ключа RSA")
- **file.pdf** – дані (контент) для підпису у вигляді файлу або base64 (залежно від **inputFormat**)

</td></tr><tr><td style="width: 21.6285%;">**Params**

</td><td style="width: 78.3397%;">- **key** – ідентифікатор ключа.
- **type –** тип підписання, може приймати значення: 
    - append – додає підпис до переданого файлу. **ВАЖЛИВО!** Якщо файл вже був підписаний, то підпис додається до існуючого, а не підписується разом з існуючим підписом.
    - sign - підписує контент, використовується за замовчуванням.
- **result –** формат підписання (дані й підпис в одному файлі, дані й підпис в окремих файлах), може приймати значення: 
    - enveloped – у відповідь надійде файл з підписом
    - detached – у відповідь надійде тільки підпис
- **inputFormat** – формат вхідних даних для підписання, може приймати значення: 
    - file – файл в бінарному вигляді
    - base64 – файл у вигляді base64 рядка
- **outputFormat** – формат вихідних (результуючих) даних після підписання, може приймати значення: 
    - file – файл в бінарному вигляді
    - base64 – файл у вигляді base64 рядка
- **signType** – тип підпису, приймає значення CADES\_BES<span class="token punctuation">,</span> CADES\_T<span class="token punctuation">,</span> CADES\_C<span class="token punctuation">,</span> CADES\_X\_LONG<span class="token punctuation">,</span> CADES\_X\_LONG\_TRUSTED. Якщо не передано, то за замовченням підставляється CADES\_BES
- **algorithm** (enum) - алгоритм формату підписання: 
    - DSTU4145\_GOST34311<span class="token punctuation">,</span>
    - DSTU4145\_DSTU7564<span class="token punctuation">,</span>
    - ECDSA

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

</div>##### **RESPONSE**

В тілі **відповіді** повертаються код 200 та результат підписання відповідно до параметрів **result** та **outputFormat.**

# Отримати інформацію про компанію GET /api/external/company

**REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 65.7143%;"><colgroup><col style="width: 27.5762%;"></col><col style="width: 72.3875%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>GET

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

</td></tr><tr><td style="width: 21.6285%;">**Authorization**

</td><td style="width: 78.3397%;">  
</td></tr><tr><td style="width: 21.6285%;">Auth type

</td><td style="width: 78.3397%;">API key</td></tr><tr><td style="width: 21.6285%;">Key / Value

</td><td style="width: 78.3397%;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

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

</div>**RESPONSE**

В тілі відповіді передаються статус 200 та об'єкт [ESSCompany](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscompany).

**CURL**

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

**Помилки**

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-403-a"><table style="width: 93.9286%;"><thead><tr><th style="width: 7.72311%;">HTTP</th><th style="width: 26.3158%;">`type`</th><th style="width: 65.9325%;">Опис</th></tr></thead><tbody><tr><td style="width: 7.72311%;">403</td><td style="width: 26.3158%;">`access_denied`</td><td style="width: 65.9325%;">Невалідний `x-system-id` або IP не дозволений.</td></tr><tr><td style="width: 7.72311%;">403</td><td style="width: 26.3158%;">`company_access_denied`</td><td style="width: 65.9325%;">Компанія не знайдена або не привʼязана до зовнішньої системи.</td></tr></tbody></table>

</div><div class="wy-table-responsive" id="bkmrk-"></div>

# Отримати інформацію про співробітника GET /api/external/company/employee

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 78.0952%; height: 231px;"><colgroup><col style="width: 23.3516%;"></col><col style="width: 76.6178%;"></col></colgroup><tbody><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**URL**

</td><td style="height: 29.6px;">  
</td></tr><tr class="row-even" style="height: 29.6px;"><td style="height: 29.6px;">Метод запиту

</td><td style="height: 29.6px;">GET

</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">URL запиту

</td><td style="height: 29.6px;">**/api/external/company/employee**

</td></tr><tr class="row-even" style="height: 47.8px;"><td style="height: 47.8px;">URL параметри

</td><td style="height: 47.8px;">**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**Headers**

</td><td style="height: 29.6px;"> </td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">Content-Type

</td><td style="height: 29.6px;">application/json

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

</div>##### **RESPONSE**

В тілі **відповіді** передаються статус 200 та об'єкт [ESSUser](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essuser).

##### **CURL**

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

##### **Помилки** 

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-400-e"><table style="width: 79.881%;"><thead><tr><th style="width: 7.78388%;">HTTP</th><th style="width: 26.4042%;">`type`</th><th style="width: 65.7814%;">Опис</th></tr></thead><tbody><tr><td style="width: 7.78388%;">400</td><td style="width: 26.4042%;">`employee_not_found`</td><td style="width: 65.7814%;">Співробітник з таким `employeeIpn` не знайдений у цій компанії.</td></tr><tr><td style="width: 7.78388%;">403</td><td style="width: 26.4042%;">`company_access_denied`</td><td style="width: 65.7814%;">Немає доступу до company.</td></tr></tbody></table>

</div>

# Пошук ключів співробітника POST /api/external/company/employee/pkeys/search

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 78.5714%;"><colgroup><col style="width: 25.6376%;"></col><col style="width: 74.3339%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>POST

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/employee/pkeys/search**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>JSON Body

</td><td>В тілі запиту методу передається об’єкт [ESSPrivateKeysQuery](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essprivatekeysquery)

 **JSON приклад запиту:**

```json
{
  "statuses": ["ACTIVATED"],
  "stamp": false,
  "limit": {
    "offset": 0,
    "count": 20
  }
}
```

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

</div>##### **RESPONSE**

В тілі відповіді передаються статус 200 та масив об'єктів [ESSPrivateKey](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/obekt-essprivatekey).

**JSON приклад відповіді:**

```
[
  {
    "id": 1001,
    "name": "Ключ співробітника",
    "uuid": "019ec000-0000-7000-8000-000000000001",
    "status": "ACTIVATED",
    "storeType": "HSM",
    "keyType": "UA",
    "stamp": false,
    "validFrom": 1717200000,
    "validTo": 1780272000,
    "requests": [],
    "certificates": []
  }
]
```

##### **CURL** 

```
curl -X POST 'https://host/api/external/company/employee/pkeys/search?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -H 'Content-Type: application/json' \
  -d '{
    "statuses": ["ACTIVATED"],
    "stamp": false,
    "limit": {"offset": 0, "count": 20}
  }'
```

##### **Помилки** 

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-403-a"><table style="width: 64.881%;"><thead><tr><th style="width: 12.1371%;">HTTP</th><th style="width: 41.1709%;">`type`</th><th style="width: 46.6445%;">Опис</th></tr></thead><tbody><tr><td style="width: 12.1371%;">400</td><td style="width: 41.1709%;">`employee_not_found`</td><td style="width: 46.6445%;">Співробітник не знайдений.</td></tr><tr><td style="width: 12.1371%;">403</td><td style="width: 41.1709%;">`company_access_denied`</td><td style="width: 46.6445%;">Немає доступу до company.</td></tr></tbody></table>

</div>

# Пошук співробітників компанії POST /api/external/company/employees/search

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 78.6905%; height: 296px;"><colgroup><col style="width: 25.5983%;"></col><col style="width: 74.3714%;"></col></colgroup><tbody><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**URL**

</td><td style="height: 29.6px;">  
</td></tr><tr class="row-even" style="height: 29.6px;"><td style="height: 29.6px;">Метод запиту

</td><td style="height: 29.6px;">POST

</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">URL запиту

</td><td style="height: 29.6px;">**/api/external/company/employees/search**

</td></tr><tr class="row-even" style="height: 29.6px;"><td style="height: 29.6px;">URL параметри

</td><td style="height: 29.6px;">**companyCode** (обов’язково) - код Компанії;

</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">**Authorization**

</td><td style="height: 29.6px;">  
</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">Auth type

</td><td style="height: 29.6px;">API key</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">Key / Value

</td><td style="height: 29.6px;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**Headers**

</td><td style="height: 29.6px;"> </td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">Content-Type

</td><td style="height: 29.6px;">application/json

</td></tr><tr style="height: 29.6px;"><td>**REQUEST**

</td><td> </td></tr><tr><td>JSON Body

</td><td>В тілі запиту методу передається об’єкт [ESSUsersQuery](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essusersquery)

 **JSON приклад запиту:**

```json
{
  "search": "3148615913",
  "role": ["USER", "ADMIN"],
  "identification": ["YES"],
  "employeeStatus": ["ACTIVE"],
  "limit": {
    "offset": 0,
    "count": 20
  }
}
```

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

</div>##### **RESPONSE**

В тілі відповіді передаються статус 200 та масив об'єктів [ESSUser](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essuser).

**JSON приклад відповіді:**

```json
[
  {
    "id": 456,
    "login": "380501112233",
    "email": "employee@example.com",
    "fullName": "Іваненко Іван Іванович",
    "ipn": "3148615913",
    "identified": "YES",
    "role": "USER",
    "employeeStatus": "ACTIVE",
    "employeeEmail": "employee@example.com"
  }
]
```

##### **CURL** 

```
curl -X POST 'https://host/api/external/company/employees/search?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "3148615913",
    "employeeStatus": ["ACTIVE"],
    "limit": {"offset": 0, "count": 20}
  }'
```

##### **Помилки** 

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-403-a"><table style="width: 65.5952%;"><thead><tr><th style="width: 12.1951%;">HTTP</th><th style="width: 41.3678%;">`type`</th><th style="width: 46.3893%;">Опис</th></tr></thead><tbody><tr><td style="width: 12.1951%;">403</td><td style="width: 41.3678%;">`company_access_denied`</td><td style="width: 46.3893%;">Немає доступу до company.</td></tr></tbody></table>

</div>

# Пошук ключів компанії POST /api/external/company/pkeys/search

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 78.9286%;"><colgroup><col style="width: 22.2351%;"></col><col style="width: 77.7262%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>POST

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/pkeys/search**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>JSON Body

</td><td>В тілі запиту методу передається об’єкт [ESSPrivateKeysQuery](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essprivatekeysquery)

 **JSON приклад запиту:**

```json
{
  "nameQuery": "Печатка",
  "stamp": true,
  "statuses": ["ACTIVATED"],
  "limit": {
    "offset": 0,
    "count": 20
  }
}
```

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

</div>##### **RESPONSE**

В тілі відповіді передаються статус 200 та масив об'єктів [ESSPrivateKey](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/obekt-essprivatekey).

##### **CURL** 

```
curl -X POST 'https://host/api/external/company/pkeys/search?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -H 'Content-Type: application/json' \
  -d '{
    "stamp": true,
    "statuses": ["ACTIVATED"],
    "limit": {"offset": 0, "count": 20}
  }'
```

##### **Помилки** 

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-403-a"><table style="width: 53.2143%;"><thead><tr><th style="width: 12.1951%;">HTTP</th><th style="width: 41.3678%;">`type`</th><th style="width: 46.3893%;">Опис</th></tr></thead><tbody><tr><td style="width: 12.1951%;">403</td><td style="width: 41.3678%;">`company_access_denied`</td><td style="width: 46.3893%;">Немає доступу до company.</td></tr></tbody></table>

</div>

# Отримати інформацію про ключ GET /api/external/company/pkey

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 78.9286%;"><colgroup><col style="width: 22.2351%;"></col><col style="width: 77.7262%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>GET

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/pkey**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

**key** (обов’язково) - код ключа.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

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

</div>##### **RESPONSE**

В тілі відповіді передаються статус 200 та об'єкт [ESSPrivateKey](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/obekt-essprivatekey).

##### **CURL**

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

#####  

##### **Помилки** 

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-403-a"><table style="width: 79.2857%;"><thead><tr><th style="width: 12.2237%;">HTTP</th><th style="width: 33.6571%;">`type`</th><th style="width: 54.0857%;">Опис</th></tr></thead><tbody><tr><td style="width: 12.2237%;">400</td><td style="width: 33.6571%;">`pkey_not_found`</td><td style="width: 54.0857%;">Ключ не знайдений або не належить цій company.</td></tr><tr><td style="width: 12.2237%;">403</td><td style="width: 33.6571%;">`company_access_denied`</td><td style="width: 54.0857%;">Немає доступу до company.</td></tr></tbody></table>

</div>

# Отримання документа компанії GET /api/external/company/form

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 97.2619%;"><colgroup><col style="width: 22.2824%;"></col><col style="width: 77.6874%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>GET

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/form**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

**formType** (обов’язково) - Enum name з `ESSRegFormType`, наприклад, `OFFER_AGREEMENT_MANAGER`.

**format** (опційно) - `binary` або `base64`. Default: `binary`.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

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

</div>##### **RESPONSE**

В тілі **відповіді** передається:

- статус 200, якщо `format=binary`

PDF bytes з content type:

```
Content-Type: application/pdf
```

- статус 200, якщо `format=base64`

```
{
  "formType": "OFFER_AGREEMENT_MANAGER",
  "fileName": "Договір-оферта (керівник/УО).pdf",
  "contentType": "application/pdf",
  "contentBase64": "JVBERi0x..."
}
```

<table id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81-formty" style="width: 67.7381%;"><thead><tr><th style="width: 32.7154%;">Поле</th><th style="width: 14.7219%;">Тип</th><th style="width: 52.5264%;">Опис</th></tr></thead><tbody><tr><td style="width: 32.7154%;">`formType`</td><td style="width: 14.7219%;">string</td><td style="width: 52.5264%;">Enum name документа.</td></tr><tr><td style="width: 32.7154%;">`fileName`</td><td style="width: 14.7219%;">string</td><td style="width: 52.5264%;">Імʼя файлу.</td></tr><tr><td style="width: 32.7154%;">`contentType`</td><td style="width: 14.7219%;">string</td><td style="width: 52.5264%;">Завжди `application/pdf`.</td></tr><tr><td style="width: 32.7154%;">`contentBase64`</td><td style="width: 14.7219%;">string</td><td style="width: 52.5264%;">PDF у base64.</td></tr></tbody></table>

##### **CURL binary**

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

##### **CURL base 64**

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

##### **Помилки**

<table id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-400-u" style="width: 69.4048%;"><thead><tr><th style="width: 12.1951%;">HTTP</th><th style="width: 41.2229%;">`type`</th><th style="width: 46.7193%;">Опис</th></tr></thead><tbody><tr><td style="width: 12.1951%;">400</td><td style="width: 41.2229%;">`unknown_form_type`</td><td style="width: 46.7193%;">Невідомий `formType`.</td></tr><tr><td style="width: 12.1951%;">400</td><td style="width: 41.2229%;">`form_not_found`</td><td style="width: 46.7193%;">Документ не знайдений.</td></tr><tr><td style="width: 12.1951%;">400</td><td style="width: 41.2229%;">`unknown_format`</td><td style="width: 46.7193%;">`format` не `binary` і не `base64`.</td></tr><tr><td style="width: 12.1951%;">403</td><td style="width: 41.2229%;">`company_access_denied`</td><td style="width: 46.7193%;">Немає доступу до company.</td></tr></tbody></table>

# Отримати ідентифікацію співробітника GET /api/external/company/employee/identification

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-pos"><table class="colwidths-given docutils align-default" style="width: 78.5714%;"><colgroup><col style="width: 22.2351%;"></col><col style="width: 77.7262%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>GET

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/employee/identification**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

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

</div>##### **RESPONSE**

У тілі відповіді передаються статус 200 та об'єкт з даними співробітника.

**Опис параметрів відповіді:**

<table id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81-info-o"><thead><tr><th>Поле</th><th>Тип</th><th>Опис</th></tr></thead><tbody><tr><td>`info`</td><td>object</td><td>Об'єкт [ESSUserIdentification.](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essuseridentification)</td></tr><tr><td>`data`</td><td>string</td><td>Base64 підпису ідентифікації. Повертається лише якщо `info.complete == YES`.</td></tr></tbody></table>

Якщо ідентифікація не завершена, поле `data` не повертається.

**JSON приклад відповіді:**

```json
{
  "info": {
    "type": "SIGN",
    "complete": "YES",
    "fullName": "Іваненко Іван Іванович",
    "fullNameEN": "IVANENKO IVAN",
    "ipn": "3148615913",
    "unzr": "19900101-12345",
    "state": "Київська",
    "city": "Київ",
    "address": "вул. Тестова, 1",
    "publicKey": "01 02 03 ...",
    "validTo": 1780272000,
    "sign": null
  },
  "data": "base64 identification sign container"
}
```

##### **CURL**

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

##### **Помилки** 

<div class="c_tableWrapper__a48" id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-403-a"><table><thead><tr><th>HTTP</th><th>`type`</th><th>Опис</th></tr></thead><tbody><tr><td>400</td><td>`employee_not_found`</td><td>Співробітник не знайдений.</td></tr><tr><td>400</td><td>`employee_identification_not_found`</td><td>Ідентифікація співробітника не знайдена.</td></tr><tr><td>400</td><td>`employee_identification_sign_not_found`</td><td>Ідентифікація завершена, але файл підпису не знайдено.</td></tr><tr><td>403</td><td>`company_access_denied`</td><td>Немає доступу до company.</td></tr></tbody></table>

</div><div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"></div>

# Отримати документ ключа GET /api/external/company/pkey/form

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 81.9048%;"><tbody><tr class="row-odd"><td style="width: 22.2159%;">**URL**

</td><td style="width: 77.7556%;">  
</td></tr><tr class="row-even"><td style="width: 22.2159%;">Метод запиту

</td><td style="width: 77.7556%;">GET

</td></tr><tr class="row-odd"><td style="width: 22.2159%;">URL запиту

</td><td style="width: 77.7556%;">**/api/external/company/pkey/form**

</td></tr><tr class="row-even"><td style="width: 22.2159%;">URL параметри

</td><td style="width: 77.7556%;">**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника.

**key** (обов’язково) - UUID ключа.

**formType** (обов’язково) - Enum name з `ESSRegFormType`, наприклад, `PK_FORM`.

**format** (опційно) - `binary` або `base64`. Default: `binary`.

</td></tr><tr><td style="width: 22.2159%;">**Authorization**

</td><td style="width: 77.7556%;">  
</td></tr><tr><td style="width: 22.2159%;">Auth type

</td><td style="width: 77.7556%;">API key</td></tr><tr><td style="width: 22.2159%;">Key / Value

</td><td style="width: 77.7556%;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td style="width: 22.2159%;">**Headers**

</td><td style="width: 77.7556%;"> </td></tr><tr class="row-odd"><td style="width: 22.2159%;">Content-Type

</td><td style="width: 77.7556%;">application/json

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

</div>##### **RESPONSE**

Такий самий, як у методі [Отримання документа компанії](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimannia-dokumenta-kompaniyi-get-apiexternalcompanyform):

- `format=binary` — PDF bytes, `Content-Type: application/pdf`;
- `format=base64` — file object з `formType`, `fileName`, `contentType`, `contentBase64`.

##### **CURL** 

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

##### **Помилки** 

<table id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-400-u" style="width: 65%;"><thead><tr><th style="width: 11.3788%;">HTTP</th><th style="width: 38.5988%;">`type`</th><th style="width: 49.9777%;">Опис</th></tr></thead><tbody><tr><td style="width: 11.3788%;">400</td><td style="width: 38.5988%;">`unknown_form_type`</td><td style="width: 49.9777%;">Невідомий `formType`.</td></tr><tr><td style="width: 11.3788%;">400</td><td style="width: 38.5988%;">`form_not_found`</td><td style="width: 49.9777%;">Документ ключа не знайдений.</td></tr><tr><td style="width: 11.3788%;">400</td><td style="width: 38.5988%;">`unknown_format`</td><td style="width: 49.9777%;">`format` не `binary` і не `base64`.</td></tr><tr><td style="width: 11.3788%;">403</td><td style="width: 38.5988%;">`company_access_denied`</td><td style="width: 49.9777%;">Немає доступу до company.</td></tr></tbody></table>

# Додати співробітника POST /api/external/company/employee

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 97.619%;"><colgroup><col style="width: 25.7383%;"></col><col style="width: 74.3701%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>POST

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/form**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>multipart/form-data

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>REQUEST Body

</td><td>**info** (обов’язково) JSON attr - дані для додавання співробітника;

**identification** (обов’язково) file - підписаний контейнер ідентифікації співробітника.

Всі персональні дані ідентифікації беруться з підпису/сертифіката у file `identification`, а не з JSON `info`.

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

</div>`info`:

```json
{
  "phone": "380501112233",
  "email": "employee@example.com",
  "role": "USER",
  "identificationType": "SIGN"
}
```

**Опис полів:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5-2"><table><thead><tr><th>Поле</th><th>Тип</th><th>Обовʼязкове</th><th>Опис</th></tr></thead><tbody><tr><td>`phone`</td><td>string</td><td>так</td><td>Телефон у форматі `380XXXXXXXXX`.</td></tr><tr><td>`email`</td><td>string</td><td>так</td><td>Email співробітника.</td></tr><tr><td>`role`</td><td>enum</td><td>так</td><td>`USER`, `ADMIN`.</td></tr><tr><td>`identificationType`</td><td>enum</td><td>так</td><td>`SIGN`, `DIIA_INTERNAL_PASSPORT` або `DIIA_FOREIGN_PASSPORT`.</td></tr></tbody></table>

</div><div class="wy-table-responsive" id="bkmrk-"></div>##### **RESPONSE**

У тілі **відповіді** передається об'єкт [ESSUser](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essuser) з даними доданого або вже існуючого співробітника.

##### **CURL**

```
curl -X POST 'https://host/api/external/company/employee?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -F 'info={
    "phone":"380501112233",
    "email":"employee@example.com",
    "role":"USER",
    "identificationType":"SIGN"
  }' \
  -F 'identification=@employee-identification.p7s;type=application/octet-stream'
```

##### **Помилки** 

<table id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-400-i"><thead><tr><th>HTTP</th><th>`type`</th><th>Опис</th></tr></thead><tbody><tr><td>400</td><td>`invalid_info`</td><td>Невалідний або неповний `info`.</td></tr><tr><td>400</td><td>`invalid_phone`</td><td>`phone` не відповідає формату `380XXXXXXXXX`.</td></tr><tr><td>400</td><td>`identification_file_not_found`</td><td>Не переданий file `identification`.</td></tr><tr><td>400</td><td>`invalid_signature`</td><td>Неможливо перевірити підпис ідентифікації.</td></tr><tr><td>400</td><td>`unsupported_role`</td><td>Непідтримувана роль.</td></tr><tr><td>400</td><td>`unsupported_identification_type`</td><td>Непідтримуваний тип ідентифікації.</td></tr><tr><td>400</td><td>`wrong_ipn`</td><td>ІПН існуючого користувача не збігається з ІПН у підписі.</td></tr><tr><td>403</td><td>`company_access_denied`</td><td>Немає доступу до company.</td></tr><tr><td>403</td><td>`company_wrong_status`</td><td>Компанія не `ACTIVE`.</td></tr></tbody></table>

# Створити чернетку ключа для співробітника POST /api/external/company/employee/pkey/generate/draft

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 97.7381%; height: 395.9px;"><colgroup><col style="width: 15.6059%;"></col><col style="width: 84.3697%;"></col></colgroup><tbody><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**URL**

</td><td style="height: 29.6px;">  
</td></tr><tr class="row-even" style="height: 29.6px;"><td style="height: 29.6px;">Метод запиту

</td><td style="height: 29.6px;">POST

</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">URL запиту

</td><td style="height: 29.6px;">**/api/external/company/employee/pkey/generate/draft**

</td></tr><tr class="row-even" style="height: 159.1px;"><td style="height: 159.1px;">URL параметри

</td><td style="height: 159.1px;">**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника;

**store** (обов’язково) - може приймати одне зі значень:

- `cloud` - сервер генерує ключ і p10-запити у форматі `PKCS #10`. Потрібен [`info.pkPassword`](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/perelik-metodiv-api-po-roboti-z-portalom-edin-id#bkmrk-1.4.-%D0%9E%D1%82%D1%80%D0%B8%D0%BC%D0%B0%D0%BD%D0%BD%D1%8F-%D0%BF%D1%83%D0%B1%D0%BB%D1%96).
- `file` - зовнішня система генерує ключ, а сервер приймає p10-запити у форматі `PKCS #10` в part `requests`

</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">**Authorization**

</td><td style="height: 29.6px;">  
</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">Auth type

</td><td style="height: 29.6px;">API key</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">Key / Value

</td><td style="height: 29.6px;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**Headers**

</td><td style="height: 29.6px;"> </td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">Content-Type

</td><td style="height: 29.6px;">multipart/form-data

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>REQUEST Body

</td><td>**info** (обов’язково) JSON attr - параметри CA user і ключа;

**requests** (обов’язково, тільки для `store=file`) JSON attr - p10-запити у форматі `PKCS #10`, створені зовнішньою системою.

Всі персональні дані ідентифікації беруться з підпису/сертифіката у file `identification`, а не з JSON `info`.

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

</div>`info`:

```json
{
  "pkName": "Ключ Іваненко",
  "pkType": "UA",
  "pkStoreType": "HSM",
  "pkPassword": "base64 RSA-encrypted password",
  "pkIsStamp": false,
  "emplTitle": "Менеджер",
  "emplOrgUnit": "Відділ продажів",
  "caPassPhrase": "base64 RSA-encrypted pass phrase",
  "certType": "SIGN_AND_ENCRYPT",
  "certValidity": "TWO"
}
```

**Опис полів** `info`:

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5-3"><table style="width: 100%; height: 371.325px;"><thead><tr style="height: 29.6px;"><th style="width: 14.2982%; height: 29.6px;">Поле</th><th style="width: 10.4873%; height: 29.6px;">Тип</th><th style="width: 16.2059%; height: 29.6px;">Обовʼязкове</th><th style="width: 58.9847%; height: 29.6px;">Опис</th></tr></thead><tbody><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`pkName`</td><td style="width: 10.4873%; height: 30.9125px;">string</td><td style="width: 16.2059%; height: 30.9125px;">так</td><td style="width: 58.9847%; height: 30.9125px;">Назва ключа.</td></tr><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`pkType`</td><td style="width: 10.4873%; height: 30.9125px;">enum</td><td style="width: 16.2059%; height: 30.9125px;">так</td><td style="width: 58.9847%; height: 30.9125px;">`UA` або `ECDSA`.</td></tr><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`pkStoreType`</td><td style="width: 10.4873%; height: 30.9125px;">enum</td><td style="width: 16.2059%; height: 30.9125px;">так</td><td style="width: 58.9847%; height: 30.9125px;">`HSM` або `FILE`.</td></tr><tr style="height: 47.7125px;"><td style="width: 14.2982%; height: 47.7125px;">[`pkPassword`](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/perelik-metodiv-api-po-roboti-z-portalom-edin-id#bkmrk-1.4.-%D0%9E%D1%82%D1%80%D0%B8%D0%BC%D0%B0%D0%BD%D0%BD%D1%8F-%D0%BF%D1%83%D0%B1%D0%BB%D1%96)</td><td style="width: 10.4873%; height: 47.7125px;">string</td><td style="width: 16.2059%; height: 47.7125px;">для `store=cloud`</td><td style="width: 58.9847%; height: 47.7125px;">Base64 від RSA-encrypted bytes пароля ключа. Шифрувати актуальним public key з `/api/external/key`.</td></tr><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`pkIsStamp`</td><td style="width: 10.4873%; height: 30.9125px;">boolean</td><td style="width: 16.2059%; height: 30.9125px;">так</td><td style="width: 58.9847%; height: 30.9125px;">`true` — печатка, `false` — особистий ключ співробітника.</td></tr><tr style="height: 29.9125px;"><td style="width: 14.2982%; height: 29.9125px;">`emplTitle`</td><td style="width: 10.4873%; height: 29.9125px;">string/null</td><td style="width: 16.2059%; height: 29.9125px;">ні</td><td style="width: 58.9847%; height: 29.9125px;">Посада для CA user.</td></tr><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`emplOrgUnit`</td><td style="width: 10.4873%; height: 30.9125px;">string/null</td><td style="width: 16.2059%; height: 30.9125px;">ні</td><td style="width: 58.9847%; height: 30.9125px;">Підрозділ для CA user.</td></tr><tr style="height: 47.7125px;"><td style="width: 14.2982%; height: 47.7125px;">[`caPassPhrase`](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/perelik-metodiv-api-po-roboti-z-portalom-edin-id#bkmrk-1.4.-%D0%9E%D1%82%D1%80%D0%B8%D0%BC%D0%B0%D0%BD%D0%BD%D1%8F-%D0%BF%D1%83%D0%B1%D0%BB%D1%96)</td><td style="width: 10.4873%; height: 47.7125px;">string</td><td style="width: 16.2059%; height: 47.7125px;">так</td><td style="width: 58.9847%; height: 47.7125px;">Base64 від RSA-encrypted bytes секретної фрази CA user. Шифрувати актуальним public key з `/api/external/key`.</td></tr><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`certType`</td><td style="width: 10.4873%; height: 30.9125px;">enum</td><td style="width: 16.2059%; height: 30.9125px;">так</td><td style="width: 58.9847%; height: 30.9125px;">`SIGN_ONLY` або `SIGN_AND_ENCRYPT`.</td></tr><tr style="height: 30.9125px;"><td style="width: 14.2982%; height: 30.9125px;">`certValidity`</td><td style="width: 10.4873%; height: 30.9125px;">enum</td><td style="width: 16.2059%; height: 30.9125px;">так</td><td style="width: 58.9847%; height: 30.9125px;">`ONE` або `TWO`.</td></tr></tbody></table>

</div>`requests` для `store=file`:

```json
{
  "ecdsa": "base64 PKCS #10 request",
  "signature": "base64 PKCS #10 request",
  "encryption": "base64 PKCS #10 request"
}
```

**Опис полів** `requests` :

<table id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9A%D0%BE%D0%BB%D0%B8-%D0%BF%D0%BE%D1%82%D1%80%D1%96%D0%B1"><thead><tr><th>Поле</th><th>Тип</th><th>Коли потрібне</th><th>Опис</th></tr></thead><tbody><tr><td>`ecdsa`</td><td>string</td><td>`pkType=ECDSA`</td><td>Base64 `PKCS #10` request для ECDSA сертифіката.</td></tr><tr><td>`signature`</td><td>string</td><td>`pkType=UA`</td><td>Base64 `PKCS #10` request для сертифіката підпису.</td></tr><tr><td>`encryption`</td><td>string</td><td>`pkType=UA` і `certType=SIGN_AND_ENCRYPT`</td><td>Base64 `PKCS #10` request для сертифіката шифрування.</td></tr></tbody></table>

##### **RESPONSE**

<div class="wy-table-responsive" id="bkmrk-"></div>В тілі **відповіді** передається статус 200.

**JSON приклад відповіді:**

```json
{
  "pKey": {
    "id": 1001,
    "name": "Ключ Іваненко",
    "uuid": "019ec000-0000-7000-8000-000000000001",
    "status": "COMPANY_GENERATED",
    "storeType": "HSM",
    "keyType": "UA",
    "stamp": false
  },
  "forms": [
    {
      "type": "PK_FORM",
      "pdf": "JVBERi0x...",
      "hash": "HASH_OF_PDF"
    }
  ]
}
```

Для співробітника з роллю `ADMIN` у відповіді додатково буде `PK_APPENDIX`.

**Опис полів відповіді:**

<table id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81-pkey-o"><thead><tr><th>Поле</th><th>Тип</th><th>Опис</th></tr></thead><tbody><tr><td>`pKey`</td><td>object</td><td>Обʼєкт `ESSPrivateKey`, поля описані в розділі 2.3. Використовуйте `pKey.uuid` у методах 9.2 і 9.3.</td></tr><tr><td>`forms`</td><td>object\[\]</td><td>PDF-документи, які потрібно підписати співробітником.</td></tr><tr><td>`forms[].type`</td><td>enum</td><td>Тип форми.</td></tr><tr><td>`forms[].pdf`</td><td>string</td><td>PDF content у base64.</td></tr><tr><td>`forms[].hash`</td><td>string/null</td><td>Hash PDF для контролю цілісності.</td></tr></tbody></table>

##### **CURL**

- **для `store=cloud` :**

```
curl -X POST 'https://host/api/external/company/employee/pkey/generate/draft?...'   -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898'   -F 'info={
    "pkName":"Ключ Іваненко",
    "pkType":"UA",
    "pkStoreType":"HSM",
    "pkPassword":"BASE64_RSA_ENCRYPTED_PASSWORD",
    "pkIsStamp":false,
    "emplTitle":"Менеджер",
    "emplOrgUnit":"Відділ продажів",
    "caPassPhrase":"BASE64_RSA_ENCRYPTED_CA_PASSPHRASE",
    "certType":"SIGN_AND_ENCRYPT",
    "certValidity":"TWO"
  }'
```

- **для `store=file` :**

```
curl -X POST 'https://host/api/external/company/employee/pkey/generate/draft?...'   -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898'   -F 'info={
    "pkName":"Ключ Іваненко",
    "pkType":"UA",
    "pkStoreType":"FILE",
    "pkIsStamp":false,
    "emplTitle":"Менеджер",
    "emplOrgUnit":"Відділ продажів",
    "caPassPhrase":"BASE64_RSA_ENCRYPTED_CA_PASSPHRASE",
    "certType":"SIGN_AND_ENCRYPT",
    "certValidity":"TWO"
  }'   -F 'requests={
    "signature":"BASE64_P10_SIGNATURE",
    "encryption":"BASE64_P10_ENCRYPTION"
  }'
```

##### **Помилки** 

<table id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-400-i"><thead><tr><th>HTTP</th><th>`type`</th><th>Опис</th></tr></thead><tbody><tr><td>400</td><td>`invalid_store`</td><td>`store` не `cloud` і не `file`.</td></tr><tr><td>400</td><td>`employee_not_found`</td><td>Співробітник не знайдений.</td></tr><tr><td>400</td><td>`employee_not_active`</td><td>Співробітник не активний або не ідентифікований.</td></tr><tr><td>400</td><td>`company_not_found`</td><td>Не знайдено company для співробітника.</td></tr><tr><td>400</td><td>`decrypt_error`</td><td>Неможливо розшифрувати `caPassPhrase` або `pkPassword`.</td></tr><tr><td>400</td><td>`employee_identification_not_found`</td><td>Не знайдено підпис ідентифікації співробітника.</td></tr><tr><td>400</td><td>`request_not_found`</td><td>Для `store=file` не переданий потрібний p10-запит.</td></tr><tr><td>400</td><td>`pk_requests_not_found`</td><td>Після створення ключа не знайдені p10-запити.</td></tr><tr><td>403</td><td>`company_access_denied`</td><td>Немає доступу до company.</td></tr><tr><td>403</td><td>`company_wrong_status`</td><td>Компанія не `ACTIVE`.</td></tr></tbody></table>

# Згенерувати PDF-форму для адміністратора компанії PATCH /api/external/company/employee/pkey/generate/draft

<p class="callout info">Цей метод можна викликати повторно. У такому випадку admin-форми будуть перестворені, а попередні варіанти цих форм — перезаписані.</p>

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 97.619%;"><tbody><tr class="row-odd"><td style="width: 18.3144%;">**URL**

</td><td style="width: 81.6612%;">  
</td></tr><tr class="row-even"><td style="width: 18.3144%;">Метод запиту

</td><td style="width: 81.6612%;">PATCH

</td></tr><tr class="row-odd"><td style="width: 18.3144%;">URL запиту

</td><td style="width: 81.6612%;">**/api/external/company/employee/pkey/generate/draft**

</td></tr><tr class="row-even"><td style="width: 18.3144%;">URL параметри

</td><td style="width: 81.6612%;">**companyCode** (обов’язково) - код Компанії;

**pKeyUuid** (обов’язково) - UUID ключа з відповіді на виклик метода [створення чернетки ключа](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft);

**adminIpn** (обов’язково) - ІПН/РНОКПП адміністратора або суперадміністратора компанії, який підписуватиме admin-форми.

Якщо ключ створюється для співробітника з роллю `ADMIN`, у `adminIpn` потрібно передати саме `SUPER_ADMIN` компанії.

</td></tr><tr><td style="width: 18.3144%;">**Authorization**

</td><td style="width: 81.6612%;">  
</td></tr><tr><td style="width: 18.3144%;">Auth type

</td><td style="width: 81.6612%;">API key</td></tr><tr><td style="width: 18.3144%;">Key / Value

</td><td style="width: 81.6612%;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td style="width: 18.3144%;">**Headers**

</td><td style="width: 81.6612%;"> </td></tr><tr class="row-odd"><td style="width: 18.3144%;">Content-Type

</td><td style="width: 81.6612%;">application/json

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

</div>##### **RESPONSE**

В тілі відповіді передається статус 200.

**JSON приклад відповіді:**

```json
{
  "pKey": {
    "uuid": "019ec000-0000-7000-8000-000000000001",
    "status": "COMPANY_GENERATED"
  },
  "forms": [
    {
      "type": "AFFILIATION_CONFIRMATION",
      "pdf": "JVBERi0x...",
      "hash": "HASH_OF_PDF"
    }
  ]
}
```

**Опис полів відповіді:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81-pkey-o"><table><thead><tr><th>Поле</th><th>Тип</th><th>Опис</th></tr></thead><tbody><tr><td>`pKey`</td><td>object</td><td>Обʼєкт `ESSPrivateKey`, поля описані в розділі 2.3.</td></tr><tr><td>`forms`</td><td>object\[\]</td><td>PDF-документи, які потрібно підписати адміністратору/суперадміністратору.</td></tr><tr><td>`forms[].type`</td><td>enum</td><td>Тип форми: `AFFILIATION_CONFIRMATION` або `POWER_OF_ATTORNEY`.</td></tr><tr><td>`forms[].pdf`</td><td>string</td><td>PDF content у base64.</td></tr><tr><td>`forms[].hash`</td><td>string/null</td><td>Hash PDF для контролю цілісності.</td></tr></tbody></table>

</div>Для ключа співробітника з роллю `ADMIN` у відповіді додатково буде `POWER_OF_ATTORNEY`.

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81-pkey-o-1"></div>##### **CURL** 

```
curl -X PATCH 'https://host/api/external/company/employee/pkey/generate/draft?...'   -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898'
```

##### **Помилки** 

<table id="bkmrk-http-type-%D0%9E%D0%BF%D0%B8%D1%81-400-i"><thead><tr><th>HTTP</th><th>`type`</th><th>Опис</th></tr></thead><tbody><tr><td>400</td><td>`invalid_pkey_uuid`</td><td>`pKeyUuid` має неправильний UUID-формат.</td></tr><tr><td>400</td><td>`pkey_not_found`</td><td>Ключ не знайдений або не належить company.</td></tr><tr><td>400</td><td>`pkey_wrong_status`</td><td>Ключ не у статусі `COMPANY_GENERATED`.</td></tr><tr><td>400</td><td>`employee_not_found`</td><td>Співробітник-власник ключа не знайдений.</td></tr><tr><td>400</td><td>`employee_not_active`</td><td>Співробітник-власник ключа не активний або не ідентифікований.</td></tr><tr><td>400</td><td>`admin_not_found`</td><td>Адміністратор не знайдений.</td></tr><tr><td>400</td><td>`admin_not_active`</td><td>Адміністратор не активний або не ідентифікований.</td></tr><tr><td>400</td><td>`admin_wrong_role`</td><td>Переданий користувач не має ролі адміністратора/суперадміністратора.</td></tr><tr><td>400</td><td>`admin_must_be_super_admin`</td><td>Для цього ключа потрібен підпис суперадміністратора.</td></tr><tr><td>403</td><td>`company_access_denied`</td><td>Немає доступу до company.</td></tr><tr><td>403</td><td>`company_wrong_status`</td><td>Компанія не `ACTIVE`.</td></tr></tbody></table>

# Передати підписи PDF і активувати ключ POST /api/external/company/employee/pkey/activation

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 79.4048%;"><tbody><tr class="row-odd"><td style="width: 20.8995%;">**URL**

</td><td style="width: 79.0704%;">  
</td></tr><tr class="row-even"><td style="width: 20.8995%;">Метод запиту

</td><td style="width: 79.0704%;">POST

</td></tr><tr class="row-odd"><td style="width: 20.8995%;">URL запиту

</td><td style="width: 79.0704%;">**/api/external/company/employee/pkey/activation**

</td></tr><tr class="row-even"><td style="width: 20.8995%;">URL параметри

</td><td style="width: 79.0704%;">**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника.

</td></tr><tr><td style="width: 20.8995%;">**Authorization**

</td><td style="width: 79.0704%;">  
</td></tr><tr><td style="width: 20.8995%;">Auth type

</td><td style="width: 79.0704%;">API key</td></tr><tr><td style="width: 20.8995%;">Key / Value

</td><td style="width: 79.0704%;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td style="width: 20.8995%;">**Headers**

</td><td style="width: 79.0704%;"> </td></tr><tr class="row-odd"><td style="width: 20.8995%;">Content-Type

</td><td style="width: 79.0704%;">application/json

</td></tr><tr><td style="width: 20.8995%;">**REQUEST**

</td><td style="width: 79.0704%;"> </td></tr><tr><td style="width: 20.8995%;">JSON Body

</td><td style="width: 79.0704%;">Приклад запиту:

```json
{
  "keyUuid": "019ec000-0000-7000-8000-000000000001",
  "activate": true,
  "forms": {
    "PK_FORM": [
      "BASE64_DETACHED_SIGNATURE_BY_EMPLOYEE",
      "BASE64_DETACHED_SIGNATURE_BY_ADMIN"
    ],
    "PK_APPENDIX": [
      "BASE64_DETACHED_SIGNATURE_BY_EMPLOYEE",
      "BASE64_DETACHED_SIGNATURE_BY_SUPER_ADMIN"
    ],
    "AFFILIATION_CONFIRMATION": [
      "BASE64_DETACHED_SIGNATURE_BY_ADMIN"
    ],
    "POWER_OF_ATTORNEY": [
      "BASE64_DETACHED_SIGNATURE_BY_SUPER_ADMIN"
    ]
  }
}
```

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

</div>**Опис полів запиту:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5-4"><table style="width: 100%;"><thead><tr><th style="width: 13.8227%;">Поле</th><th style="width: 12.514%;">Тип</th><th style="width: 17.5146%;">Обовʼязкове</th><th style="width: 56.244%;">Опис</th></tr></thead><tbody><tr><td style="width: 13.8227%;">`keyUuid`</td><td style="width: 12.514%;">string UUID</td><td style="width: 17.5146%;">так</td><td style="width: 56.244%;">UUID ключа з відповіді 9.1: `pKey.uuid`.</td></tr><tr><td style="width: 13.8227%;">`activate`</td><td style="width: 12.514%;">boolean</td><td style="width: 17.5146%;">так</td><td style="width: 56.244%;">`true` — одразу активувати ключ; `false` — передати ключ на активацію КНЕДП.</td></tr><tr><td style="width: 13.8227%;">`forms`</td><td style="width: 12.514%;">object/map</td><td style="width: 17.5146%;">так</td><td style="width: 56.244%;">Map підписів для PDF-документів, отриманих у 9.1 та 9.2.</td></tr><tr><td style="width: 13.8227%;">`forms.{formType}`</td><td style="width: 12.514%;">string\[\]</td><td style="width: 17.5146%;">так для кожної PDF-форми</td><td style="width: 56.244%;">Масив detached-підписів PDF у base64. Ключ map — enum name `ESSRegFormType`.</td></tr></tbody></table>

</div><p class="callout warning">**Важливо**:  
- треба передати підписи для кожної PDF-форми, отриманої у 9.1 та 9.2;  
- підпис має бути detached: у forms.{formType} передається тільки підпис у base64, без PDF-контенту;  
- підпис має бути сформований по точних bytes PDF з поля pdf відповідної форми;  
- для одного formType треба передати масив підписів, навіть якщо підпис один.</p>

**Правила підписання:**

<div class="c_tableWrapper__a48" id="bkmrk-formtype-%D0%A5%D1%82%D0%BE-%D0%BF%D1%96%D0%B4%D0%BF%D0%B8%D1%81%D1%83"><table style="width: 62.7381%;"><thead><tr><th style="width: 44.9102%;">`formType`</th><th style="width: 55.2741%;">Хто підписує</th></tr></thead><tbody><tr><td style="width: 44.9102%;">`PK_FORM`</td><td style="width: 55.2741%;">співробітник + admin/super\_admin</td></tr><tr><td style="width: 44.9102%;">`PK_APPENDIX`</td><td style="width: 55.2741%;">співробітник + super\_admin</td></tr><tr><td style="width: 44.9102%;">`AFFILIATION_CONFIRMATION`</td><td style="width: 55.2741%;">admin/super\_admin</td></tr><tr><td style="width: 44.9102%;">`POWER_OF_ATTORNEY`</td><td style="width: 55.2741%;">super\_admin</td></tr></tbody></table>

</div>##### **RESPONSE**

В тілі відповіді передаються статус 200 та оновлений повний [обʼєкт ESSPrivateKey](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/obekt-essprivatekey) .

Якщо `activate=true`, очікуваний статус:

```json
{
  "uuid": "019ec000-0000-7000-8000-000000000001",
  "status": "ACTIVATED"
}
```

Якщо `activate=false`, очікуваний статус:

```json
{
  "uuid": "019ec000-0000-7000-8000-000000000001",
  "status": "COMPANY_ADMIN_APPROVED"
}
```

##### **CURL** 

```
curl -X POST 'https://host/api/external/company/employee/pkey/activation?...'   -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898'   -H 'Content-Type: application/json'   -d '{
    "keyUuid": "019ec000-0000-7000-8000-000000000001",
    "activate": true,
    "forms": {
      "PK_FORM": [
        "BASE64_DETACHED_SIGNATURE_BY_EMPLOYEE",
        "BASE64_DETACHED_SIGNATURE_BY_ADMIN"
      ],
      "AFFILIATION_CONFIRMATION": [
        "BASE64_DETACHED_SIGNATURE_BY_ADMIN"
      ]
    }
  }'
```

##### **Помилки** 

<table id="bkmrk-http-type-%D0%94%D0%BE%D0%B4%D0%B0%D1%82%D0%BA%D0%BE%D0%B2%D1%96-"><thead><tr><th>HTTP</th><th>`type`</th><th>Додаткові поля</th><th>Опис</th></tr></thead><tbody><tr><td>400</td><td>`key_uuid_not_found`</td><td>—</td><td>Не переданий `keyUuid`.</td></tr><tr><td>400</td><td>`employee_not_found`</td><td>—</td><td>Співробітник не знайдений.</td></tr><tr><td>400</td><td>`employee_not_active`</td><td>—</td><td>Співробітник не активний або не ідентифікований.</td></tr><tr><td>400</td><td>`pkey_not_found`</td><td>—</td><td>Ключ не знайдений або не належить company/employee.</td></tr><tr><td>400</td><td>`pkey_wrong_status`</td><td>`status`</td><td>Ключ не у статусі `COMPANY_GENERATED`.</td></tr><tr><td>400</td><td>`forms_not_found`</td><td>—</td><td>Не передані підписи або для ключа немає PDF-форм.</td></tr><tr><td>400</td><td>`unexpected_form`</td><td>`formType`</td><td>Переданий підпис для форми, яка не була згенерована для ключа.</td></tr><tr><td>400</td><td>`admin_not_found`</td><td>—</td><td>Адміністратор не знайдений.</td></tr><tr><td>400</td><td>`admin_not_active`</td><td>—</td><td>Адміністратор не активний або не ідентифікований.</td></tr><tr><td>400</td><td>`admin_wrong_role`</td><td>—</td><td>Адміністратор не має ролі admin/super\_admin.</td></tr><tr><td>400</td><td>`admin_must_be_super_admin`</td><td>—</td><td>Для однієї з форм потрібен super\_admin.</td></tr><tr><td>400</td><td>`form_sign_not_found`</td><td>`formType`</td><td>Не переданий підпис для однієї зі збережених форм.</td></tr><tr><td>400</td><td>`unsupported_form`</td><td>`formType`</td><td>Непідтримуваний тип форми для цього запиту.</td></tr><tr><td>400</td><td>`wrong_sign_count`</td><td>`formType`</td><td>Кількість підписів для форми не відповідає очікуваній.</td></tr><tr><td>400</td><td>`duplicate_signature`</td><td>`formType`</td><td>Для форми передано однаковий підпис більше одного разу.</td></tr><tr><td>400</td><td>`invalid_signature`</td><td>`formType`</td><td>Підпис не проходить перевірку для PDF.</td></tr><tr><td>400</td><td>`wrong_signer`</td><td>`formType`</td><td>Підписант не відповідає очікуваному підписанту форми.</td></tr><tr><td>403</td><td>`company_access_denied`</td><td>—</td><td>Немає доступу до company.</td></tr><tr><td>403</td><td>`company_wrong_status`</td><td>`status`</td><td>Компанія не `ACTIVE`.</td></tr></tbody></table>

# Змінити статус ключа POST /api/external/company/pkey/status

Метод змінює статус ключа компанії/співробітника та одразу формує, підписує і зберігає PDF-підтвердження зміни статусу.

Клієнт не підписує PDF самостійно, а передає UUID ключа адміністратора/суперадміністратора та зашифрований пароль до нього. Після чого API:

1. формує PDF-форми зміни статусу;
2. підписує їх ключем адміністратора/суперадміністратора;
3. зберігає підписані PDF як підтвердження зміни статусу;
4. змінює статус ключа у системі;
5. передає зміну статусу до центру сертифікації;
6. повертає масив підписаних PDF.

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 89.7619%;"><colgroup><col style="width: 22.2581%;"></col><col style="width: 77.8413%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>POST

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/pkey/status**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>JSON Body

</td><td> **JSON приклад запиту:**

```json
{
  "keyUuid": "019ec000-0000-7000-8000-000000000001",
  "action": "hold",
  "adminKeyUuid": "019ec000-0000-7000-8000-000000000099",
  "adminKeyPassword": "BASE64_RSA_ENCRYPTED_ADMIN_KEY_PASSWORD",
  "reason": "Компрометація ключа"
}
```

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

</div>**Опис полів запиту:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5-5"><table style="width: 100%;"><thead><tr><th style="width: 17.1592%;">Поле</th><th style="width: 10.9628%;">Тип</th><th style="width: 11.9158%;">Обовʼязкове</th><th style="width: 59.9384%;">Опис</th></tr></thead><tbody><tr><td style="width: 17.1592%;">`keyUuid`</td><td style="width: 10.9628%;">string UUID</td><td style="width: 11.9158%;">так</td><td style="width: 59.9384%;">UUID ключа, статус якого треба змінити.</td></tr><tr><td style="width: 17.1592%;">`action`</td><td style="width: 10.9628%;">enum</td><td style="width: 11.9158%;">так</td><td style="width: 59.9384%;">Дія:

- `hold` - призупинити активний ключ.
- `unhold` - відновити ключ зі статусу `HOLD`.
- `revoke` - скасувати/відкликати ключ.

</td></tr><tr><td style="width: 17.1592%;">`adminKeyUuid`</td><td style="width: 10.9628%;">string UUID</td><td style="width: 11.9158%;">так</td><td style="width: 59.9384%;">UUID ключа адміністратора/суперадміністратора цієї компанії.</td></tr><tr><td style="width: 17.1592%;">`adminKeyPassword`</td><td style="width: 10.9628%;">string</td><td style="width: 11.9158%;">так</td><td style="width: 59.9384%;">Base64 від RSA-encrypted bytes пароля ключа адміністратора/суперадміністратора. Шифрувати public key з `/api/external/key`; див. розділ 1.4.</td></tr><tr><td style="width: 17.1592%;">`reason`</td><td style="width: 10.9628%;">string</td><td style="width: 11.9158%;">так</td><td style="width: 59.9384%;">Причина зміни статусу. Мінімум 4 символи після trim. Потрапляє у PDF і в історію статусів.</td></tr></tbody></table>

</div>API перевіряє, чи дозволена дія для поточного статусу ключа. Наприклад, `hold` дозволений тільки для `ACTIVATED`, а `unhold` — для ключа у статусі `HOLD`.

##### **RESPONSE**

В тілі відповіді передаються статус 200 та масив рядків. Кожен рядок — підписаний PDF у base64.

**JSON приклад відповіді:**

```
[
  "BASE64_SIGNED_STATUS_CHANGE_PDF"
]
```

Якщо для ключа є дочірні файлові ключі, які мають змінювати статус каскадно, у відповіді буде кілька елементів: основний ключ + дочірні ключі.

##### **CURL** 

```
curl -X POST 'https://host/api/external/company/pkey/status?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -H 'Content-Type: application/json' \
  -d '{
    "keyUuid": "019ec000-0000-7000-8000-000000000001",
    "action": "hold",
    "adminKeyUuid": "019ec000-0000-7000-8000-000000000099",
    "adminKeyPassword": "BASE64_RSA_ENCRYPTED_ADMIN_KEY_PASSWORD",
    "reason": "Компрометація ключа"
  }'
```

##### **Помилки**

<table id="bkmrk-http-type-%D0%94%D0%BE%D0%B4%D0%B0%D1%82%D0%BA%D0%BE%D0%B2%D1%96-" style="width: 100%;"><thead><tr><th style="width: 6.67302%;">HTTP</th><th style="width: 20.734%;">`type`</th><th style="width: 19.1855%;">Додаткові поля</th><th style="width: 53.5028%;">Опис</th></tr></thead><tbody><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`decrypt_error`</td><td style="width: 19.1855%;">`field=adminKeyPassword`</td><td style="width: 53.5028%;">Не вдалося розшифрувати пароль ключа адміністратора/суперадміністратора.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`pkey_not_found`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Ключ `keyUuid` не знайдений або не належить company.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`employee_not_found`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Власник ключа не знайдений як співробітник company.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`admin_pkey_not_found`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Ключ адміністратора/суперадміністратора не знайдений або не належить company.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`admin_required`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Власник `adminKeyUuid` не має ролі `ADMIN`/`SUPER_ADMIN`.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`invalid_password`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Пароль ключа адміністратора/суперадміністратора неправильний.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`invalid_reason`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">`reason` порожній або коротший за 4 символи після trim.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`unsupported_action`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">У `action` передано не `hold`, `unhold` або `revoke`.</td></tr><tr><td style="width: 6.67302%;">400</td><td style="width: 20.734%;">`pkey_wrong_status`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Перехід статусу не дозволений для поточного стану ключа.</td></tr><tr><td style="width: 6.67302%;">403</td><td style="width: 20.734%;">`company_access_denied`</td><td style="width: 19.1855%;">—</td><td style="width: 53.5028%;">Немає доступу до company.</td></tr><tr><td style="width: 6.67302%;">403</td><td style="width: 20.734%;">`company_wrong_status`</td><td style="width: 19.1855%;">`status`</td><td style="width: 53.5028%;">Компанія не `ACTIVE`.</td></tr></tbody></table>

# Змінити статус співробітника POST /api/external/company/employee/status

Метод змінює статус співробітника компанії. Якщо дія вимагає каскадної зміни статусів ключів співробітника, API формує PDF-документи зміни статусу ключів, підписує їх ключем адміністратора/суперадміністратора, зберігає підтвердження і змінює статуси ключів.

Клієнт не підписує PDF самостійно. Клієнт передає UUID ключа адміністратора/суперадміністратора та зашифрований пароль до нього.

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 87.2619%;"><colgroup><col style="width: 22.2824%;"></col><col style="width: 77.6874%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>POST

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/employee/status**

</td></tr><tr class="row-even"><td>URL параметри

</td><td>**companyCode** (обов’язково) - код Компанії;

**employeeIpn** (обов’язково) - ІПН/РНОКПП співробітника.

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>JSON Body

</td><td> **JSON приклад запиту:**

```
{
  "action": "BLOCKED",
  "adminKeyUuid": "019ec000-0000-7000-8000-000000000099",
  "adminKeyPassword": "BASE64_RSA_ENCRYPTED_ADMIN_KEY_PASSWORD",
  "reason": "Тимчасове блокування співробітника"
}
```

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

</div>**Опис полів запиту:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5-6"><table style="width: 100%; height: 185.537px;"><thead><tr style="height: 29.6px;"><th style="width: 16.4442%; height: 29.6px;">Поле</th><th style="width: 11.082%; height: 29.6px;">Тип</th><th style="width: 12.0349%; height: 29.6px;">Обовʼязкове</th><th style="width: 60.415%; height: 29.6px;">Опис</th></tr></thead><tbody><tr style="height: 30.9125px;"><td style="width: 16.4442%; height: 30.9125px;">`action`</td><td style="width: 11.082%; height: 30.9125px;">enum</td><td style="width: 12.0349%; height: 30.9125px;">так</td><td style="width: 60.415%; height: 30.9125px;">Новий статус/дія для співробітника: `ACTIVE`, `BLOCKED`, `FIRED`, `REHIRED`.</td></tr><tr style="height: 30.9125px;"><td style="width: 16.4442%; height: 30.9125px;">`adminKeyUuid`</td><td style="width: 11.082%; height: 30.9125px;">string UUID</td><td style="width: 12.0349%; height: 30.9125px;">так</td><td style="width: 60.415%; height: 30.9125px;">UUID ключа адміністратора/суперадміністратора цієї компанії.</td></tr><tr style="height: 47.7125px;"><td style="width: 16.4442%; height: 47.7125px;">`<a href="https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/perelik-metodiv-api-po-roboti-z-portalom-edin-id#bkmrk-1.4.-%D0%9E%D1%82%D1%80%D0%B8%D0%BC%D0%B0%D0%BD%D0%BD%D1%8F-%D0%BF%D1%83%D0%B1%D0%BB%D1%96">adminKeyPassword</a>`</td><td style="width: 11.082%; height: 47.7125px;">string</td><td style="width: 12.0349%; height: 47.7125px;">так</td><td style="width: 60.415%; height: 47.7125px;">Base64 від RSA-encrypted bytes пароля ключа адміністратора/суперадміністратора. Шифрувати public key з `/api/external/key`.</td></tr><tr style="height: 46.4px;"><td style="width: 16.4442%; height: 46.4px;">`reason`</td><td style="width: 11.082%; height: 46.4px;">string</td><td style="width: 12.0349%; height: 46.4px;">так</td><td style="width: 60.415%; height: 46.4px;">Причина зміни статусу. Мінімум 4 символи після trim. Потрапляє у PDF-документи зміни статусу ключів і в історію статусів співробітника.</td></tr></tbody></table>

</div>**Дозволені переходи статусів:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D1%82%D0%BE%D1%87%D0%BD%D0%B8%D0%B9-%D1%81%D1%82%D0%B0%D1%82%D1%83%D1%81-%D1%81%D0%BF%D1%96%D0%B2"><table style="width: 53.5714%;"><thead><tr><th style="width: 61.5682%;">Поточний статус співробітника</th><th style="width: 38.3766%;">Дозволені `action`</th></tr></thead><tbody><tr><td style="width: 61.5682%;">`ACTIVE`</td><td style="width: 38.3766%;">`BLOCKED`, `FIRED`</td></tr><tr><td style="width: 61.5682%;">`REHIRED`</td><td style="width: 38.3766%;">`BLOCKED`, `FIRED`</td></tr><tr><td style="width: 61.5682%;">`BLOCKED`</td><td style="width: 38.3766%;">`ACTIVE`, `FIRED`</td></tr><tr><td style="width: 61.5682%;">`FIRED`</td><td style="width: 38.3766%;">`REHIRED`</td></tr></tbody></table>

</div>Якщо передати недозволений перехід, API поверне `wrong_action`.

##### **RESPONSE**

В тілі відповіді передаються статус 200.

**JSON приклад відповіді:**

```json
{
  "employee": {
    "id": 456,
    "login": "380501112233",
    "email": "employee@example.com",
    "fullName": "Іваненко Іван Іванович",
    "ipn": "3148615913",
    "role": "USER",
    "employeeStatus": "BLOCKED",
    "employeeEmail": "employee@example.com"
  },
  "pdf": [
    "BASE64_SIGNED_STATUS_CHANGE_PDF"
  ]
}
```

**Опис полів відповіді:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81-employ"><table style="width: 80.3571%;"><thead><tr><th style="width: 14.009%;">Поле</th><th style="width: 10.377%;">Тип</th><th style="width: 75.5794%;">Опис</th></tr></thead><tbody><tr><td style="width: 14.009%;">`employee`</td><td style="width: 10.377%;">object</td><td style="width: 75.5794%;">Оновлений JSON-обʼєкт `ESSUser`. Поля описані в розділі 2.2.</td></tr><tr><td style="width: 14.009%;">`pdf`</td><td style="width: 10.377%;">string\[\]</td><td style="width: 75.5794%;">Масив підписаних PDF-документів зміни статусу ключів у base64.</td></tr></tbody></table>

</div>Для `REHIRED` PDF-документи за ключами не формуються, тому `pdf` буде порожнім масивом.

Якщо у співробітника немає ключів, для яких потрібно виконати каскадну зміну статусу, `pdf` також буде порожнім масивом.

В історії статусів ключів дія фіксується як виконана адміністратором компанії.

##### **CURL** 

```
curl -X POST 'https://host/api/external/company/employee/status?...' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "BLOCKED",
    "adminKeyUuid": "019ec000-0000-7000-8000-000000000099",
    "adminKeyPassword": "BASE64_RSA_ENCRYPTED_ADMIN_KEY_PASSWORD",
    "reason": "Тимчасове блокування співробітника"
  }'
```

##### **Помилки** 

<table id="bkmrk-http-type-%D0%94%D0%BE%D0%B4%D0%B0%D1%82%D0%BA%D0%BE%D0%B2%D1%96-" style="width: 100%;"><thead><tr><th style="width: 6.31554%;">HTTP</th><th style="width: 21.2144%;">`type`</th><th style="width: 17.6321%;">Додаткові поля</th><th style="width: 54.9333%;">Опис</th></tr></thead><tbody><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`employee_not_found`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Співробітник не знайдений.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`wrong_action`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Перехід статусу не дозволений.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`unsupported_action`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">`action` не передано або не підтримується.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`invalid_reason`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">`reason` порожній або коротший за 4 символи після trim.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`decrypt_error`</td><td style="width: 17.6321%;">`field=adminKeyPassword`</td><td style="width: 54.9333%;">Не вдалося розшифрувати пароль ключа адміністратора/суперадміністратора.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`admin_pkey_not_found`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Ключ адміністратора/суперадміністратора не знайдено або не належить company.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`admin_required`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Власник `adminKeyUuid` не має ролі `ADMIN`/`SUPER_ADMIN`.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`invalid_password`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Пароль ключа адміністратора/суперадміністратора неправильний.</td></tr><tr><td style="width: 6.31554%;">400</td><td style="width: 21.2144%;">`pkey_wrong_status`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Каскадна зміна статусу одного з ключів неможлива для поточного стану ключа.</td></tr><tr><td style="width: 6.31554%;">403</td><td style="width: 21.2144%;">`company_access_denied`</td><td style="width: 17.6321%;">—</td><td style="width: 54.9333%;">Немає доступу до company.</td></tr><tr><td style="width: 6.31554%;">403</td><td style="width: 21.2144%;">`company_wrong_status`</td><td style="width: 17.6321%;">`status`</td><td style="width: 54.9333%;">Компанія не `ACTIVE`.</td></tr></tbody></table>

# Верифікувати підпис на файлі POST /api/external/company/sign/file/verify

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-pos"><table class="colwidths-given docutils align-default" style="width: 97.1429%; height: 506.812px;"><colgroup><col style="width: 25.6844%;"></col><col style="width: 74.4386%;"></col></colgroup><tbody><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**URL**

</td><td style="height: 29.6px;">  
</td></tr><tr class="row-even" style="height: 29.6px;"><td style="height: 29.6px;">Метод запиту

</td><td style="height: 29.6px;">POST

</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">URL запиту

</td><td style="height: 29.6px;">**<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**

</td></tr><tr class="row-even" style="height: 209.5px;"><td style="height: 209.5px;">URL параметри

</td><td style="height: 209.5px;">**format** (enum) - формат передачі файлів (`binary` за замовчуванням або `base64`).

**type** (enum) - тип підпису:

- `enveloped` (за замовчуванням) - очікується **рівно 1 файл**. Якщо передано 0 або &gt;1 файлу, метод повертає помилку 400.
- `detached` - очікується **мінімум 2 файли** (1 оригінальний документ + 1 або більше файлів підпису `.p7s`). Якщо передано менше 2 файлів, метод повертає помилку 400.

**returnOriginal** (boolean) - прапорець повернення оригінального файлу (false за замовчуванням або true).

</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">**Authorization**

</td><td style="height: 29.6px;">  
</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">Auth type

</td><td style="height: 29.6px;">API key</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">Key / Value

</td><td style="height: 29.6px;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">**Headers**

</td><td style="height: 29.6px;"> </td></tr><tr class="row-odd" style="height: 29.6px;"><td style="height: 29.6px;">Content-Type

</td><td style="height: 29.6px;">multipart/form-data

</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">**REQUEST**

</td><td style="height: 29.6px;"> </td></tr><tr style="height: 30.9125px;"><td style="height: 30.9125px;">JSON Body

</td><td style="height: 30.9125px;"> У тілі запиту передається масив файлів (контент у форматі згідно з параметром `format`).

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

</div>##### **RESPONSE**

```
{signInfo: [EndUserSignInfo], originalFile: "original file in base64"}
```

**Приклад EndUserSignInfo:**

```json
{
    "ownerInfo": {
        "issuer": "O=ТОВ \"АТС\";OU=Відділ електронних довірчих послуг;CN=Тестовий НЕДП ТОВ \"АТС\";Serial=UA-12345678-1111;C=UA;L=Київ;OI=NTRUA-12345678",
        "issuerCN": "Тестовий НЕДП ТОВ \"АТС\"",
        "serial": "447D03645BB037EB040000002100000078000000",
        "subject": "O=ТОВ \"АТС\";Title=генеральний директор;CN=ІВАНЕНКО ІВАН ІВАНОВИЧ;SN=ІВАНЕНКО;GivenName=ІВАН ІВАНОВИЧ;Serial=TINUA-3456789012;C=UA;L=Київ;OI=NTRUA-12345678",
        "subjCN": "ІВАНЕНКО ІВАН ІВАНОВИЧ",
        "subjOrg": "ТОВ \"АТС\"",
        "subjTitle": "генеральний директор",
        "subjLocality": "Київ",
        "subjFullName": "ІВАНЕНКО ІВАН ІВАНОВИЧ",
        "subjAddress": "03061, м. Київ, вул. Михайла Донця, буд. 6",
        "subjPhone": "+38 (0 11) 111-11-11",
        "subjEMail": "testtest@edin.ua",
        "subjEDRPOUCode": "12345678",
        "subjDRFOCode": "3456789012"
    },
    "timeInfo": {
        "isTimeAvail": true,
        "isTimeStamp": true,
        "time": "Mar 26, 2026, 11:26:29 AM",
        "timeArray": [
            126,
            2,
            26,
            11,
            26,
            29
        ]
    }
}
```

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"></div>

# Отримати інформацію про сертифікат GET /api/external/company/key/certificate

##### **REQUEST**

<div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"><table class="colwidths-given docutils align-default" style="width: 78.9286%;"><tbody><tr class="row-odd"><td style="width: 25.6011%;">**URL**

</td><td style="width: 74.3544%;">  
</td></tr><tr class="row-even"><td style="width: 25.6011%;">Метод запиту

</td><td style="width: 74.3544%;">GET

</td></tr><tr class="row-odd"><td style="width: 25.6011%;">URL запиту

</td><td style="width: 74.3544%;">**/api/external/company/key/certificate**

</td></tr><tr class="row-even"><td style="width: 25.6011%;">URL параметри

</td><td style="width: 74.3544%;">**key** (обов’язково) - uuid ключа;

</td></tr><tr><td style="width: 25.6011%;">**Authorization**

</td><td style="width: 74.3544%;">  
</td></tr><tr><td style="width: 25.6011%;">Auth type

</td><td style="width: 74.3544%;">API key</td></tr><tr><td style="width: 25.6011%;">Key / Value

</td><td style="width: 74.3544%;">**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td style="width: 25.6011%;">**Headers**

</td><td style="width: 74.3544%;"> </td></tr><tr class="row-odd"><td style="width: 25.6011%;">Content-Type

</td><td style="width: 74.3544%;">application/json

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

</div>##### **RESPONSE**

У відповідь повертається об'єкт [EndUserCertificateInfoEx](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-endusercertificateinfoex) з інформацією про сертифікат.

# Створення компанії POST /api/external/company/create

Метод створює компанію у статусі `DRAFT`, з договором-офертою `OFFER`, створює чернетку ключа суперадміністратора та привʼязує компанію до зовнішньої системи.

Якщо компанія з таким кодом вже привʼязана до цієї зовнішньої системи, метод не створює нову компанію, а повертає існуючий обʼєкт `ESSCompany`.

Якщо компанія з таким кодом вже активна, але не привʼязана до цієї зовнішньої системи, метод повертає помилку `company_already_active`.

##### **REQUEST**

<div class="c_container__c89" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-pos"><div class="copy-code-container"><div class="wy-table-responsive"><table class="colwidths-given docutils align-default" style="width: 78.8095%;"><colgroup><col style="width: 21.1568%;"></col><col style="width: 78.8043%;"></col></colgroup><tbody><tr class="row-odd"><td>**URL**

</td><td>  
</td></tr><tr class="row-even"><td>Метод запиту

</td><td>POST

</td></tr><tr class="row-odd"><td>URL запиту

</td><td>**/api/external/company/create**

</td></tr><tr><td>**Authorization**

</td><td>  
</td></tr><tr><td>Auth type

</td><td>API key</td></tr><tr><td>Key / Value

</td><td>**x-system-id** - токен, отриманий при підключенні</td></tr><tr class="row-odd"><td>**Headers**

</td><td> </td></tr><tr class="row-odd"><td>Content-Type

</td><td>application/json

</td></tr><tr><td>**REQUEST**

</td><td> </td></tr><tr><td>REQUEST Body

</td><td>**info** - дані суперадміністратора компанії, для якого буде створено чернетку ключа.

**company -** обʼєкт з даними про компанію [ESSCompany](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscompany)

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

</div></div></div>**COMPANY:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A4%D0%BE%D1%80%D0%BC%D0%B0%D1%82-%D0%A2%D0%B8%D0%BF-1-%D0%9E%D0%BF"><table style="width: 78.8095%;"><thead><tr><th style="width: 16.9098%;">Поле</th><th style="width: 13.2626%;">Формат</th><th style="width: 16.5782%;">Тип <sup>1</sup></th><th style="width: 53.2162%;">Опис</th></tr></thead><tbody><tr><td style="width: 16.9098%;">`fullName`</td><td style="width: 13.2626%;">string</td><td style="width: 16.5782%;">M</td><td style="width: 53.2162%;">Повна назва компанії/ФОП.</td></tr><tr><td style="width: 16.9098%;">`shortName`</td><td style="width: 13.2626%;">string</td><td style="width: 16.5782%;">M</td><td style="width: 53.2162%;">Скорочена назва компанії/ФОП.</td></tr><tr><td style="width: 16.9098%;">`fullNameEN`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">Повна назва англійською.</td></tr><tr><td style="width: 16.9098%;">`shortNameEN`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">Скорочена назва англійською.</td></tr><tr><td style="width: 16.9098%;">`type`</td><td style="width: 13.2626%;">enum</td><td style="width: 16.5782%;">M</td><td style="width: 53.2162%;">Тип компанії: `COMPANY` або `SELF_EMPLOYED`.</td></tr><tr><td style="width: 16.9098%;">`code`</td><td style="width: 13.2626%;">string</td><td style="width: 16.5782%;">M</td><td style="width: 53.2162%;">Для компанії — ЄДРПОУ, для ФОП — РНОКПП.</td></tr><tr><td style="width: 16.9098%;">`ipn`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">ІПН платника ПДВ, якщо є.</td></tr><tr><td style="width: 16.9098%;">`country`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">Країна.</td></tr><tr><td style="width: 16.9098%;">`state`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">Область/регіон.</td></tr><tr><td style="width: 16.9098%;">`locality`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">Населений пункт.</td></tr><tr><td style="width: 16.9098%;">`street`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">Адреса.</td></tr><tr><td style="width: 16.9098%;">`ceoName`</td><td style="width: 13.2626%;">string/null</td><td style="width: 16.5782%;">O</td><td style="width: 53.2162%;">ПІБ керівника.</td></tr></tbody></table>

</div><dl class="footnote brackets" id="bkmrk-1---%D0%9F%D1%96%D0%B4-%D0%B2%D0%B8%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%BD%D1%8F%D0%BC-"><dt class="label">---

</dt><dt class="label" id="bkmrk-1---%D0%9F%D1%96%D0%B4-%D0%B2%D0%B8%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%BD%D1%8F%D0%BC--1"><span class="brackets">1 - </span>Під визначенням колонки **Тип поля** мається на увазі скорочене позначення:</dt><dd>- M (mandatory) — обов’язкові до заповнення поля;
- O (optional) — необов’язкові (опціональні) до заповнення поля.

</dd></dl><div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5"></div>Поля договору у запиті передавати не потрібно. Сервер завжди створює компанію з:

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%97%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%BD%D1%8F-status"><table><thead><tr><th>Поле</th><th>Значення</th></tr></thead><tbody><tr><td>`status`</td><td>`DRAFT`</td></tr><tr><td>`agreemType`</td><td>`OFFER`</td></tr><tr><td>`agreemNumber`</td><td>`null`</td></tr><tr><td>`agreemDate`</td><td>`0`</td></tr></tbody></table>

</div>**INFO:**

<div class="c_tableWrapper__a48" id="bkmrk-%D0%9F%D0%BE%D0%BB%D0%B5-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%B1%D0%BE%D0%B2%CA%BC%D1%8F%D0%B7%D0%BA%D0%BE%D0%B2%D0%B5-1"><table><thead><tr><th>Поле</th><th>Тип</th><th>Обовʼязкове</th><th>Опис</th></tr></thead><tbody><tr><td>`fullName`</td><td>string</td><td>так</td><td>ПІБ суперадміністратора.</td></tr><tr><td>`ipn`</td><td>string</td><td>так</td><td>ІПН/РНОКПП суперадміністратора.</td></tr><tr><td>`phone`</td><td>string</td><td>так</td><td>Телефон у форматі `380XXXXXXXXX`.</td></tr><tr><td>`email`</td><td>string</td><td>так</td><td>Email суперадміністратора.</td></tr><tr><td>`organizationUnit`</td><td>string/null</td><td>ні</td><td>Підрозділ для даних ключа.</td></tr><tr><td>`position`</td><td>string/null</td><td>ні</td><td>Посада для даних ключа.</td></tr></tbody></table>

</div><div class="c_container__c89" id="bkmrk-"><div class="copy-code-container"><div class="wy-table-responsive" id="bkmrk-url-%D0%9C%D0%B5%D1%82%D0%BE%D0%B4-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83-get"></div></div></div><div class="c_container__c89" id="bkmrk--1"><div class="copy-code-container"><details><summary>JSON приклад запиту</summary>

<div class="c_container__c89" id="bkmrk--2"><div class="copy-code-container">  
</div></div>```json
{
  "company": {
    "fullName": "ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ \"ТЕСТ\"",
    "shortName": "ТОВ \"ТЕСТ\"",
    "fullNameEN": "TEST LLC",
    "shortNameEN": "TEST LLC",
    "type": "COMPANY",
    "code": "00000000",
    "ipn": null,
    "country": "UA",
    "state": "м. Київ",
    "locality": "Київ",
    "street": "вул. Тестова, 1",
    "ceoName": "Іваненко Іван Іванович"
  },
  "info": {
    "fullName": "Іваненко Іван Іванович",
    "ipn": "0000000000",
    "phone": "380671234567",
    "email": "ivanenko@example.com",
    "organizationUnit": "Адміністрація",
    "position": "Директор"
  }
}

```

<div class="c_container__c89" id="bkmrk--3"><div class="copy-code-container">  
</div></div></details></div></div>##### **RESPONSE** 

У відповідь повертаються статус 200 та обʼєкт [ESSCompany.](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscompany)

<div class="c_container__c89" id="bkmrk--4"></div>##### **CURL**

```bash
curl -X POST 'https://host/api/external/company/create' \
  -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' \
  -H 'Content-Type: application/json' \
  -d '{
    "company": {
      "fullName": "ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ \"ТЕСТ\"",
      "shortName": "ТОВ \"ТЕСТ\"",
      "fullNameEN": "TEST LLC",
      "shortNameEN": "TEST LLC",
      "type": "COMPANY",
      "code": "00000000",
      "ipn": null,
      "country": "UA",
      "state": "м. Київ",
      "locality": "Київ",
      "street": "вул. Тестова, 1",
      "ceoName": "Іваненко Іван Іванович"
    },
    "info": {
      "fullName": "Іваненко Іван Іванович",
      "ipn": "0000000000",
      "phone": "380671234567",
      "email": "ivanenko@example.com",
      "organizationUnit": "Адміністрація",
      "position": "Директор"
    }
  }'
```

##### **Помилки**

<table id="bkmrk-type-%D0%9E%D0%BF%D0%B8%D1%81-access_den" style="width: 99.5238%;"><thead data-pos="946"><tr data-pos="946"><th data-pos="947" style="width: 24.3836%;">`type`</th><th data-pos="956" style="width: 75.5893%;">Опис</th></tr></thead><tbody data-pos="974"><tr data-pos="974"><td data-pos="975" style="width: 24.3836%;">`access_denied`</td><td data-pos="993" style="width: 75.5893%;">Невірний `x-system-id` або доступ за IP заборонений.</td></tr><tr data-pos="1049"><td data-pos="1050" style="width: 24.3836%;">`empty_body`</td><td data-pos="1065" style="width: 75.5893%;">Тіло запиту порожнє.</td></tr><tr data-pos="1089"><td data-pos="1090" style="width: 24.3836%;">`invalid_body`</td><td data-pos="1107" style="width: 75.5893%;">Некоректний JSON або відсутні обовʼязкові поля.</td></tr><tr data-pos="1158"><td data-pos="1159" style="width: 24.3836%;">`company_already_active`</td><td data-pos="1186" style="width: 75.5893%;">Компанія з таким кодом вже активна, але не привʼязана до цієї зовнішньої системи.</td></tr><tr data-pos="1271"><td data-pos="1272" style="width: 24.3836%;">`unknown_company`</td><td data-pos="1292" style="width: 75.5893%;">Компанію не знайдено в публічних реєстрах, але не коректний ІПН/РНОКПП</td></tr><tr data-pos="1366"><td data-pos="1367" style="width: 24.3836%;">`wrong_ipn`</td><td data-pos="1381" style="width: 75.5893%;">Користувач з таким телефоном вже існує, але має інший ІПН/РНОКПП.</td></tr><tr data-pos="1450"><td data-pos="1451" style="width: 24.3836%;">`offline_exists`</td><td data-pos="1470" style="width: 75.5893%;">Користувач з таким телефоном вже існує з offline-ідентифікацією.</td></tr></tbody></table>