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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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