# Робота з API порталу EDIN ID [Колекцію Postman](https://wiki-v2.edin.ua/attachments/94) можна скачати в сторінці ["Перелік методів АРІ"](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/perelik-metodiv-api-po-roboti-z-portalom-edin-id) # Перелік методів API по роботі з порталом EDIN ID

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

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

##### **Авторизація** Кожен запит має містити HTTP header:

Header	Обовʼязковий	Опис
`x-system-id`	так	Токен/ідентифікатор зовнішньої системи. Саме цей header використовується для авторизації.

Приклад: ``` curl -X GET 'https://host/api/external/company?...' \ -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' ``` ##### **Отримання публічного ключа для шифрування паролів** Усі секретні значення, які передаються в API, мають бути зашифровані на актуальний публічний RSA-ключ сервера. Це стосується таких полів:

Поле	Що передавати
[Метод 9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft): `info.caPassPhrase`	`base64(RSA-encrypt(publicKey, caPassPhraseBytes))`
[Метод 9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft): `info.pkPassword`	`base64(RSA-encrypt(publicKey, pkPasswordBytes))`
[Метод 11](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-spivrobitnika-post-apiexternalcompanyemployeestatus): `adminKeyPassword`	`base64(RSA-encrypt(publicKey, adminKeyPasswordBytes))`
[Підписати хеш ключем співробітника компанії](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/pidpisati-kliucem-spivrobitnika-kompaniyi-post-apiexternalcompanysign): requestbody.password	`base64(RSA-encrypt(publicKey, password))`
[Підписати файл ключем співробітника компанії](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/pidpisati-fail-kliucem-spivrobitnika-kompaniyi-post-apiexternalcompanysignfile): params.password	`base64(RSA-encrypt(publicKey, caPassPhraseBytes))`

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

1	Отримати і зберегти публічний ключ	[GET /api/external/key](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-i-zberegti-publicnii-kliuc-get-apiexternalkey)
2	Підписати хеш ключем співробітника компанії	[POST /api/external/company/sign](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/pidpisati-kliucem-spivrobitnika-kompaniyi-post-apiexternalcompanysign "Підписати хеш ключем співробітника компанії POST /api/external/company/sign")
3	Підписати файл ключем співробітника компанії	[POST /api/external/company/sign/file](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/pidpisati-fail-kliucem-spivrobitnika-kompaniyi-post-apiexternalcompanysignfile "Підписати файл ключем співробітника компанії POST /api/external/company/sign/file")
4	Верифікувати підпис на файлі	[POST /api/external/company/sign/file/verify](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/verifikuvati-pidpis-na-faili-post-apiexternalcompanysignfileverify)
5	Отримати інформацію про сертифікат	[GET /api/external/company/key/certificate](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-sertifikat-get-apiexternalcompanykeycertificate)

[Колекція Postman](https://wiki-v2.edin.ua/attachments/94)

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

1	Отримати інформацію про компанію	[GET /api/external/company](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-kompaniiu-get-apiexternalcompany)
2	Отримати інформацію про співробітника	[GET /api/external/company/employee](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-spivrobitnika-get-apiexternalcompanyemployee "Підписати хеш ключем співробітника компанії POST /api/external/company/sign")
3	Пошук ключів співробітника	[POST /api/external/company/employee/pkeys/search](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/posuk-kliuciv-spivrobitnika-post-apiexternalcompanyemployeepkeyssearch "Підписати файл ключем співробітника компанії POST /api/external/company/sign/file")
4	Пошук співробітників компанії	[POST /api/external/company/employees/search](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/posuk-spivrobitnikiv-kompaniyi-post-apiexternalcompanyemployeessearch)
5	Пошук ключів компанії	[POST /api/external/company/pkeys/search](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/posuk-kliuciv-kompaniyi-post-apiexternalcompanypkeyssearch)
6	Отримати інформацію про ключ	[GET /api/external/company/pkey](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-kliuc-get-apiexternalcompanypkey)
7.1	Отримати документ компанії	[GET /api/external/company/form](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimannia-dokumenta-kompaniyi-get-apiexternalcompanyform)
7.2	Отримати ідентифікацію співробітника	[GET /api/external/company/employee/identification](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-identifikaciiu-spivrobitnika-get-apiexternalcompanyemployeeidentification)
7.3	Отримати документ ключа	[GET /api/external/company/pkey/form](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-dokument-kliuca-get-apiexternalcompanypkeyform)
8	Додати співробітника	[POST /api/external/company/employee](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/dodati-spivrobitnika-post-apiexternalcompanyemployee)
9.1	Створити чернетку ключа	[POST /api/external/company/employee/pkey/generate/draft](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft)
9.2	Згенерувати PDF-форму для адміністратора компанії	[PATCH /api/external/company/employee/pkey/generate/draft](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft)
9.3	Передати підписи PDF і активувати ключ	[POST /api/external/company/employee/pkey/activation](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/peredati-pidpisi-pdf-i-aktivuvati-kliuc-post-apiexternalcompanyemployeepkeyactivation)
10	Змінити статус ключа	[POST /api/external/company/pkey/status](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-kliuca-post-apiexternalcompanypkeystatus)
11	Змінити статус співробітника	[POST /api/external/company/employee/status](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-spivrobitnika-post-apiexternalcompanyemployeestatus)
12	Створити компанію	[POST /api/external/company/create](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvorennia-kompaniyi-post-apiexternalcompanycreate)

**Створення ключа складається з трьох запитів:** 1. [Створити чернетку ключа та отримати PDF для підпису співробітником](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft). 2. [Згенерувати PDF для підпису адміністратором компанії](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft). 3. [Передати detached-підписи всіх PDF і активувати ключ або передати його на активацію КНЕДП](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/peredati-pidpisi-pdf-i-aktivuvati-kliuc-post-apiexternalcompanyemployeepkeyactivation). **Рекомендований сценарій створення та активації ключа:** 1. Перевірити компанію методом [1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-kompaniiu-get-apiexternalcompany). 2. Якщо співробітника ще немає – створити його методом [8](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/dodati-spivrobitnika-post-apiexternalcompanyemployee). 3. Перевірити співробітника методом [2](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-informaciiu-pro-spivrobitnika-get-apiexternalcompanyemployee). 4. Викликати метод [9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft) і отримати `pKey.uuid` та employee PDF-форми. 5. Співробітник підписує PDF-форми з відповіді [9.1](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/stvoriti-cernetku-kliuca-dlia-spivrobitnika-post-apiexternalcompanyemployeepkeygeneratedraft) detached-підписом. 6. Викликати метод [9.2](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft) з `pKeyUuid` та `adminIpn` і отримати admin PDF-форми. 7. Адміністратор/суперадміністратор підписує PDF-форми з відповіді [9.2](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zgeneruvati-pdf-formu-dlia-administratora-kompaniyi-patch-apiexternalcompanyemployeepkeygeneratedraft) detached-підписом. 8. Викликати метод [9.3](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/peredati-pidpisi-pdf-i-aktivuvati-kliuc-post-apiexternalcompanyemployeepkeyactivation), передавши `keyUuid`, `activate` і map підписів за всіма отриманими `formType`. 9. Отримати оновлений `ESSPrivateKey` зі статусом `ACTIVATED` або `COMPANY_ADMIN_APPROVED`. # Шифрування пароля за допомогою відкритого ключа RSA ### Приклад для Postman (js) #### Функції для шифрування ```javascript /** * Encrypt data with RSA public key * @param publicKey - get from server * @param password - user key password */ utils = { rsaEncrypt: async function(publicKey, password) { const cryptoKey = await crypto.subtle.importKey("spki", publicKey, { name: "RSA-OAEP", hash: "SHA-256" }, true, ["encrypt"]); const encodedText = new TextEncoder().encode(password); const encrypted = await crypto.subtle.encrypt({name: "RSA-OAEP"}, cryptoKey, encodedText); // return toBase64(encrypted); } } function toBase64(buffer) { const bytes = new Uint8Array(buffer); let binary = ''; for (let i = 0; i < bytes.byteLength; i++) { binary += String.fromCharCode(bytes[i]); } return btoa(binary); } ``` #### Шифрування пароля ```javascript const encrypted = await utils.rsaEncrypt(Uint8Array.from(publicKey), password)); ``` де, - publicKey - публічний ключ, отриманий методом [GET /api/external/key](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/otrimati-i-zberegti-publicnii-kliuc-get-apiexternalkey) - password - пароль від ключа ### Приклад Java ```java import java.nio.charset.StandardCharsets; import java.security.KeyFactory; import java.security.PublicKey; import java.security.spec.MGF1ParameterSpec; import java.security.spec.X509EncodedKeySpec; import java.util.Base64; import javax.crypto.Cipher; import javax.crypto.spec.OAEPParameterSpec; import javax.crypto.spec.PSource; String pem = """ -----BEGIN PUBLIC KEY----- MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJB... -----END PUBLIC KEY----- """; String body = pem .replace("-----BEGIN PUBLIC KEY-----", "") .replace("-----END PUBLIC KEY-----", "") .replaceAll("\\s", ""); byte[] der = Base64.getDecoder().decode(body); PublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(der)); OAEPParameterSpec oaepParams = new OAEPParameterSpec( "SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT ); Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPPadding"); cipher.init(Cipher.ENCRYPT_MODE, publicKey, oaepParams); byte[] encrypted = cipher.doFinal("my-secret-password".getBytes(StandardCharsets.UTF_8)); String encryptedBase64 = Base64.getEncoder().encodeToString(encrypted); ``` ### Приклад Node.js ```javascript import crypto from "node:crypto"; const publicKeyPem = `-----BEGIN PUBLIC KEY----- MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJB... -----END PUBLIC KEY-----`; const encrypted = crypto.publicEncrypt( { key: publicKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" }, Buffer.from("my-secret-password", "utf8") ); const encryptedBase64 = encrypted.toString("base64"); ``` ### Як шифрувати? 1. Отримати публічний ключ через `/api/external/key?type=pem`. 2. Імпортувати public key у crypto-бібліотеку як RSA public key. 3. Зашифрувати plaintext пароль bytes. 4. Результат RSA encryption закодувати в base64. 5. Передати base64 string у відповідне поле запиту. ```text plaintext password -> UTF-8 bytes -> RSA encrypt with server public key -> base64 -> JSON field ```

алгоритм шифрування має відповідати вимогам API: `RSA/ECB/OAEPPadding` з `OAEP SHA-256` і `MGF1 SHA-256`; - не використовуйте `RSA_PKCS1_PADDING` / `RSA/ECB/PKCS1Padding` — сервер не зможе розшифрувати такі дані; - RSA OAEP має обмеження на довжину plaintext, яке залежить від розміру ключа; передавайте короткі секрети/паролі, а не великі JSON/файли; - публічний ключ має TTL, тому його треба оновлювати після `expiredAt` / `x-key-ttl`; - не кешуйте ключ назавжди; - якщо сервер повертає `decrypt_error` для `caPassPhrase` або `pkPassword`, найчастіші причини: - використаний застарілий public key; - зашифровано не тим padding/OAEP hash; - у JSON переданий не base64 від encrypted bytes; - plaintext був зашифрований іншим ключем.

# Помилки при роботі з API Помилки повертаються у JSON без envelope: ```json { "type": "employee_not_found" } ``` ##### **Загальні помилки**

Код відповіді	Опис
403	Помилка авторизації зовнішньої системи або підключення зовнішньої системи відбувається з недоступних IP-адрес або компанія не привʼязана до зовнішньої системи..
400	Бізнес/валідаційні помилки: не знайдено співробітника, ключ, документ, неправильний статус тощо.
413	Перевищено допустимий розмір файлу, якщо для конкретного upload-методу увімкнений ліміт.

Типові помилки доступу: ```json {"type":"access_denied"} ``` ```json {"type":"company_access_denied"} ``` ```json {"type":"company_wrong_status","status":"DRAFT"} ```

##### **Помилки підписання хешів**

Код відповіді	Опис
406	Ключ не знайдено або неправильний пароль
413	Більше 100 хешів для підписання
422	Помилка в процесі підписання
426	Неможливо дешифрувати пароль до ключа. Спробувати оновити публічний ключ для шифрування та повторити операцію

##### **Помилки підписання файлів**

Код відповіді	Опис
406	Ключ не знайдено або неправильний пароль
412	Атрибути ("key" або "password") або файл неправильно заповнені або відсутні у запиті
413	Розмір файла для підпису більше 1Мб
422	Помилка в процесі підписання
426	Неможливо дешифрувати пароль до ключа. Спробувати оновити публічний ключ для шифрування та повторити операцію

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

URL
Метод запиту	GET
URL запиту	/api/external/key
Authorization
Auth type	API key
Key / Value	x-system-id / токен, отриманий при підключенні
Params
type	тип відповіді JSON\|PEM\|XML (якщо параметр не передавати за замовченням буде JSON)

##### **RESPONSE** В тілі **відповіді** повертається ключ у вказаному форматі: - якщо type = JSON – повертається масив байт - якщо type = PEM – повертається PEM-файл у вигляді ```json -----BEGIN PUBLIC KEY----- MIGfMA0GCSqGSIb3DQEBAQ9QIDAQAB -----END PUBLIC KEY----- ``` - якщо type = XML – повертається XML-файл у вигляді ```markdown wxWy8iReusbmiadsULVLSD36+l5k6cZ0= AQAB ``` **Для type in (PEM, XML) в reponse-header** передається параметр `x-key-ttl`, в якому передається термін життя відкритого ключа. # Підписати ключем співробітника компанії POST /api/external/company/sign ##### **REQUEST**

URL
Метод запиту	POST
URL запиту	/api/external/company/sign
Headers
Authorization	x-system-id - токен, отриманий при підключенні
Content-Type	aplication/json
Request body	{ "key": "{{id ключа}}", "password": "{{зашифрований пароль від ключа}}", "algorithm": "DSTU4145_GOST34311", "DSTU4145_DSTU7564", "ECDSA", "isRaw": "true/false. В разі встановлення true повертає "сирий підпис", при цьому signtype ігноруються. "hashes": [ {"hash": "{{хеш документа, що підписується}}", "description": "опис документа, що підписується"} ] "SignType": "{{CADES_BES (за замовчуванням), CADES_T, CADES_C, CADES_X_LONG, CADES_X_LONG_TRUSTED;}}", }

##### **RESPONSE** В тілі **відповіді** повертається масив підписів. Приклад: ``` { "fFNkFPush1kn988zLJoXBoSYilWMI408xxQ7Xs69Ww=": "MIILPgYJKoZIhvcNAQcC..." } ``` # Підписати файл ключем співробітника компанії POST /api/external/company/sign/file ##### **REQUEST**

URL
Метод запиту	POST
URL запиту	/api/external/company/sign/file
Authorization
Auth type	API key
Key / Value	x-system-id / токен, отриманий при підключенні
Headers
Content-Type	[multipart/form-data](https://tools.ietf.org/html/rfc7578)
Request body	Параметри тіла запиту: - 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)
Params	- key – ідентифікатор ключа. - type – тип підписання, може приймати значення: - append – додає підпис до переданого файлу. ВАЖЛИВО! Якщо файл вже був підписаний, то підпис додається до існуючого, а не підписується разом з існуючим підписом. - sign - підписує контент, використовується за замовчуванням. - result – формат підписання (дані й підпис в одному файлі, дані й підпис в окремих файлах), може приймати значення: - enveloped – у відповідь надійде файл з підписом - detached – у відповідь надійде тільки підпис - inputFormat – формат вхідних даних для підписання, може приймати значення: - file – файл в бінарному вигляді - base64 – файл у вигляді base64 рядка - outputFormat – формат вихідних (результуючих) даних після підписання, може приймати значення: - file – файл в бінарному вигляді - base64 – файл у вигляді base64 рядка - signType – тип підпису, приймає значення CADES\_BES, CADES\_T, CADES\_C, CADES\_X\_LONG, CADES\_X\_LONG\_TRUSTED. Якщо не передано, то за замовченням підставляється CADES\_BES - algorithm (enum) - алгоритм формату підписання: - DSTU4145\_GOST34311, - DSTU4145\_DSTU7564, - ECDSA

##### **RESPONSE** В тілі **відповіді** повертаються код 200 та результат підписання відповідно до параметрів **result** та **outputFormat.** # Отримати інформацію про компанію GET /api/external/company **REQUEST**

URL
Метод запиту	GET
URL запиту	/api/external/company
URL параметри	companyCode (обов’язково) - код Компанії;
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

**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' ``` **Помилки**

HTTP	`type`	Опис
403	`access_denied`	Невалідний `x-system-id` або IP не дозволений.
403	`company_access_denied`	Компанія не знайдена або не привʼязана до зовнішньої системи.

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

URL
Метод запиту	GET
URL запиту	/api/external/company/employee
URL параметри	companyCode (обов’язково) - код Компанії; employeeIpn (обов’язково) - ІПН/РНОКПП співробітника.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

##### **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' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`employee_not_found`	Співробітник з таким `employeeIpn` не знайдений у цій компанії.
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/employee/pkeys/search
URL параметри	companyCode (обов’язково) - код Компанії; employeeIpn (обов’язково) - ІПН/РНОКПП співробітника.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
JSON Body	В тілі запиту методу передається об’єкт [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 } } ```

##### **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} }' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`employee_not_found`	Співробітник не знайдений.
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/employees/search
URL параметри	companyCode (обов’язково) - код Компанії;
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
JSON Body	В тілі запиту методу передається об’єкт [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 } } ```

##### **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} }' ``` ##### **Помилки**

HTTP	`type`	Опис
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/pkeys/search
URL параметри	companyCode (обов’язково) - код Компанії;
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
JSON Body	В тілі запиту методу передається об’єкт [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 } } ```

##### **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} }' ``` ##### **Помилки**

HTTP	`type`	Опис
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	GET
URL запиту	/api/external/company/pkey
URL параметри	companyCode (обов’язково) - код Компанії; key (обов’язково) - код ключа.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

##### **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' ``` ##### ##### **Помилки**

HTTP	`type`	Опис
400	`pkey_not_found`	Ключ не знайдений або не належить цій company.
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	GET
URL запиту	/api/external/company/form
URL параметри	companyCode (обов’язково) - код Компанії; formType (обов’язково) - Enum name з `ESSRegFormType`, наприклад, `OFFER_AGREEMENT_MANAGER`. format (опційно) - `binary` або `base64`. Default: `binary`.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

##### **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..." } ```

Поле	Тип	Опис
`formType`	string	Enum name документа.
`fileName`	string	Імʼя файлу.
`contentType`	string	Завжди `application/pdf`.
`contentBase64`	string	PDF у base64.

##### **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' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`unknown_form_type`	Невідомий `formType`.
400	`form_not_found`	Документ не знайдений.
400	`unknown_format`	`format` не `binary` і не `base64`.
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	GET
URL запиту	/api/external/company/employee/identification
URL параметри	companyCode (обов’язково) - код Компанії; employeeIpn (обов’язково) - ІПН/РНОКПП співробітника.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

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

Поле	Тип	Опис
`info`	object	Об'єкт [ESSUserIdentification.](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-essuseridentification)
`data`	string	Base64 підпису ідентифікації. Повертається лише якщо `info.complete == YES`.

Якщо ідентифікація не завершена, поле `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' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`employee_not_found`	Співробітник не знайдений.
400	`employee_identification_not_found`	Ідентифікація співробітника не знайдена.
400	`employee_identification_sign_not_found`	Ідентифікація завершена, але файл підпису не знайдено.
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	GET
URL запиту	/api/external/company/pkey/form
URL параметри	companyCode (обов’язково) - код Компанії; employeeIpn (обов’язково) - ІПН/РНОКПП співробітника. key (обов’язково) - UUID ключа. formType (обов’язково) - Enum name з `ESSRegFormType`, наприклад, `PK_FORM`. format (опційно) - `binary` або `base64`. Default: `binary`.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

##### **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 ``` ##### **Помилки**

HTTP	`type`	Опис
400	`unknown_form_type`	Невідомий `formType`.
400	`form_not_found`	Документ ключа не знайдений.
400	`unknown_format`	`format` не `binary` і не `base64`.
403	`company_access_denied`	Немає доступу до company.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/form
URL параметри	companyCode (обов’язково) - код Компанії.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	multipart/form-data
REQUEST
REQUEST Body	info (обов’язково) JSON attr - дані для додавання співробітника; identification (обов’язково) file - підписаний контейнер ідентифікації співробітника. Всі персональні дані ідентифікації беруться з підпису/сертифіката у file `identification`, а не з JSON `info`.

`info`: ```json { "phone": "380501112233", "email": "employee@example.com", "role": "USER", "identificationType": "SIGN" } ``` **Опис полів:**

Поле	Тип	Обовʼязкове	Опис
`phone`	string	так	Телефон у форматі `380XXXXXXXXX`.
`email`	string	так	Email співробітника.
`role`	enum	так	`USER`, `ADMIN`.
`identificationType`	enum	так	`SIGN`, `DIIA_INTERNAL_PASSPORT` або `DIIA_FOREIGN_PASSPORT`.

##### **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' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`invalid_info`	Невалідний або неповний `info`.
400	`invalid_phone`	`phone` не відповідає формату `380XXXXXXXXX`.
400	`identification_file_not_found`	Не переданий file `identification`.
400	`invalid_signature`	Неможливо перевірити підпис ідентифікації.
400	`unsupported_role`	Непідтримувана роль.
400	`unsupported_identification_type`	Непідтримуваний тип ідентифікації.
400	`wrong_ipn`	ІПН існуючого користувача не збігається з ІПН у підписі.
403	`company_access_denied`	Немає доступу до company.
403	`company_wrong_status`	Компанія не `ACTIVE`.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/employee/pkey/generate/draft
URL параметри	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`
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	multipart/form-data
REQUEST
REQUEST Body	info (обов’язково) JSON attr - параметри CA user і ключа; requests (обов’язково, тільки для `store=file`) JSON attr - p10-запити у форматі `PKCS #10`, створені зовнішньою системою. Всі персональні дані ідентифікації беруться з підпису/сертифіката у file `identification`, а не з JSON `info`.

`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`:

Поле	Тип	Обовʼязкове	Опис
`pkName`	string	так	Назва ключа.
`pkType`	enum	так	`UA` або `ECDSA`.
`pkStoreType`	enum	так	`HSM` або `FILE`.
[`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)	string	для `store=cloud`	Base64 від RSA-encrypted bytes пароля ключа. Шифрувати актуальним public key з `/api/external/key`.
`pkIsStamp`	boolean	так	`true` — печатка, `false` — особистий ключ співробітника.
`emplTitle`	string/null	ні	Посада для CA user.
`emplOrgUnit`	string/null	ні	Підрозділ для CA user.
[`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)	string	так	Base64 від RSA-encrypted bytes секретної фрази CA user. Шифрувати актуальним public key з `/api/external/key`.
`certType`	enum	так	`SIGN_ONLY` або `SIGN_AND_ENCRYPT`.
`certValidity`	enum	так	`ONE` або `TWO`.

`requests` для `store=file`: ```json { "ecdsa": "base64 PKCS #10 request", "signature": "base64 PKCS #10 request", "encryption": "base64 PKCS #10 request" } ``` **Опис полів** `requests` :

Поле	Тип	Коли потрібне	Опис
`ecdsa`	string	`pkType=ECDSA`	Base64 `PKCS #10` request для ECDSA сертифіката.
`signature`	string	`pkType=UA`	Base64 `PKCS #10` request для сертифіката підпису.
`encryption`	string	`pkType=UA` і `certType=SIGN_AND_ENCRYPT`	Base64 `PKCS #10` request для сертифіката шифрування.

##### **RESPONSE**

В тілі **відповіді** передається статус 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`. **Опис полів відповіді:**

Поле	Тип	Опис
`pKey`	object	Обʼєкт `ESSPrivateKey`, поля описані в розділі 2.3. Використовуйте `pKey.uuid` у методах 9.2 і 9.3.
`forms`	object\[\]	PDF-документи, які потрібно підписати співробітником.
`forms[].type`	enum	Тип форми.
`forms[].pdf`	string	PDF content у base64.
`forms[].hash`	string/null	Hash PDF для контролю цілісності.

##### **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" }' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`invalid_store`	`store` не `cloud` і не `file`.
400	`employee_not_found`	Співробітник не знайдений.
400	`employee_not_active`	Співробітник не активний або не ідентифікований.
400	`company_not_found`	Не знайдено company для співробітника.
400	`decrypt_error`	Неможливо розшифрувати `caPassPhrase` або `pkPassword`.
400	`employee_identification_not_found`	Не знайдено підпис ідентифікації співробітника.
400	`request_not_found`	Для `store=file` не переданий потрібний p10-запит.
400	`pk_requests_not_found`	Після створення ключа не знайдені p10-запити.
403	`company_access_denied`	Немає доступу до company.
403	`company_wrong_status`	Компанія не `ACTIVE`.

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

Цей метод можна викликати повторно. У такому випадку admin-форми будуть перестворені, а попередні варіанти цих форм — перезаписані.

##### **REQUEST**

URL
Метод запиту	PATCH
URL запиту	/api/external/company/employee/pkey/generate/draft
URL параметри	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` компанії.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

##### **RESPONSE** В тілі відповіді передається статус 200. **JSON приклад відповіді:** ```json { "pKey": { "uuid": "019ec000-0000-7000-8000-000000000001", "status": "COMPANY_GENERATED" }, "forms": [ { "type": "AFFILIATION_CONFIRMATION", "pdf": "JVBERi0x...", "hash": "HASH_OF_PDF" } ] } ``` **Опис полів відповіді:**

Поле	Тип	Опис
`pKey`	object	Обʼєкт `ESSPrivateKey`, поля описані в розділі 2.3.
`forms`	object\[\]	PDF-документи, які потрібно підписати адміністратору/суперадміністратору.
`forms[].type`	enum	Тип форми: `AFFILIATION_CONFIRMATION` або `POWER_OF_ATTORNEY`.
`forms[].pdf`	string	PDF content у base64.
`forms[].hash`	string/null	Hash PDF для контролю цілісності.

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

##### **CURL** ``` curl -X PATCH 'https://host/api/external/company/employee/pkey/generate/draft?...' -H 'x-system-id: 019eb581-307b-7562-8a1f-20227511e898' ``` ##### **Помилки**

HTTP	`type`	Опис
400	`invalid_pkey_uuid`	`pKeyUuid` має неправильний UUID-формат.
400	`pkey_not_found`	Ключ не знайдений або не належить company.
400	`pkey_wrong_status`	Ключ не у статусі `COMPANY_GENERATED`.
400	`employee_not_found`	Співробітник-власник ключа не знайдений.
400	`employee_not_active`	Співробітник-власник ключа не активний або не ідентифікований.
400	`admin_not_found`	Адміністратор не знайдений.
400	`admin_not_active`	Адміністратор не активний або не ідентифікований.
400	`admin_wrong_role`	Переданий користувач не має ролі адміністратора/суперадміністратора.
400	`admin_must_be_super_admin`	Для цього ключа потрібен підпис суперадміністратора.
403	`company_access_denied`	Немає доступу до company.
403	`company_wrong_status`	Компанія не `ACTIVE`.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/employee/pkey/activation
URL параметри	companyCode (обов’язково) - код Компанії; employeeIpn (обов’язково) - ІПН/РНОКПП співробітника.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
JSON Body	Приклад запиту: ```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" ] } } ```

**Опис полів запиту:**

Поле	Тип	Обовʼязкове	Опис
`keyUuid`	string UUID	так	UUID ключа з відповіді 9.1: `pKey.uuid`.
`activate`	boolean	так	`true` — одразу активувати ключ; `false` — передати ключ на активацію КНЕДП.
`forms`	object/map	так	Map підписів для PDF-документів, отриманих у 9.1 та 9.2.
`forms.{formType}`	string\[\]	так для кожної PDF-форми	Масив detached-підписів PDF у base64. Ключ map — enum name `ESSRegFormType`.

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

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

`formType`	Хто підписує
`PK_FORM`	співробітник + admin/super\_admin
`PK_APPENDIX`	співробітник + super\_admin
`AFFILIATION_CONFIRMATION`	admin/super\_admin
`POWER_OF_ATTORNEY`	super\_admin

##### **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" ] } }' ``` ##### **Помилки**

HTTP	`type`	Додаткові поля	Опис
400	`key_uuid_not_found`	—	Не переданий `keyUuid`.
400	`employee_not_found`	—	Співробітник не знайдений.
400	`employee_not_active`	—	Співробітник не активний або не ідентифікований.
400	`pkey_not_found`	—	Ключ не знайдений або не належить company/employee.
400	`pkey_wrong_status`	`status`	Ключ не у статусі `COMPANY_GENERATED`.
400	`forms_not_found`	—	Не передані підписи або для ключа немає PDF-форм.
400	`unexpected_form`	`formType`	Переданий підпис для форми, яка не була згенерована для ключа.
400	`admin_not_found`	—	Адміністратор не знайдений.
400	`admin_not_active`	—	Адміністратор не активний або не ідентифікований.
400	`admin_wrong_role`	—	Адміністратор не має ролі admin/super\_admin.
400	`admin_must_be_super_admin`	—	Для однієї з форм потрібен super\_admin.
400	`form_sign_not_found`	`formType`	Не переданий підпис для однієї зі збережених форм.
400	`unsupported_form`	`formType`	Непідтримуваний тип форми для цього запиту.
400	`wrong_sign_count`	`formType`	Кількість підписів для форми не відповідає очікуваній.
400	`duplicate_signature`	`formType`	Для форми передано однаковий підпис більше одного разу.
400	`invalid_signature`	`formType`	Підпис не проходить перевірку для PDF.
400	`wrong_signer`	`formType`	Підписант не відповідає очікуваному підписанту форми.
403	`company_access_denied`	—	Немає доступу до company.
403	`company_wrong_status`	`status`	Компанія не `ACTIVE`.

# Змінити статус ключа POST /api/external/company/pkey/status Метод змінює статус ключа компанії/співробітника та одразу формує, підписує і зберігає PDF-підтвердження зміни статусу. Клієнт не підписує PDF самостійно, а передає UUID ключа адміністратора/суперадміністратора та зашифрований пароль до нього. Після чого API: 1. формує PDF-форми зміни статусу; 2. підписує їх ключем адміністратора/суперадміністратора; 3. зберігає підписані PDF як підтвердження зміни статусу; 4. змінює статус ключа у системі; 5. передає зміну статусу до центру сертифікації; 6. повертає масив підписаних PDF. ##### **REQUEST**

URL
Метод запиту	POST
URL запиту	/api/external/company/pkey/status
URL параметри	companyCode (обов’язково) - код Компанії;
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
JSON Body	JSON приклад запиту: ```json { "keyUuid": "019ec000-0000-7000-8000-000000000001", "action": "hold", "adminKeyUuid": "019ec000-0000-7000-8000-000000000099", "adminKeyPassword": "BASE64_RSA_ENCRYPTED_ADMIN_KEY_PASSWORD", "reason": "Компрометація ключа" } ```

**Опис полів запиту:**

Поле	Тип	Обовʼязкове	Опис
`keyUuid`	string UUID	так	UUID ключа, статус якого треба змінити.
`action`	enum	так	Дія: - `hold` - призупинити активний ключ. - `unhold` - відновити ключ зі статусу `HOLD`. - `revoke` - скасувати/відкликати ключ.
`adminKeyUuid`	string UUID	так	UUID ключа адміністратора/суперадміністратора цієї компанії.
`adminKeyPassword`	string	так	Base64 від RSA-encrypted bytes пароля ключа адміністратора/суперадміністратора. Шифрувати public key з `/api/external/key`; див. розділ 1.4.
`reason`	string	так	Причина зміни статусу. Мінімум 4 символи після trim. Потрапляє у PDF і в історію статусів.

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": "Компрометація ключа" }' ``` ##### **Помилки**

HTTP	`type`	Додаткові поля	Опис
400	`decrypt_error`	`field=adminKeyPassword`	Не вдалося розшифрувати пароль ключа адміністратора/суперадміністратора.
400	`pkey_not_found`	—	Ключ `keyUuid` не знайдений або не належить company.
400	`employee_not_found`	—	Власник ключа не знайдений як співробітник company.
400	`admin_pkey_not_found`	—	Ключ адміністратора/суперадміністратора не знайдений або не належить company.
400	`admin_required`	—	Власник `adminKeyUuid` не має ролі `ADMIN`/`SUPER_ADMIN`.
400	`invalid_password`	—	Пароль ключа адміністратора/суперадміністратора неправильний.
400	`invalid_reason`	—	`reason` порожній або коротший за 4 символи після trim.
400	`unsupported_action`	—	У `action` передано не `hold`, `unhold` або `revoke`.
400	`pkey_wrong_status`	—	Перехід статусу не дозволений для поточного стану ключа.
403	`company_access_denied`	—	Немає доступу до company.
403	`company_wrong_status`	`status`	Компанія не `ACTIVE`.

# Змінити статус співробітника POST /api/external/company/employee/status Метод змінює статус співробітника компанії. Якщо дія вимагає каскадної зміни статусів ключів співробітника, API формує PDF-документи зміни статусу ключів, підписує їх ключем адміністратора/суперадміністратора, зберігає підтвердження і змінює статуси ключів. Клієнт не підписує PDF самостійно. Клієнт передає UUID ключа адміністратора/суперадміністратора та зашифрований пароль до нього. ##### **REQUEST**

URL
Метод запиту	POST
URL запиту	/api/external/company/employee/status
URL параметри	companyCode (обов’язково) - код Компанії; employeeIpn (обов’язково) - ІПН/РНОКПП співробітника.
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
JSON Body	JSON приклад запиту: ``` { "action": "BLOCKED", "adminKeyUuid": "019ec000-0000-7000-8000-000000000099", "adminKeyPassword": "BASE64_RSA_ENCRYPTED_ADMIN_KEY_PASSWORD", "reason": "Тимчасове блокування співробітника" } ```

**Опис полів запиту:**

Поле	Тип	Обовʼязкове	Опис
`action`	enum	так	Новий статус/дія для співробітника: `ACTIVE`, `BLOCKED`, `FIRED`, `REHIRED`.
`adminKeyUuid`	string UUID	так	UUID ключа адміністратора/суперадміністратора цієї компанії.
`adminKeyPassword`	string	так	Base64 від RSA-encrypted bytes пароля ключа адміністратора/суперадміністратора. Шифрувати public key з `/api/external/key`.
`reason`	string	так	Причина зміни статусу. Мінімум 4 символи після trim. Потрапляє у PDF-документи зміни статусу ключів і в історію статусів співробітника.

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

Поточний статус співробітника	Дозволені `action`
`ACTIVE`	`BLOCKED`, `FIRED`
`REHIRED`	`BLOCKED`, `FIRED`
`BLOCKED`	`ACTIVE`, `FIRED`
`FIRED`	`REHIRED`

Якщо передати недозволений перехід, 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" ] } ``` **Опис полів відповіді:**

Поле	Тип	Опис
`employee`	object	Оновлений JSON-обʼєкт `ESSUser`. Поля описані в розділі 2.2.
`pdf`	string\[\]	Масив підписаних PDF-документів зміни статусу ключів у base64.

Для `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": "Тимчасове блокування співробітника" }' ``` ##### **Помилки**

HTTP	`type`	Додаткові поля	Опис
400	`employee_not_found`	—	Співробітник не знайдений.
400	`wrong_action`	—	Перехід статусу не дозволений.
400	`unsupported_action`	—	`action` не передано або не підтримується.
400	`invalid_reason`	—	`reason` порожній або коротший за 4 символи після trim.
400	`decrypt_error`	`field=adminKeyPassword`	Не вдалося розшифрувати пароль ключа адміністратора/суперадміністратора.
400	`admin_pkey_not_found`	—	Ключ адміністратора/суперадміністратора не знайдено або не належить company.
400	`admin_required`	—	Власник `adminKeyUuid` не має ролі `ADMIN`/`SUPER_ADMIN`.
400	`invalid_password`	—	Пароль ключа адміністратора/суперадміністратора неправильний.
400	`pkey_wrong_status`	—	Каскадна зміна статусу одного з ключів неможлива для поточного стану ключа.
403	`company_access_denied`	—	Немає доступу до company.
403	`company_wrong_status`	`status`	Компанія не `ACTIVE`.

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

URL
Метод запиту	POST
URL запиту	/api/external/company/sign/file/verify
URL параметри	format (enum) - формат передачі файлів (`binary` за замовчуванням або `base64`). type (enum) - тип підпису: - `enveloped` (за замовчуванням) - очікується рівно 1 файл. Якщо передано 0 або >1 файлу, метод повертає помилку 400. - `detached` - очікується мінімум 2 файли (1 оригінальний документ + 1 або більше файлів підпису `.p7s`). Якщо передано менше 2 файлів, метод повертає помилку 400. returnOriginal (boolean) - прапорець повернення оригінального файлу (false за замовчуванням або true).
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	multipart/form-data
REQUEST
JSON Body	У тілі запиту передається масив файлів (контент у форматі згідно з параметром `format`).

##### **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 ] } } ```

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

URL
Метод запиту	GET
URL запиту	/api/external/company/key/certificate
URL параметри	key (обов’язково) – uuid ключа; raw (не обовʼязково) – true/false (за замовченням false), якщо raw = true, то у відповіді буде сам сертифікат в base64 type (не обовʼязково) – тип сертифіката. Доступні значення (SIGNATURE, ENCRYPTION, RSA, ECDSA). За замовченням SIGNATURE
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json

##### **RESPONSE** У відповідь повертається об'єкт [EndUserCertificateInfoEx](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-endusercertificateinfoex) з інформацією про сертифікат або контент сертифіката в base64 (якщо raw = true) # Створення компанії POST /api/external/company/create Метод створює компанію у статусі `DRAFT`, з договором-офертою `OFFER`, створює чернетку ключа суперадміністратора та привʼязує компанію до зовнішньої системи. Якщо компанія з таким кодом вже привʼязана до цієї зовнішньої системи, метод не створює нову компанію, а повертає існуючий обʼєкт `ESSCompany`. Якщо компанія з таким кодом вже активна, але не привʼязана до цієї зовнішньої системи, метод повертає помилку `company_already_active`. ##### **REQUEST**

URL
Метод запиту	POST
URL запиту	/api/external/company/create
Authorization
Auth type	API key
Key / Value	x-system-id - токен, отриманий при підключенні
Headers
Content-Type	application/json
REQUEST
REQUEST Body	info - дані суперадміністратора компанії, для якого буде створено чернетку ключа. company - обʼєкт з даними про компанію [ESSCompany](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscompany)

**COMPANY:**

Поле	Формат	Тип ¹	Опис
`fullName`	string	M	Повна назва компанії/ФОП.
`shortName`	string	M	Скорочена назва компанії/ФОП.
`fullNameEN`	string/null	O	Повна назва англійською.
`shortNameEN`	string/null	O	Скорочена назва англійською.
`type`	enum	M	Тип компанії: `COMPANY` або `SELF_EMPLOYED`.
`code`	string	M	Для компанії — ЄДРПОУ, для ФОП — РНОКПП.
`ipn`	string/null	O	ІПН платника ПДВ, якщо є.
`country`	string/null	O	Країна.
`state`	string/null	O	Область/регіон.
`locality`	string/null	O	Населений пункт.
`street`	string/null	O	Адреса.
`ceoName`	string/null	O	ПІБ керівника.

---
1 - Під визначенням колонки **Тип поля** мається на увазі скорочене позначення:: - M (mandatory) — обов’язкові до заповнення поля; - O (optional) — необов’язкові (опціональні) до заповнення поля.

Поля договору у запиті передавати не потрібно. Сервер завжди створює компанію з:

Поле	Значення
`status`	`DRAFT`
`agreemType`	`OFFER`
`agreemNumber`	`null`
`agreemDate`	`0`

**INFO:**

Поле	Тип	Обовʼязкове	Опис
`fullName`	string	так	ПІБ суперадміністратора.
`ipn`	string	так	ІПН/РНОКПП суперадміністратора.
`phone`	string	так	Телефон у форматі `380XXXXXXXXX`.
`email`	string	так	Email суперадміністратора.
`organizationUnit`	string/null	ні	Підрозділ для даних ключа.
`position`	string/null	ні	Посада для даних ключа.

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

```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": "Директор" } } ```

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

##### **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": "Директор" } }' ``` ##### **Помилки**

`type`	Опис
`access_denied`	Невірний `x-system-id` або доступ за IP заборонений.
`empty_body`	Тіло запиту порожнє.
`invalid_body`	Некоректний JSON або відсутні обовʼязкові поля.
`company_already_active`	Компанія з таким кодом вже активна, але не привʼязана до цієї зовнішньої системи.
`unknown_company`	Компанію не знайдено в публічних реєстрах, але не коректний ІПН/РНОКПП
`wrong_ipn`	Користувач з таким телефоном вже існує, але має інший ІПН/РНОКПП.
`offline_exists`	Користувач з таким телефоном вже існує з offline-ідентифікацією.

# Об'єкти API # Довідник enum значень ##### **`ESSRegFormType`** Для запитів на документи `formType` передається як enum name:

name	code	Опис	використання
`PK_FORM`	1	Заява на отримання КЕП	ключ
`OFFER_AGREEMENT_USER`	2	Договір-оферта користувача	компанія
`OFFER_AGREEMENT_MANAGER`	3	Договір-оферта керівника/УО	компанія
`POWER_OF_ATTORNEY`	4	Доручення	компанія
`AFFILIATION_CONFIRMATION`	5	Приналежність
`SIGNATORY_CONFIRMATION`	6	Підтвердження підписанта
`CA_CONFIRMATION`	7	Підтвердження КНЕДП
`INDIVIDUAL_AGREEMENT`	8	Індивідуальний договір
`PK_APPENDIX`	9	Додаток до заяви
`USER_IDENTIFICATION`	10	Ідентифікація користувача
`COMPANY_CHARTER`	11	Статут компанії
`ACCEPT_CHARTER`	12	Підтвердження статуту компанії
`AGREEMENT_APPENDIX`	13	Додаток до договору
`DISAGREEMENT_PROTOCOL`	14	Протокол розбіжностей

У методі для [заміни статусу ключа](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/zminiti-status-kliuca-post-apiexternalcompanypkeystatus) підписи передаються у map `forms`, де ключ — це enum name, наприклад, `"PK_FORM"` або `"PK_APPENDIX"`. ##### **Інші поширені enum**

Enum	Приклади значень
`ESSCompanyUserType`	`USER`, `ADMIN`, `SUPER_ADMIN`, `DRAFT_ADMIN`
`ESSUserIdentificationType`	`SIGN`, `DIIA_INTERNAL_PASSPORT`, `DIIA_FOREIGN_PASSPORT`, `OFFLINE`, `UNKNOWN`
`ESSUserCompleteType`	`YES`, `NO`
`ESSUserCompanyStatus`	`ACTIVE`, `BLOCKED`, `FIRED`, `REHIRED`
`ESSPKType`	`UA`, `ECDSA`
`ESSPKStoreType`	`HSM`, `FILE`
`ESSPKStatus`	`COMPANY_GENERATED`, `ACTIVATED`, інші статуси ключа
`EUCreatePKType`	`SIGN_ONLY`, `SIGN_AND_ENCRYPT`
`ESSCertificateValidityYears`	`ONE`, `TWO`

# Об'єкт ESSCompany ##### **Опис параметрів об’єкта**

Поле	Тип	Опис
`id`	number	Внутрішній ідентифікатор компанії.
`fullName`	string/null	Повна назва українською.
`shortName`	string/null	Скорочена назва українською.
`fullNameEN`	string/null	Повна назва англійською.
`shortNameEN`	string/null	Скорочена назва англійською.
`type`	enum	Тип компанії, наприклад, `COMPANY` або `SELF_EMPLOYED`.
`code`	string	Код компанії/ФОП.
`ipn`	string/null	ІПН, якщо застосовується.
`status`	enum	Статус компанії. Частина write/action методів дозволена лише для `ACTIVE` компаній.
`country`	string/null	Країна.
`state`	string/null	Область/регіон.
`locality`	string/null	Населений пункт.
`street`	string/null	Адреса.
`ceoName`	string/null	ПІБ керівника.
`agreemType`	enum/null	Тип договору.
`agreemNumber`	string/null	Номер договору.
`agreemDate`	number	Дата договору, Unix timestamp у секундах.
`ECDSAStatus` або `ecdsaStatus`	enum	Готовність компанії до ECDSA залежно від EN-назв.
`role`	enum/null	Роль користувача в компанії, якщо company повернена в контексті співробітника.
`employeeStatus`	enum/null	Статус співробітника, якщо company повернена в контексті співробітника.
`employeeEmail`	string/null	Email співробітника в компанії, якщо доступний.

**JSON приклад:** ```json { "id": 123, "fullName": "ТОВ \"Тест\"", "shortName": "ТОВ \"Тест\"", "fullNameEN": "TEST LLC", "shortNameEN": "TEST LLC", "type": "COMPANY", "code": "25412361", "ipn": null, "status": "ACTIVE", "country": "UA", "state": "Київська", "locality": "Київ", "street": "вул. Тестова, 1", "ceoName": "Петренко Петро Петрович", "agreemType": "INDIVIDUAL", "agreemNumber": "123", "agreemDate": 1717200000, "role": null, "employeeStatus": null, "employeeEmail": null } ```

# Об'єкт ESSUser ##### **Опис параметрів об’єкта**

Поле	Формат	Опис
`id`	number	Внутрішній ідентифікатор користувача.
`login`	string	Логін/телефон користувача.
`email`	string/null	Email користувача.
`fullName`	string/null	ПІБ українською з ідентифікації.
`fullNameEN`	string/null	ПІБ англійською, якщо є.
`ipn`	string/null	РНОКПП/ІПН користувача.
`unzr`	string/null	УНЗР.
`registered` або `isRegistered`	boolean	Ознака, чи зареєстрований користувач.
`type`	enum	Тип ідентифікації: `SIGN`, `DIIA_INTERNAL_PASSPORT`, `DIIA_FOREIGN_PASSPORT`, `OFFLINE`, `UNKNOWN`.
`identified`	enum	`YES` або `NO`.
`mobile` або `isMobile`	boolean	Ознака mobile user.
`role`	enum/null	Роль у компанії: `USER`, `ADMIN`, `SUPER_ADMIN`, `DRAFT_ADMIN`.
`employeeStatus`	enum/null	Статус співробітника у компанії.
`employeeEmail`	string/null	Email співробітника у компанії.

**JSON приклад:** ```json { "id": 456, "login": "380501112233", "email": "employee@example.com", "fullName": "Іваненко Іван Іванович", "fullNameEN": "IVANENKO IVAN", "ipn": "3148615913", "unzr": "19900101-12345", "registered": false, "type": "SIGN", "identified": "YES", "mobile": false, "role": "USER", "employeeStatus": "ACTIVE", "employeeEmail": "employee@example.com" } ```

# Обект ESSPrivateKey ##### **Опис параметрів об’єкта**

Поле	Тип	Опис
`id`	number	Внутрішній ідентифікатор ключа.
`name`	string	Назва ключа.
`caUserId`	number	Внутрішній ID CA user.
`caUser`	object/null	Обʼєкт [ESSCAUser](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscauser).
`uuid`	string	Публічний ідентифікатор ключа. Використовувати як `key` або `keyUuid`.
`status`	enum	Статус ключа, наприклад, `COMPANY_GENERATED`, `ACTIVATED`.
`statusType`	enum	Додатковий тип статусу.
`storeType`	enum	Тип сховища: `HSM`, `FILE`.
`keyType`	enum	Тип ключа: `UA`, `ECDSA`.
`stamp` або `isStamp`	boolean	`true`, якщо це печатка.
`validityYears`	enum	`ONE` або `TWO`.
`validFrom`	number	Початок дії сертифіката, Unix timestamp у секундах.
`validTo`	number	Кінець дії сертифіката, Unix timestamp у секундах.
`usage`	number	Внутрішній usage.
`parentKeyId`	number	Внутрішній ID батьківського ключа, якщо є.
`requests`	array	Масив [ESSPKRequest](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esspkrequest).
`certificates`	array	Масив [ESSCertificate](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscertificate).

# Об'єкт ESSCAUser ##### **Опис параметрів об’єкта**

Поле	Формат	Опис
`id`	number	Внутрішній ID CA user.
`userId`	number	Внутрішній ID користувача.
`type`	enum	Тип CA user, наприклад `COMPANY`, `SELF_EMPLOYED`, `PERSONAL`.
`serialNumber`	number	Серійний номер користувача в ЦСК.
`info`	object/null	Об'єкт [ESSCAUserInfo](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscauserinfo).
`companyId`	number	Внутрішній ID компанії.
`company`	object/null	Об'єкт [ESSCompany](https://wiki-v2.edin.ua/books/robota-z-api-portalu-edin-id/page/objekt-esscompany)

# Об'єкт ESSCAUserInfo ##### **Опис параметрів об'єкта**

Поле	Формат	Опис
`commonName`	string/null	CN.
`userCode`	string/null	Код користувача.
`locality`	string/null	Населений пункт.
`state`	string/null	Область/регіон.
`country`	string/null	Країна.
`street`	string/null	Адреса.
`organization`	string/null	Організація.
`organizationCode`	string/null	Код організації.
`organizationUnit`	string/null	Підрозділ.
`ouCode`	string/null	Код підрозділу.
`title`	string/null	Посада.
`phone`	string/null	Телефон.
`surname`	string/null	Прізвище.
`givenname`	string/null	Імʼя/по батькові.
`email`	string/null	Email.
`dns`	string/null	DNS.
`upn`	string/null	UPN.
`edrpouCode`	string/null	ЄДРПОУ.
`drfoCode`	string/null	РНОКПП/ДРФО.
`nbuCode`	string/null	Код НБУ.
`unzr`	string/null	УНЗР.
`information`	string/null	Додаткова інформація.
`passPhrase` або `isPassPhrase`	boolean	Чи збережено секретну фразу.
`publishCert`	boolean	Публікувати сертифікат.
`publishCertOut`	boolean	Публікувати сертифікат назовні.

# Об'єкт ESSPKRequest ##### **Опис параметрів об'єкта**

Поле	Формат	Опис
`privateKeyId`	number	Внутрішній ID ключа.
`type`	enum	`SIGNATURE`, `ENCRYPTION`, `ECDSA`.
`content`	number\[\]	Бінарний p10 request у форматі `PKCS #10` у JSON як масив байтів.
`publicKey`	number\[\]	Публічний ключ як масив байтів.
`publicKeyId`	number\[\]	ID публічного ключа як масив байтів.

# Об'єкт ESSCertificate ##### **Опис параметрів об'єкта**

Поле	Формат	Опис
`type`	enum	`SIGNATURE`, `ENCRYPTION`, `ECDSA`.
`status`	enum	Статус сертифіката.
`serial`	string	Серійний номер сертифіката.

# Об'єкт ESSUserIdentification ##### **Опис параметрів об'єкта**

Поле	Формат	Опис
`type`	enum	Тип ідентифікації.
`complete`	enum	`YES` або `NO`.
`fullName`	string/null	ПІБ українською.
`fullNameEN`	string/null	ПІБ англійською.
`ipn`	string/null	РНОКПП/ІПН.
`unzr`	string/null	УНЗР.
`state`	string/null	Область/регіон.
`city`	string/null	Населений пункт.
`address`	string/null	Адреса.
`publicKey`	string/null	Публічний ключ у hex-поданні.
`validTo`	number	Дата завершення сертифіката, Unix timestamp у секундах.
`sign`	string/null	Зазвичай `null` у цих відповідях; файл підпису повертається окремо в полі `data`.

# Об'єкт ESSPrivateKeysQuery ##### **Опис параметрів об'єкта**

Параметр	Формат	Тип ¹	Опис
`nameQuery`	string	O	Пошук за назвою ключа.
`companyQuery`	string	O	Пошук за назвою компанії.
`caUserName`	string	O	Пошук за CA user name.
`stamp`	boolean	O	`true` — тільки печатки, `false` — тільки ключі.
`validTo`	object	O	Діапазон дати `validTo`.
`userId`	number	O	Internal поле; для external API краще не використовувати.
`title`	string	O	Пошук за посадою.
`parentPKeyId`	number	O	Internal поле батьківського ключа.
`uuids`	string\[\]	O	Список UUID ключів.
`statuses`	enum\[\]	O	Фільтр за статусами ключів.
`statusTypes`	enum\[\]	O	Фільтр за типами статусів.
`storeType`	enum\[\]	O	`HSM`, `FILE`.
`keyType`	enum\[\]	O	`UA`, `ECDSA`.
`caType`	enum\[\]	O	Тип CA user.
`pKeyId`	number\[\]	O	Internal ID ключів; для external API краще не використовувати.
`companies`	number\[\]	O	Internal поле; у external API компанія береться з `companyCode`.
`users`	number\[\]	O	Internal поле; для методу пошуку ключів співробітника employee береться з `employeeIpn`.
`usage`	number\[\]	O	Usage фільтр.
`orderBy`	object	O	Сортування.
`limit`	object	O	Ліміт/offset.

**JSON приклад:** ```json { "nameQuery": "Ключ", "stamp": false, "statuses": ["ACTIVATED"], "storeType": ["HSM"], "keyType": ["UA"], "limit": { "offset": 0, "count": 50 } } ``` ---

1 - Під визначенням колонки **Тип поля** мається на увазі скорочене позначення:: - M (mandatory) — обов’язкові до заповнення поля; - O (optional) — необов’язкові (опціональні) до заповнення поля.

# Об'єкт ESSUsersQuery ##### **Опис параметрів об'єкта**

Параметр	Формат	Тип ¹	Опис
`search`	string	O	Пошук за ПІБ, ІПН або телефоном.
`users`	number\[\]	O	Internal ID користувачів; для external API краще не використовувати.
`companies`	number\[\]	O	Internal поле; компанія береться з `companyCode`.
`role`	enum\[\]	O	`USER`, `ADMIN`, `SUPER_ADMIN`.
`identification`	enum\[\]	O	`YES`, `NO`.
`employeeStatus`	enum\[\]	O	Наприклад `ACTIVE`.
`registration`	boolean	O	Фільтр за реєстрацією користувача.
`orderBy`	object	O	Сортування.
`limit`	object	O	Ліміт/offset.

**JSON приклад:** ```json { "search": "3148615913", "role": ["USER", "ADMIN"], "identification": ["YES"], "employeeStatus": ["ACTIVE"], "limit": { "offset": 0, "count": 50 } } ``` # Об'єкт EndUserCertificateInfoEx ##### ``` class EndUserCertificateInfoEx { isFilled: boolean; version: number; issuer: string; issuerCN: string; serial: string; subject: string; subjCN: string; subjOrg: string; subjOrgUnit: string; subjTitle: string; subjState: string; subjLocality: string; subjFullName: string; subjAddress: string; subjPhone: string; subjEMail: string; subjDNS: string; subjEDRPOUCode: string; subjDRFOCode: string; subjNBUCode: string; subjSPFMCode: string; subjOCode: string; subjOUCode: string; subjUserCode: string; certBeginTime: Date; certEndTime: Date; isPrivKeyTimesAvail: boolean; privKeyBeginTime: Date; privKeyEndTime: Date; publicKeyBits: number; publicKey: string; publicKeyID: string; issuerPublicKeyID: string; keyUsage: string; extKeyUsages: string; policies: string; crlDistribPoint1: string; crlDistribPoint2: string; isPowerCert: boolean; isSubjTypeAvail: boolean; isSubjCA: boolean; chainLength: number; UPN: string; publicKeyType: number; keyUsageType: number; RSAModul: string; RSAExponent: string; OCSPAccessInfo: string; issuerAccessInfo: string; TSPAccessInfo: string; isLimitValueAvailable: boolean; limitValue: number; limitValueCurrency: string; subjType: number; subjSubType: number; subjUNZR: string; subjCountry: string; fingerprint: string; isQSCD: boolean; subjUserID: string; certHashType: number; } ```

URL
Метод запиту	POST
URL запиту	/api/external/company/sign/file
Authorization
Auth type	API key
Key / Value	x-system-id / токен, отриманий при підключенні
Headers
Content-Type	[multipart/form-data](https://tools.ietf.org/html/rfc7578)
Request body	Параметри тіла запиту: - 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)
Params	- key – ідентифікатор ключа. - type – тип підписання, може приймати значення: - append – додає підпис до переданого файлу. ВАЖЛИВО! Якщо файл вже був підписаний, то підпис додається до існуючого, а не підписується разом з існуючим підписом. - sign - підписує контент, використовується за замовчуванням. - result – формат підписання (дані й підпис в одному файлі, дані й підпис в окремих файлах), може приймати значення: - enveloped – у відповідь надійде файл з підписом - detached – у відповідь надійде тільки підпис - inputFormat – формат вхідних даних для підписання, може приймати значення: - file – файл в бінарному вигляді - base64 – файл у вигляді base64 рядка - outputFormat – формат вихідних (результуючих) даних після підписання, може приймати значення: - file – файл в бінарному вигляді - base64 – файл у вигляді base64 рядка - signType – тип підпису, приймає значення CADES\_BES, CADES\_T, CADES\_C, CADES\_X\_LONG, CADES\_X\_LONG\_TRUSTED. Якщо не передано, то за замовченням підставляється CADES\_BES - algorithm (enum) - алгоритм формату підписання: - DSTU4145\_GOST34311, - DSTU4145\_DSTU7564, - ECDSA