Методи 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 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

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

PDF bytes з content type:

Content-Type: application/pdf
{
  "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

Такий самий, як у методі Отримання документа компанії:

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

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

URL

Метод запиту

POST

URL запиту

/api/external/company/pkey/status

URL параметри

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

Authorization

Auth type

 API key

Key / Value

 x-system-id - токен, отриманий при підключенні

Headers

  

Content-Type

application/json

REQUEST

  

JSON Body

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

 

{
  "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-ідентифікацією.