Об'єкти 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;
}