Робота з API порталу EDIN ID

• Перелік методів API по роботі з порталом EDIN ID
• Шифрування пароля за допомогою відкритого ключа RSA
• Помилки при роботі з API
• Методи API
• Отримати і зберегти публічний ключ GET /api/external/key
• Підписати ключем співробітника компанії POST /api/external/company/sign
• Підписати файл ключем співробітника компанії POST /api/external/company/sign/file
• Отримати інформацію про компанію GET /api/external/company
• Отримати інформацію про співробітника GET /api/external/company/employee
• Пошук ключів співробітника POST /api/external/company/employee/pkeys/search
• Пошук співробітників компанії POST /api/external/company/employees/search
• Пошук ключів компанії POST /api/external/company/pkeys/search
• Отримати інформацію про ключ GET /api/external/company/pkey
• Отримання документа компанії GET /api/external/company/form
• Отримати ідентифікацію співробітника GET /api/external/company/employee/identification
• Отримати документ ключа GET /api/external/company/pkey/form
• Додати співробітника POST /api/external/company/employee
• Створити чернетку ключа для співробітника POST /api/external/company/employee/pkey/generate/draft
• Згенерувати PDF-форму для адміністратора компанії PATCH /api/external/company/employee/pkey/generate/draft
• Передати підписи PDF і активувати ключ POST /api/external/company/employee/pkey/activation
• Змінити статус ключа POST /api/external/company/pkey/status
• Змінити статус співробітника POST /api/external/company/employee/status
• Верифікувати підпис на файлі POST /api/external/company/sign/file/verify
• Отримати інформацію про сертифікат GET /api/external/company/key/certificate
• Створення компанії POST /api/external/company/create
• Об'єкти API
• Довідник enum значень
• Об'єкт ESSCompany
• Об'єкт ESSUser
• Обект ESSPrivateKey
• Об'єкт ESSCAUser
• Об'єкт ESSCAUserInfo
• Об'єкт ESSPKRequest
• Об'єкт ESSCertificate
• Об'єкт ESSUserIdentification
• Об'єкт ESSPrivateKeysQuery
• Об'єкт ESSUsersQuery
• Об'єкт EndUserCertificateInfoEx

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

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

Для підписання хеш(ів) та/або файлу пароль передається в зашифрованому вигляді.

Авторизація 

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

Приклад:

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

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

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

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

API очікує саме base64 від зашифрованих bytes, а не plaintext пароль.

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

Колекція Postman

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

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

1. Створити чернетку ключа та отримати PDF для підпису співробітником.
2. Згенерувати PDF для підпису адміністратором компанії.
3. Передати detached-підписи всіх PDF і активувати ключ або передати його на активацію КНЕДП.

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

1. Перевірити компанію методом 1.
2. Якщо співробітника ще немає – створити його методом 8.
3. Перевірити співробітника методом 2.
4. Викликати метод 9.1 і отримати pKey.uuid та employee PDF-форми.
5. Співробітник підписує PDF-форми з відповіді 9.1 detached-підписом.
6. Викликати метод 9.2 з pKeyUuid та adminIpn і отримати admin PDF-форми.
7. Адміністратор/суперадміністратор підписує PDF-форми з відповіді 9.2 detached-підписом.
8. Викликати метод 9.3, передавши keyUuid, activate і map підписів за всіма отриманими formType.
9. Отримати оновлений 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");

Як шифрувати?

1. Отримати публічний ключ через /api/external/key?type=pem.
2. Імпортувати public key у crypto-бібліотеку як RSA public key.
3. Зашифрувати plaintext пароль bytes.
4. Результат RSA encryption закодувати в base64.
5. Передати 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"
}

Загальні помилки

Типові помилки доступу:

{"type":"access_denied"}

{"type":"company_access_denied"}

{"type":"company_wrong_status","status":"DRAFT"}

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

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

Методи API

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

REQUEST

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

RESPONSE

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

Приклад:

{
    "fFNkFPush1kn988zLJoXBoSYilWMI408xxQ7Xs69Ww=": "MIILPgYJKoZIhvcNAQcC..."
}

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

REQUEST

RESPONSE

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

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

REQUEST

RESPONSE

В тілі відповіді передаються статус 200 та об'єкт ESSCompany.

CURL 

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

Помилки 

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

REQUEST

RESPONSE

В тілі відповіді передаються статус 200 та об'єкт ESSUser.

CURL

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

Помилки 

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

REQUEST

{
  "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}
  }'

Помилки 

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

REQUEST

{
  "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}
  }'

Помилки 

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

REQUEST

{
  "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}
  }'

Помилки 

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

REQUEST

RESPONSE

В тілі відповіді передаються статус 200 та об'єкт ESSPrivateKey.

CURL

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

Помилки 

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

REQUEST

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..."
}

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'

Помилки

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

REQUEST

RESPONSE

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

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

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

Помилки 

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

REQUEST

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

Помилки 

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

REQUEST

info:

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

Опис полів:

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'

Помилки 

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

REQUEST

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:

requests для store=file:

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

Опис полів requests :

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.

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

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"
  }'

Помилки 

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

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

REQUEST

RESPONSE

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

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

{
  "pKey": {
    "uuid": "019ec000-0000-7000-8000-000000000001",
    "status": "COMPANY_GENERATED"
  },
  "forms": [
    {
      "type": "AFFILIATION_CONFIRMATION",
      "pdf": "JVBERi0x...",
      "hash": "HASH_OF_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'

Помилки 

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

REQUEST

{
  "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"
    ]
  }
}

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

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

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

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"
      ]
    }
  }'

Помилки 

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

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

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

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

REQUEST

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

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

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

Помилки

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

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

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

REQUEST

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

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

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

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

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

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

Помилки 

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

REQUEST

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

RESPONSE

У відповідь повертається об'єкт EndUserCertificateInfoEx з інформацією про сертифікат або контент сертифіката в base64 (якщо raw = true)

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

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

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

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

REQUEST

COMPANY:

---

1 - Під визначенням колонки Тип поля мається на увазі скорочене позначення:

• M (mandatory) — обов’язкові до заповнення поля;

• O (optional) — необов’язкові (опціональні) до заповнення поля.

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

INFO:

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

Помилки

Об'єкти API

Довідник enum значень

ESSRegFormType 

Для запитів на документи formType передається як enum name:

У методі для заміни статусу ключа підписи передаються у map forms, де ключ — це enum name, наприклад, "PK_FORM" або "PK_APPENDIX".

Інші поширені enum

Об'єкт ESSCompany

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

Об'єкт ESSUser

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

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

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

Об'єкт ESSCAUser

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

Об'єкт ESSCAUserInfo

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

Об'єкт ESSPKRequest

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

Об'єкт ESSCertificate

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

Об'єкт ESSUserIdentification

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

Об'єкт ESSPrivateKeysQuery

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

JSON приклад:

{
  "nameQuery": "Ключ",
  "stamp": false,
  "statuses": ["ACTIVATED"],
  "storeType": ["HSM"],
  "keyType": ["UA"],
  "limit": {
    "offset": 0,
    "count": 50
  }
}

1 - Під визначенням колонки Тип поля мається на увазі скорочене позначення:

• M (mandatory) — обов’язкові до заповнення поля;

• O (optional) — необов’язкові (опціональні) до заповнення поля.

Об'єкт ESSUsersQuery

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

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;
}