Робота з API порталу EDIN ID
Колекцію Postman можна скачати в сторінці "Перелік методів АРІ"

Перелік методів API по роботі з порталом EDIN ID
Всі запити нижче перерахованих API методів порталу EDIN ID направляються на адресу: https://id.edin.ua
Для підписання хеш(ів) та/або файлу пароль передається в зашифрованому вигляді.
Авторизація 
Кожен запит має містити 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: 
info.caPassPhrase
base64(RSA-encrypt(publicKey, caPassPhraseBytes))
Метод 9.1: 
info.pkPassword
base64(RSA-encrypt(publicKey, pkPasswordBytes))
Метод 11: 
adminKeyPassword
base64(RSA-encrypt(publicKey, adminKeyPasswordBytes))
Підписати хеш ключем співробітника компанії: requestbody.password
base64(RSA-encrypt(publicKey, password))
Підписати файл ключем співробітника компанії: params.password
base64(RSA-encrypt(publicKey, caPassPhraseBytes))
API очікує саме base64 від зашифрованих bytes, а не plaintext пароль.
Інтеграція підписання в облікову систему
1
Отримати і зберегти публічний ключ
GET /api/external/key
2
Підписати хеш ключем співробітника компанії
POST /api/external/company/sign
3
Підписати файл ключем співробітника компанії
POST /api/external/company/sign/file
4
Верифікувати підпис на файлі
POST /api/external/company/sign/file/verify
5
Отримати інформацію про сертифікат
GET /api/external/company/key/certificate
Колекція Postman
Інтеграція управління ключами в облікову систему
1
Отримати інформацію про компанію
GET /api/external/company
2
Отримати інформацію про співробітника
GET /api/external/company/employee
3
Пошук ключів співробітника
POST /api/external/company/employee/pkeys/search
4
Пошук співробітників компанії
POST /api/external/company/employees/search
5
Пошук ключів компанії
POST /api/external/company/pkeys/search
6
Отримати інформацію про ключ
GET /api/external/company/pkey
7.1
Отримати документ компанії
GET /api/external/company/form
7.2
Отримати ідентифікацію співробітника
GET /api/external/company/employee/identification
7.3
Отримати документ ключа
GET /api/external/company/pkey/form
8
Додати співробітника
POST /api/external/company/employee
9.1
Створити чернетку ключа
POST /api/external/company/employee/pkey/generate/draft
9.2
Згенерувати PDF-форму для адміністратора компанії
PATCH /api/external/company/employee/pkey/generate/draft
9.3
Передати підписи PDF і активувати ключ
POST /api/external/company/employee/pkey/activation
10
Змінити статус ключа
POST /api/external/company/pkey/status
11
Змінити статус співробітника 
POST /api/external/company/employee/status
12
Створити компанію
POST /api/external/company/create
Створення ключа складається з трьох запитів:
Створити чернетку ключа та отримати PDF для підпису співробітником.
Згенерувати PDF для підпису адміністратором компанії.
Передати detached-підписи всіх PDF і активувати ключ або передати його на активацію КНЕДП.
Рекомендований сценарій створення та активації ключа:
Перевірити компанію методом 1.
Якщо співробітника ще немає – створити його методом 8.
Перевірити співробітника методом 2.
Викликати метод 9.1 і отримати 
pKey.uuid та employee PDF-форми.
Співробітник підписує PDF-форми з відповіді 9.1 detached-підписом.
Викликати метод 9.2 з 
pKeyUuid та 
adminIpn і отримати admin PDF-форми.
Адміністратор/суперадміністратор підписує PDF-форми з відповіді 9.2 detached-підписом.
Викликати метод 9.3, передавши 
keyUuid, 
activate і map підписів за всіма отриманими 
formType.
Отримати оновлений 
ESSPrivateKey зі статусом 
ACTIVATED або 
COMPANY_ADMIN_APPROVED.

Шифрування пароля за допомогою відкритого ключа RSA
Приклад для Postman (js)
Функції для шифрування
/**
 * 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);
}
Шифрування пароля
const encrypted = await utils.rsaEncrypt(Uint8Array.from(publicKey), password));
де, 
publicKey - публічний ключ, отриманий методом GET /api/external/key
password - пароль від ключа
Приклад 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
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");
Як шифрувати?
Отримати публічний ключ через 
/api/external/key?type=pem.
Імпортувати public key у crypto-бібліотеку як RSA public key.
Зашифрувати plaintext пароль bytes.
Результат RSA encryption закодувати в base64.
Передати base64 string у відповідне поле запиту.
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:
{
  "type": "employee_not_found"
}
Загальні помилки
Код відповіді
Опис
403
Помилка авторизації зовнішньої системи або підключення зовнішньої системи відбувається з недоступних IP-адрес або компанія не привʼязана до зовнішньої системи..
400
Бізнес/валідаційні помилки: не знайдено співробітника, ключ, документ, неправильний статус тощо.
413
Перевищено допустимий розмір файлу, якщо для конкретного upload-методу увімкнений ліміт.
Типові помилки доступу:
{"type":"access_denied"}
{"type":"company_access_denied"}
{"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-файл у вигляді
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQ9QIDAQAB
-----END PUBLIC KEY-----
якщо type = XML – повертається XML-файл у вигляді
<?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
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
Request body
Параметри тіла запиту:
password – зашифрований пароль до ключа
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.
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.
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
 
 JSON приклад запиту:
 
{
  "statuses": ["ACTIVATED"],
  "stamp": false,
  "limit": {
    "offset": 0,
    "count": 20
  }
}
RESPONSE
В тілі відповіді передаються статус 200 та масив об'єктів 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
 
 JSON приклад запиту:
 
{
  "search": "3148615913",
  "role": ["USER", "ADMIN"],
  "identification": ["YES"],
  "employeeStatus": ["ACTIVE"],
  "limit": {
    "offset": 0,
    "count": 20
  }
}
RESPONSE
В тілі відповіді передаються статус 200 та масив об'єктів ESSUser.
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
 
 JSON приклад запиту:
 
{
  "nameQuery": "Печатка",
  "stamp": true,
  "statuses": ["ACTIVATED"],
  "limit": {
    "offset": 0,
    "count": 20
  }
}
 
RESPONSE
В тілі відповіді передаються статус 200 та масив об'єктів 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.
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.
data
string
Base64 підпису ідентифікації. Повертається лише якщо 
info.complete == YES.
Якщо ідентифікація не завершена, поле 
data не повертається.
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
Такий самий, як у методі Отримання документа компанії:
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:
{
  "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 з даними доданого або вже існуючого співробітника.
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.
 
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:
{
  "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
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
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:
{
  "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  приклад відповіді:
{
  "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 ключа з відповіді на виклик метода створення чернетки ключа;
adminIpn (обов’язково) - ІПН/РНОКПП адміністратора або суперадміністратора компанії, який підписуватиме admin-форми.
 
Якщо ключ створюється для співробітника з роллю 
ADMIN, у 
adminIpn потрібно передати саме 
SUPER_ADMIN компанії.
Authorization
Auth type
API key
Key / Value
x-system-id - токен, отриманий при підключенні
Headers
 
Content-Type
application/json
RESPONSE
В тілі відповіді передається статус 200.
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
Приклад запиту:
 
{
  "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 .
Якщо 
activate=true, очікуваний статус:
{
  "uuid": "019ec000-0000-7000-8000-000000000001",
  "status": "ACTIVATED"
}
Якщо 
activate=false, очікуваний статус:
{
  "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:
формує PDF-форми зміни статусу;
підписує їх ключем адміністратора/суперадміністратора;
зберігає підписані PDF як підтвердження зміни статусу;
змінює статус ключа у системі;
передає зміну статусу до центру сертифікації;
повертає масив підписаних 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 приклад запиту:
 
{
  "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  приклад відповіді:
{
  "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:
{
    "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 з інформацією про сертифікат або контент сертифіката в 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
COMPANY:
Поле
Формат
Тип 1
Опис
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 приклад запиту
{
  "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.
CURL
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
Протокол розбіжностей
У методі для заміни статусу ключа підписи передаються у 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 приклад:
{
  "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 приклад:
{
  "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.
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.
certificates
array
Масив ESSCertificate.
 

Об'єкт ESSCAUser
Опис параметрів об’єкта
Поле
Формат
Опис
id
number
Внутрішній ID CA user.
userId
number
Внутрішній ID користувача.
type
enum
Тип CA user, наприклад 
COMPANY, 
SELF_EMPLOYED, 
PERSONAL.
serialNumber
number
Серійний номер користувача в ЦСК.
info
object/null
Об'єкт ESSCAUserInfo.
companyId
number
Внутрішній ID компанії.
company
object/null
Об'єкт 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
Опис параметрів об'єкта
Параметр
Формат
Тип 1
Опис
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 приклад:
{
  "nameQuery": "Ключ",
  "stamp": false,
  "statuses": ["ACTIVATED"],
  "storeType": ["HSM"],
  "keyType": ["UA"],
  "limit": {
    "offset": 0,
    "count": 50
  }
}
1 - Під визначенням колонки Тип поля мається на увазі скорочене позначення:
M (mandatory) — обов’язкові до заповнення поля;
O (optional) — необов’язкові (опціональні) до заповнення поля.

Об'єкт ESSUsersQuery
Опис параметрів об'єкта
Параметр
Формат
Тип 1
Опис
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 приклад:
{
  "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;
}