# Створити чернетку ключа для співробітника 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>