# API: настройки пользователей и организаций ## `GET` `/api/settings` - получить настройки аутентифицированного пользователя {#user-settings} Ответ: ```json { "userId": "IIN123456789012", "emailNotificationsEnabled": true, "emailNotificationsRoutingEnabled": false, "email": "user@example.com", "modifiedAt": 1585827107000, "dataArchiveEnabled": false, "dataArchiveQuota": 123, "dataArchiveQuotaExpires": 1585827107001, "dataArchiveUsage": 123, "dataArchiveContactEmail": "userArchiver@example.com" } ``` - `userId` - ИИН пользователя; - `emailNotificationsEnabled` - флаг указывающий включена ли отправка уведомлений по электронной почте для данного пользователя; - `emailNotificationsRoutingEnabled` - флаг указывающий включена ли отправка уведомлений связанных с входящими и исходящими по электронной почте для данного пользователя; - `email` - электронный адрес пользователя, поле может содержать пустую строку (`""`); - `modifiedAt` - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит `0`; - `dataArchiveEnabled` - флаг, указывающий активировано ли архивирование подписанных данных, если включен, необходимо указать `dataArchiveContactEmail`; - `dataArchiveQuota` - размер текущей квоты архивирования (в байтах); - `dataArchiveQuotaExpires` - опциональное поле, содержащее дату истечения срока действия дополнительной квоты (в миллисекундах с UNIX Epoch); - `dataArchiveUsage` - объем хранящихся в архиве данных (в байтах); - `dataArchiveContactEmail` - электронный адрес для отправки уведомлений, связанных с архивированием данных. *** ## `POST` `/api/settings` - сохранить настройки аутентифицированного пользователя {#user-settings-apply} Запрос (`Content-Type` необходимо установить в `application/json`): ```json { "emailNotificationsEnabled": false, "emailNotificationsRoutingEnabled": false, "email": "otheruser@example.com", "dataArchiveEnabled": true, "dataArchiveContactEmail": "userArchiver@example.com" } ``` - `emailNotificationsEnabled` - новое значение флага указывающего включена ли отправка уведомлений по электронной почте для данного пользователя; - `emailNotificationsRoutingEnabled` - новое значение флага указывающего включена ли отправка уведомлений связанных с входящими и исходящими по электронной почте для данного пользователя; - `email` - новый электронный адрес пользователя, разрешено передавать пустую строку (`""`); - `dataArchiveEnabled` - новое значение флага, позволяющего включить/отключить архивирование подписанных данных; - `dataArchiveContactEmail` - новый электронный адрес для отправки уведомлений, связанных с архивированием данных. Ответ: ```json { "userId": "IIN123456789012", "modifiedAt": 1585827107000 } ``` - `userId` - ИИН пользователя; - `modifiedAt` - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. *** ## `GET` `/api/settingsAudit?lastEventId=X` - аудит изменений настроек пользователя {#user-settings-audit} - `lastEventId=X` - опционально, последний идентификатор записи после которого нужно возвращать записи. Возвращает журнал изменений настроек пользователя. Ответ: ```json { "userId": "IIN112233445566", "eventsTotal": 3, "events": [] } ``` - `userId` - ИИН пользователя; - `eventsTotal` - количество изменений зарегистрированных в системе; - `events` - массив объектов описывающих изменения. Структура объектов описывающих изменения: ```json { "eventId": 1, "original": {}, "modified": {}, "modifiedAt": 1586167317737 } ``` - `eventId` - идентификатор события; - `original` - настройки до изменения; - `modified` - настройки после изменения; - `modifiedAt` - момент изменения в миллисекундах с UNIX Epoch. *** ## `GET` `/api/organizationSettings` - получить настройки организации аутентифицированного пользователя {#organization-settings} Настройки организации определяют уровень доступа к документам организации сотрудникам, имеющим указанные полномочия, и информационным системам, прошедшим аутентификацию по указанным клиентским сертификатам. Подробнее о методах аутентификации и настройках читайте в разделе [Аутентификация и контроль доступа](/en/support/developers/auth-and-access-control/index.md). Ответ: ```json { "businessId": "BIN123456789012", "tlsCertificatesList": [ { "description": "First certificate", "body": "PEM-ENCODED-CERT-1", "disabled": false, "settings": { "ddcHowToVerifyStrings": { "kk": "", "ru": "" } } }, { "description": "Second certificate", "body": "PEM-ENCODED-CERT-2", "disabled": false, "settings": {} }, { "description": "Third certificate", "body": "PEM-ENCODED-CERT-3", "disabled": true, "settings": { "qrOrganisationName": { "kk": "OrgKK", "ru": "Orgru", "en": "Orgen" }, "qrLogo": "MTEK", "ddcLogo": "MTEK", "ddcLogoString":{ "kk": "sigex.kz сайтына жазылды", "ru": "подписано на сайте sigex.kz" }, "ddcLogoDisable": false } }, ], "documentsAccess": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [0], "iins": ["IIN111111111111"] }, "documentsList": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [0, 1], "iins": [] }, "documentsSettings": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": ["IIN111111111111"] }, "organizationSettings": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": ["IIN111111111111"] }, "documentsPackagesRoute": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": ["IIN111111111111"] }, "routedDocumentsPackagesView": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": ["IIN111111111111"] }, "webhooks":{ "urls":["https://example.com/webhook-for-sigex","https://192.168.1.12"], "routingUrls": ["https://example.com/webhook-for-sigex","https://192.168.1.12"] }, "modifiedAt": 1585827107000, "dataArchiveEnabled": false, "dataArchiveQuota": 123, "dataArchiveQuotaExpires": 1585827107001, "dataArchiveUsage": 123, "dataArchiveContactEmail": "orgArchiver@example.com", "subscriptionContactEmail": "orgSubscriber@example.com", "routingContactEmail": "orgSubscriber@example.com" } ``` - `businessId` - БИН организации; - `tlsCertificatesList` - массив клиентских сертификатов информационных систем; - `documentsAccess` - контроль доступа к документам организации; - `documentsList` - контроль доступа к перечислению документов организации; - `documentsSettings` - контроль доступа к редактированию настроек документов организации; - `organizationSettings` - контроль доступа к просмотру и редактированию настроек организации; - `documentsPackagesRoute` - контроль доступа к возможности отправки исходящих от имени организации и комментирования входящих и исходящих; - `routedDocumentsPackagesView` - контроль доступа к возможности просмотра списков входящих и исходящих организации; - `webhooks` - параметры доставки [Webhook](/en/support/developers/notifications/index.md#notifications-webhook) уведомлений: - `urls` - адреса для отправки стандартных уведомлений; - `routingUrls` - адреса для отправки уведомлений о входящих и исходящих; - `modifiedAt` - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит `0`; - `dataArchiveEnabled` - флаг, указывающий активировано ли архивирование подписанных данных, если включен, необходимо указать `dataArchiveContactEmail`; - `dataArchiveQuota` - размер текущей квоты архивирования (в байтах); - `dataArchiveQuotaExpires` - опциональное поле, содержащее дату истечения срока действия дополнительной квоты (в миллисекундах с UNIX Epoch); - `dataArchiveUsage` - объем хранящихся в архиве данных (в байтах); - `dataArchiveContactEmail` - электронный адрес для отправки уведомлений, связанных с архивированием данных; - `subscriptionContactEmail` - электронный адрес для отправки уведомлений, связанных с подпиской организации; - `routingContactEmail` - электронный адрес для отправки уведомлений, связанных с входящими и исходящими. Элементы массива `tlsCertificatesList` хранят информацию о сертификатах, которые информационные системы могут использовать для клиентской mTLS аутентификации и имеют следующую структуру: - `description` - описание; - `body` - сертификат в формате PEM, то есть строка; - `disabled` - флаг помечающий сертификат как отключенный; - `settings` - объект настроек информационной системы. Объекты настроек информационных систем позволяют конфигурировать информационные системы по отдельности и имеют следующую структуру: - `ddcHowToVerifyStrings` - объект с пояснениями о процедуре проверки подписей, отображаемыми на формируемых Карточках электронных документов, ключами являются языки, в данный момент поддерживаются `"ru"` и `"kk"`; - `qrOrganisationName` - объект с названиями организации, отображаемыми в приложениях eGov mobile и eGov Business при подписании через QR и по ссылке, ключами являются языки, необходимо указывать три языка: `"ru"`, `"kk"` и `"en"`; - `qrLogo` - логотип для встраивания в центр QR кода при подписании через QR, должен быть в формате `PNG` (не более 102х102 пикселя) закодированный в `base64`; - `ddcLogo` - логотип отображаемый на формируемых карточках электронных документов, должен быть в формате `PNG` (точно 200x100 пикселей) закодированный в `base64`; - `ddcLogoString` - объект с подписями под логотипом отображаемым на формируемых карточках электронных документов, ключами являются языки, в данный момент поддерживаются `"ru"` и `"kk"`; - `ddcLogoDisable` - флаг позволяющий отключить нанесение логотипа на формируемые карточки электронных документов. Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру: - `authorities` - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа; - `tlsCertificatesIndices` - массив индексов сертификатов из `tlsCertificatesList`, определяет по каким сертификатам разрешен доступ; - `iins` - массив ИИНов сотрудников организации, которые имеют доступ. Поле `webhooks` имеет следующую структуру: - `urls` - массив строк с URL для отправки [Webhook](/en/support/developers/notifications/index.md#notifications-webhook) уведомлений. *** ## `POST` `/api/organizationSettings` - сохранить настройки организации {#organization-settings-apply} Настройки организации позволяют предоставлять доступ к документам организации сотрудникам, имеющим указанные полномочия, и информационным системам, прошедшим аутентификацию по указанным клиентским сертификатам. Подробнее о методах аутентификации и настройках читайте в разделе [Аутентификация и контроль доступа](/en/support/developers/auth-and-access-control/index.md). Запрос (`Content-Type` необходимо установить в `application/json`): ```json { "tlsCertificatesList": [ { "description": "First certificate", "body": "PEM-ENCODED-CERT-1", "disabled": false, "settings": { "ddcHowToVerifyStrings": { "kk": "", "ru": "" } } }, { "description": "Second certificate", "body": "PEM-ENCODED-CERT-2", "disabled": false, "settings": {} }, { "description": "Third certificate", "body": "PEM-ENCODED-CERT-3", "disabled": true, "settings": { "qrOrganisationName": { "kk": "OrgKK", "ru": "Orgru", "en": "Orgen" }, "qrLogo": "MTEK", "ddcLogo": "MTEK", "ddcLogoString":{ "kk": "sigex.kz сайтына жазылды", "ru": "подписано на сайте sigex.kz" }, "ddcLogoDisable": false } }, ], "documentsAccess": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [0], "iins": ["IIN111111111111"] }, "documentsList": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [0, 1], "iins": [] }, "documentsSettings": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": [] }, "packagesAccess": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [0], "iins": ["IIN111111111111"] }, "packagesList": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [0, 1], "iins": [] }, "packagesSettings": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": [] }, "organizationSettings": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": [] }, "documentsPackagesRoute": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": ["IIN111111111111"] }, "routedDocumentsPackagesView": { "authorities": ["OID1", "OID2"], "tlsCertificatesIndices": [1], "iins": ["IIN111111111111"] }, "webhooks":{ "urls":["https://example.com/webhook-for-sigex","https://192.168.1.12"], "routingUrls": ["https://example.com/webhook-for-sigex","https://192.168.1.12"] }, "dataArchiveEnabled": true, "dataArchiveContactEmail": "orgArchiver@example.com", "subscriptionContactEmail": "orgSubscriber@example.com", "routingContactEmail": "orgSubscriber@example.com" } ``` - `tlsCertificatesList` - массив клиентских сертификатов информационных систем; - `documentsAccess` - контроль доступа к документам организации; - `documentsList` - контроль доступа к перечислению документов организации; - `documentsSettings` - контроль доступа к редактированию настроек документов организации; - `packagesAccess` - контроль доступа к пакетам документов организации; - `packagesList` - контроль доступа к перечислению пакетов документов организации; - `packagesSettings` - контроль доступа к редактированию настроек пакетов документов организации; - `organizationSettings` - контроль доступа к просмотру и редактированию настроек организации; - `documentsPackagesRoute` - контроль доступа к возможности отправки исходящих от имени организации и комментирования входящих и исходящих; - `routedDocumentsPackagesView` - контроль доступа к возможности просмотра списков входящих и исходящих организации; - `webhooks` - параметры доставки [Webhook](/en/support/developers/notifications/index.md#notifications-webhook) уведомлений: - `urls` - адреса для отправки стандартных уведомлений; - `routingUrls` - адреса для отправки уведомлений о входящих и исходящих; - `dataArchiveEnabled` - новое значение флага, позволяющего включить/отключить архивирование подписанных данных; - `dataArchiveContactEmail` - новый электронный адрес для отправки уведомлений, связанных с архивированием данных; - `subscriptionContactEmail` - электронный адрес для отправки уведомлений, связанных с подпиской организации; - `routingContactEmail` - электронный адрес для отправки уведомлений, связанных с входящими и исходящими. Элементы массива `tlsCertificatesList` хранят информацию о сертификатах, которые информационные системы могут использовать для клиентской mTLS аутентификации и имеют следующую структуру: - `description` - описание; - `body` - сертификат в формате PEM, то есть строка; - `disabled` - флаг помечающий сертификат как отключенный; - `settings` - объект настроек информационной системы. Объекты настроек информационных систем позволяют конфигурировать информационные системы по отдельности и имеют следующую структуру: - `ddcHowToVerifyStrings` - объект с пояснениями о процедуре проверки подписей, отображаемыми на формируемых Карточках электронных документов, ключами являются языки, в данный момент поддерживаются `"ru"` и `"kk"`; - `qrOrganisationName` - объект с названиями организации, отображаемыми в приложениях eGov mobile и eGov Business при подписании через QR и по ссылке, ключами являются языки, необходимо указывать три языка: `"ru"`, `"kk"` и `"en"`; - `qrLogo` - логотип для встраивания в центр QR кода при подписании через QR, должен быть в формате `PNG` (не более 102х102 пикселя) закодированный в `base64`; - `ddcLogo` - логотип отображаемый на формируемых карточках электронных документов, должен быть в формате `PNG` (точно 200x100 пикселей) закодированный в `base64`; - `ddcLogoString` - объект с подписями под логотипом отображаемым на формируемых карточках электронных документов, ключами являются языки, в данный момент поддерживаются `"ru"` и `"kk"`; - `ddcLogoDisable` - флаг позволяющий отключить нанесение логотипа на формируемые карточки электронных документов. Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру: - `authorities` - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа; - `tlsCertificatesIndices` - массив индексов сертификатов из `tlsCertificatesList`, определяет по каким сертификатам разрешен доступ; - `iins` - массив ИИНов сотрудников организации, которым необходимо предоставить доступ. Поле `webhooks` имеет следующую структуру: - `urls` - массив строк с URL для отправки [Webhook](/en/support/developers/notifications/index.md#notifications-webhook) уведомлений. Ответ: ```json { "businessId": "BIN123456789012", "modifiedAt": 1585827107000 } ``` - `businessId` - БИН организации; - `modifiedAt` - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. *** ## `GET` `/api/organizationSettingsAudit?lastEventId=X` - аудит изменений настроек организации {#organization-settings-audit} - `lastEventId=X` - опционально, последний идентификатор записи после которого нужно возвращать записи. Возвращает журнал изменений настроек организации. Ответ: ```json { "businessId": "BIN112233445566", "eventsTotal": 3, "events": [] } ``` - `businessId` - БИН организации; - `eventsTotal` - количество изменений зарегистрированных в системе; - `events` - массив объектов описывающих изменения. Структура объектов описывающих изменения: ```json { "eventId": 1, "original": {}, "modified": {}, "modifiedBy": "IIN123456789", "modifiedByDigest": "XXXXXXXXXXXXXXX", "modifiedAt": 1586167317737 } ``` - `eventId` - идентификатор события; - `original` - настройки до изменения; - `modified` - настройки после изменения; - `modifiedBy` - кем были произведены изменения, ИИН; - `modifiedByDigest` - хеш клиентского сертификата в том случае, если изменение было выполнено от имени информационной системы; - `modifiedAt` - момент изменения в миллисекундах с UNIX Epoch. *** ## `GET` `/api/organizationPermissions` - получить права аутентифицированного пользователя в разрезе его организации {#organization-permissions} Ответ: ```json { "documentsAccess": true, "documentsList": true, "documentsSettings": true, "organizationSettings": true } ``` - `documentsAccess` - имеет ли текущий аутентифицированный пользователь доступ к документам организации; - `documentsList` - имеет ли текущий аутентифицированный пользователь право перечислять документы организации; - `documentsSettings` - имеет ли текущий аутентифицированный пользователь право менять настройки документов организации; - `organizationSettings` - имеет ли текущий аутентифицированный пользователь право менять настройки организации. *** ## `GET` `/api/organizationSubscription` - получить сведения о текущем тарифном плане организации {#organization-subscription} Для доступа к обработчику необходимы права доступа к настройкам организации. Ответ: ```json { "name": "some subscription name", "expires": 1681900484242, "contactEmail": "subscription@example.com", "features": [ { "name": "some feature name", "enabled": true }, { "name": "another feature name", "enabled": true } ] } ``` - `name` - текущий уровень подписки на английском языке, переводы доступны в [`GET` `/api/strings` - перечень известных строк](/en/support/developers/api-other/index.md#strings) через `consts.subscriptions[name]`; - `expires` - опциональная дата окончания действия подписки (миллисекунды с UNIX Epoch), для подписок без срока действия (в том числе базового бесплатного) вернет `0`; - `contactEmail` - опциональный email адрес по которому сервис отправляет уведомления, связанные с подпиской; - `features` - массив объектов описывающих поддерживаемые сервисом функции: - `name` - имя функции на английском языке, переводы доступны в [`GET` `/api/strings` - перечень известных строк](/en/support/developers/api-other/index.md#strings) через `consts.subscriptionFeatures[name]`; - `enabled` - включена ли функция на данном уровне подписки.