• Введение
  • Отправка запросов и интерпретация ответов
  • Известные OIDы применяемые в НУЦ РК
• Аутентификация и контроль доступа
  • Аутентификация пользователей по цифровым сертификатам
  • Аутентификация информационных систем двусторонним mTLS
  • Контроль доступа
• Сообщения об ошибках
  • Перечень возможных сообщений об ошибках
• Уведомления
  • Уведомления по электронной почте
    • Базовые уведомления по электронной почте
    • Дополнительные уведомления по электронной почте запрашиваемые при регистрации подписей
    • Уведомления по электронной почте рассылаемые по запросу
  • Webhook
• Архивирование подписанных данных
• Методы API
  • POST /api - регистрация нового документа в системе
  • POST /api/{id}/data - фиксация значений хешей документа
  • GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе
  • GET /api/{id}/data - получение подписанных данных из архива
  • POST /api/{id} - добавление подписи к документу
  • POST /api/{id}/verify - проверка подписей
  • POST /api/{id}/notify - отправка уведомлений о документе
  • GET /api/{id}/signature/{signId}?signFormat=X&cmsAsPem=false - экспорт одной подписи документа
  • GET /api/{id}/signature/{signId}/qr?signFormat=X&qrVersion=25&qrLevel=M - экспорт подписи в виде набора QR кодов
  • POST /api/{id}/buildDDC?fileName=X&withoutDocumentVisualization=false&withoutSignaturesVisualization=false&withoutQRCodesInSignaturesVisualization=false&withoutID=false&qrWithIDLink=false&language=ru - формирование карточки электронного документа
  • POST /api/{id}/buildEzSigner - формирование CMS для сервиса ezSigner.kz
  • POST /api/{id}/settings - изменение настроек документа
  • GET /api/{id}/settingsAudit?lastEventId=X - аудит изменений настроек документа
  • GET /api/{id}/buildFileName?name=XXX - сформировать имя файла с идентификатором SIGEX
  • POST /api/{id}/egovQr - регистрация процедуры упрощенного подписания через QR или диплинки
  • GET /api/{id}/egovOperation/{operationId} - получение статуса процедуры подписания
  • DELETE /api/{id}/egovOperation/{operationId} - отмена процедуры подписания
  • POST /api/package - регистрация пакета документов
  • GET /api/package/{packageId} - получение данных о зарегистрированном пакете документов
  • POST /api/package/{packageId} - добавление подписей к документам пакета
  • POST /api/package/{packageId}/notify - отправка уведомлений о пакете документов
  • POST /api/package/{packageId}/settings - изменение настроек пакета документов
  • GET /api/package/{packageId}/settingsAudit?lastEventId=X - аудит изменений настроек пакета документов
  • POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки
  • GET /api/package/{packageId}/egovOperation/{operationId} - получение статуса процедуры подписания пакета документов
  • DELETE /api/package/{packageId}/egovOperation/{operationId} - отмена процедуры подписания пакета документов
  • POST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документа
  • POST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документа
  • POST /api/checkPDFForDDC - проверка PDF на возможность визуализации в карточке
  • POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данных
  • POST /api/auth - аутентификация
  • POST /api/auth - сброс аутентификации
  • GET /api/auth - текущее состояние аутентификации
  • GET /api?from=xxx&until=yyy&organization=true&dataArchived=true - перечисление документов аутентифицированного пользователя или системы
  • GET /api/package?from=xxx&until=yyy&organization=true - перечисление пакетов документов аутентифицированного пользователя или системы
  • GET /api/settings - получить настройки аутентифицированного пользователя
  • POST /api/settings - сохранить настройки аутентифицированного пользователя
  • GET /api/settingsAudit - аудит изменений настроек пользователя
  • GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя
  • POST /api/organizationSettings - сохранить настройки организации
  • GET /api/organizationSettingsAudit - аудит изменений настроек организации
  • GET /api/organizationPermissions - получить права аутентифицированного пользователя в разрезе его организации
  • GET /api/organizationSubscription - получить сведения о текущем тарифном плане организации
  • GET /api/idFromFileName/?name=XXX - получить идентификатор SIGEX из имени файла
  • GET /api/normalizeId/{specialId} - получить нормализованный идентификатор и его тип по специальному идентификатору
  • GET /api/externalServicesStats - статистика доступности сторонних сервисов
  • GET /api/strings - перечень известных строк
  • GET /api/version - версия сервиса
  • POST /api/egovQr - зарегистрировать новую процедуру подписания ЭЦП через QR
  • POST /api/egovQr/{qrId} - отправка данных на подписание
  • GET /api/egovQr/{qrId} - получение подписей

# Введение

Сервис SIGEX предоставляет публичный API по протоколу HTTPS на двух портах:

• 443 - аутентификация пользователей;
• 10443 - аутентификация информационных систем.

Отличия описаны в разделе Аутентификация и контроль доступа.

Статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы.

# Отправка запросов и интерпретация ответов

Кроме тех случаев, когда это явно указано, запросы сервису следует отправлять в формате JSON (с указанием типа содержимого application/json в заголовке Content-Type), сервис должен вернуть HTTP код 200 и ответ в виде JSON строки. Другой код HTTP свидетельствует о серьезной проблеме при обработке запроса, в этом случае нет смысла пробовать анализировать ответ.

Строки в JSON ответах сервиса всегда обрабатываются таким образом, чтобы JSON можно было безопасно встраивать в HTML в тег <script>. Для этого символы '<', '>', '&', U+2028 и U+2029 заменяются на '\u003c', '\u003e', '\u0026', '\u2028' и '\u2029' соответствено. Это не должно вызывать каких-либо неожиданных эффектов, так как по RFC 8259 любые символы в строках могут быть экранированы.

# Известные OIDы применяемые в НУЦ РК

Реестр OID и других спеифических строк доступен на странице Известные строки.

# Аутентификация и контроль доступа

Сервис поддерживает два механизма аутентификации:

• аутентификация пользователей по цифровым сертификатам - этот механизм подходит для тех случаев, когда действия выполнятся от имени пользователей (к примеру просмотр своих подписанных документов или документов сотрудников компании);
• аутентификация информационных систем двусторонним mTLS - этот механизм подходит для автоматизированных сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы (к примеру построение отчетов о подписанных документах по расписанию).

# Аутентификация пользователей по цифровым сертификатам

Этот способ аутентификации подходит для тех сценариев, когда действия предполагается выполнять от имени конкретных пользователей, к примеру:

• Система электронного документооборота (ЭДО) может использовать SIGEX как источник данных о цифровых подписях под документами пользователей. В этом случае после входа в свой профиль в ЭДО пользователи могут просматривать и редактировать настройки своего профиля в SIGEX, менять параметры своих подписанных документов в SIGEX. Для выполнения действий ЭДО обращается к сервису SIGEX от имени того пользователя, который запросил выполнение этого действия в ЭДО.
  sequenceDiagram participant B as Браузер пользователя participant D as Сервер ЭДО participant S as SIGEX B->>D: Пользователь запрашивает перечень
  подписей под документом в ЭДО D-->>S: ЭДО запрашивает у SIGEX перечень подписей
  под соответствующим подписанным документом S-->>D: SIGEX формирует ответ для ЭДО D->>B: ЭДО конвертирует данные и
  формирует ответ на запрос пользователя
• Веб интерфейс информационной системы может взаимодействовать с SIGEX напрямую, а не через свой сервер, это может быть удобно для тех систем, которым не требуется проверять цифровые подписи под электронными документами - к примеру системы обмена сообщениями или CRM системы могут отображать контекстную информацию о документах подписанных цифровой подписью.
  sequenceDiagram participant B as Браузер пользователя participant D as CRM система participant S as SIGEX B->>D: Пользователь открывает профиль клиента D->>B: В профиле клиента CRM система
  приводит перечень договоров с клиентом B-->>S: Браузер пользователя запрашивает
  информацию о подписях под договорами S-->>B: SIGEX предоставляет информацию
  и в профиле автоматически отображается информация о подписях
• Информационные системы могут внедрять аутентификацию по цифровым сертификатам (к примеру вход в личный кабинет пользователя по цифровому сертификату) используя данный механизм аутентификации в режиме внешней аутентификации, преимущества такого подхода:
  • регистрация новых пользователей не обязательна, они могут сразу входить в систему;
  • идентификация пользователей по ИИН;
  • при необходимости привязка к БИН;
  • простая реализация минимизирует вероятность обнаружения уязвимостей.

Аутентификация пользователей по цифровым сертификатам основана на подписании пользователем блока случайных данных (nonce) и последующей проверке этой подписи. В том случае, если подпись верна, сервис может быть уверен в том, что пользователь обладает закрытым ключом соответствующим открытому ключу в сертификате (регистрационном свидетельстве).

За данный режим аутентификации отвечают следующие API:

• POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данных
• POST /api/auth - аутентификация
• POST /api/auth - сброс аутентификации - не используется в режиме внешней аутентификации
• GET /api/auth - текущее состояние аутентификации - не используется в режиме внешней аутентификации

Отличительной особенностью режима внешней аутентификации является то, что в этом режиме сервис SIGEX не устанавливает в своих ответах cookie с JWT токенами содержащими информацию о пользователе прошедшем аутентификацию. Детали приведены в POST /api/auth - аутентификация.

Вводная статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы в режиме внешней аутентификации.

# Аутентификация информационных систем двусторонним mTLS

Этот способ аутентификации подходит для тех сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы, к примеру:

• автоматизированный экспорт подписей из SIGEX в локальную БД;
• анализ и построение отчетов о документах организации;
• построение отчетов о действиях сотрудников организации (кто что и когда подписывал).

В случае использования этого механизма, с точки зрения SIGEX информационная система будет действовать от имени организации, а не какого-то определенного ее представителя.

Данный механизм аутентификации доступен на отдельном порту https://sigex.kz:10443 и требует предоставления клиентского сертификата https://ru.wikipedia.org/wiki/HTTPS#Идентификация_клиента. Практически все API, доступные на стандартном порту https://sigex.kz, без изменений доступны и тут. Исключение составляют API аутентификации по цифровым сертификатам, тут они не работают.

Важный нюанс: реализация данного механизма аутентификации основана на сертификатах только по той причине, что в mTLS не предусмотрено аутентификации по открытым ключам, фактически сервис анализирует только открытый ключ содержащийся в сертификате, остальные поля не учитываются.

Для того, чтобы использовать аутентификацию информационных систем двусторонним mTLS необходимо:

• опционально самостоятельно сгенерировать клиентский mTLS сертификат для информационной системы (это можно сделать автоматически в следующем пункте);
• добавить сертификат информационной системы в настройках организации в необходимые этой информационной системе списки контроля доступа;
• на сервере информационной системы в качестве URL для доступа к API SIGEX использовать https://sigex.kz:10443;
• настроить использование двустороннего mTLS при взаимодействии с API SIGEX на сервере информационной системы с использованием указанного ранее сертификата и соответствующего закрытого ключа.

Поддерживаемые протоколы:

• TLS 1.3.

Допустимые длины ключей:

• RSA не короче 2048 бит;
• ECDSA не короче 224 бит.

# Контроль доступа

Определены следующие типы прав доступа:

• просмотр информации о документе и настроек документа;
• получение подписанных данных документа из архива;
• изменение настроек документа;
• перечисление документов;
• просмотр информации о пакете документов и его настроек;
• изменение настроек пакета документов;
• перечисление пакетов документов;
• просмотр/изменение настроек организации;
• просмотр/изменение настроек пользователя.

Полномочия первого руководителя всегда присутствуют во всех блоках контроля доступа настроек организации (POST /api/organizationSettings - сохранить настройки организации). Таким образом первый руководитель всегда имеет доступ к документам, пакетам документов и настройкам организации.

# Просмотр информации о документе и настроек документа

Документ может быть публично доступным, либо с ограниченным доступом, это определяет параметр private в настройках документа (см. POST /api/{id}/settings - изменение настроек документа).

В том случае, если документ был предрегистрирован и флаг publicDuringPreregistration был установлен в true, то доступ к информации о документе может получить любой кто знает идентификатор документа до тех пор пока под ним не будет зарегистрирована первая подпись. После регистрации первой подписи он будет обрабатываться как обычный документ.

# Получение подписанных данных документа из архива

Доступ к подписанным данным документа предоставляется аналогично доступу к информации о документе, но с ограничением - он возможен только аутентифицированным пользователям и информационным системам (за исключением специального режима активируемого флагом publicDuringPreregistration, в этом случае аутентификация не требуется).

В том случае, если документ был предрегистрирован и флаг publicDuringPreregistration был установлен в true, то доступ к подписываемым данным может получить любой кто знает идентификатор документа до тех пор пока под ним не будет зарегистрирована первая подпись. После регистрации первой подписи он будет обрабатываться как обычный документ.

# Изменение настроек документа

# Перечисление документов

API перечисления документов (GET /api?from=xxx&until=yyy&organization=true&dataArchived=true - перечисление документов аутентифицированного пользователя или системы) с помощью параметра organization позволяет указывать какие документы следует перечислять:

• Документы пользователя (их возможно перечислять после прохождения аутентификации по сертификату физического, либо юридического лица) - это документы, подписанные пользователем, как физическим лицом, либо представителем юридического лица.
• Документы юридического лица (их возможно перечислять после прохождения аутентификации по сертификату юридического лица, либо информационной системой по двустороннему mTLS) - это документы, подписанные сотрудниками той же организации, что пользователь или информационная система, а так же зарегистрированные информационными системами этой же организации.

Во втором случае следует установить organization=true в запросе.

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

Перечисление документов юридического лица:

# Просмотр информации о пакете документов и его настроек

Пакет документов может быть публично доступным, либо с ограниченным доступом, это определяет параметр private в настройках пакета документов (см. POST /api/package/{packageId}/settings - изменение настроек пакета документов).

# Изменение настроек пакета документов

# Перечисление пакетов документов

API перечисления пакетов документов (GET /api/package?from=xxx&until=yyy&organization=true - перечисление пакетов документов аутентифицированного пользователя или системы) с помощью параметра organization позволяет указывать какие пакеты документов следует перечислять:

• Пакеты документов пользователя (их возможно перечислять после прохождения аутентификации по сертификату физического, либо юридического лица) - это пакеты документов в настройках которых пользователь указан в packageAccess как физическое лицо или сотрудник юридического лица.
• Пакеты документов юридического лица (их возможно перечислять после прохождения аутентификации по сертификату юридического лица, либо информационной системой по двустороннему mTLS) - это пакеты документов в настроках которых в packageAccess указан БИН юридического лица, а так же зарегистрированные информационными системами этой же организации.

Во втором случае следует установить organization=true в запросе.

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

Перечисление пакетов документов юридического лица:

# Просмотр/изменение настроек организации

Просматривать и изменять настройки организации могут:

• в том случае, если выполнена аутентификация по сертификату сотрудника юридического лица, то в этом сертификате должно присутствовать полномочие приведенное в блоке organizationSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации), либо ИИН в сертификате должен совпадать с одним из указанных в блоке organizationSettings;
• в том случае, если выполнена аутентификация информационных систем двусторонним mTLS, то сертификат использованный при аутентификации должен быть указан в блоке organizationSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации).

# Просмотр/изменение настроек пользователя

Просматривать и изменять свои настройки может пользователь, выполнивший аутентификацию как по сертификату физического лица, так и сотрудника юридического лица.

# Сообщения об ошибках

При возникновении ошибок все методы API возвращают сообщение об ошибке следующего формата:

{
  "message": "Request processing error",
  "requestID": 1570108542768139099
}

• message - текст сообщения об ошибке на английском языке;
• requestID - идентификатор запроса.

# Перечень возможных сообщений об ошибках

Реестр сообщений об ошибках и других спеифических строк доступен на странице Известные строки.

# Уведомления

В сервисе реализованы уведомления по следующим каналам:

• по электронной почте - предназначены для информирования пользователей;
• Webhook - предназначены для информационных систем.

# Уведомления по электронной почте

Уведомления по электронной почте могут рассылаться автоматически, а так же по запросу.

# Базовые уведомления по электронной почте

Поддерживаются следующие типы базовых уведомлений по электронной почте (email):

1. уведомления о подписании нового документа;
2. уведомления о добавлении подписи к документу;
3. уведомления о добавлении подписи к документу, подписанному пользователем;
4. уведомление о превышении квоты архива подписанных данных;
5. уведомление об истечении срока действия квоты архива подписанных данных;
6. уведомления о предрегистрации документа;
7. уведомления о регистрации нового пакета документов.

Сервис рассылает уведомления о подписании нового документа (1) тем получателям, которые были указаны в массиве emailNotifications.to при регистрации документа с помощью POST /api - регистрация нового документа в системе. Рассылаемые электронные письма содержат ссылки на страницу подписанного документа, а так же к ним прикреплены подлинники подписанных документов (можно отключить с помощью флага doNotAttachDocument). Подлинник подписанного документа может быть не прикреплен к письму в том случае, если прикрепляемый файл не прошел проверку антивирусным программным обеспечением, либо если он большого размера.

В том случае, если используется функция предрегистрации, то сервис отправляет уведомления о предрегистрации документа (6). Эти уведомления подобны уведомлениям о подписании нового документа (1), но не содержат информации о том, кто первым подписал документ, вместо этого они содержат информацию о том, какая организация отправила документ на подписание.

Так же каждому пользователю, подписавшему какой-либо документ, сервис отправляет уведомление в том случае, если к этому документу была добавлена подпись - это уведомления о добавлении подписи к документу, подписанному пользователем (3). В этом случае электронные письма содержат ссылку на страницу подписанного документа и информацию о том, кто добавил подпись, подлинник подписанного документа к письму не прикрепляется. Адреса для отправки этих уведомлений сервис берет из настроек пользователей (поле email в POST /api/settings - сохранить настройки аутентифицированного пользователя), которых сервис идентифицирует по ИИН. По умолчанию в настройки заносится тот адрес электронной почты, который был указан в сертификате, который пользователь использовал первый раз для подписания документа на сервисе, либо аутентификации. Эта опция отключена по умолчанию, для того, чтобы получать эти уведомления, пользователям нужно активировать ее в своих настройках.

Помимо этого сервис рассылает уведомления о новых подписях под документами на те адреса электронной почты, которые были указаны при регистрации документа - уведомления о добавлении подписи к документу (2).

Рассмотрим пример:

• при регистрации нового документа были указаны два адреса электронной почты 1@example.com и 2@example.com, первым подписал документ пользователь, у которого в настройках указан адрес me@example.com;
• сервис отправил уведомления о новых документах (1) на адреса 1@example.com и 2@example.com;
• далее пользователь, у которого в настройках указан адрес other@example.com, добавил подпись к этому документу;
• сервис отправил одно уведомление о добавлении подписи (3) на адрес me@example.com и два уведомления о добавлении подписи (2) на адреса 1@example.com и 2@example.com;
• после этого пользователь, у которого в настройках указан адрес 1@example.com, тоже добавил подпись к этому документу;
• сервис отправил два уведомления о добавлении подписи (3) на адрес me@example.com и other@example.com и одно уведомление о добавлении подписи (2) на адрес 2@example.com.

Таким образом все заинтересованные стороны получают актуальную информацию о состоянии своих подписанных документов.

При регистрации пакета документов сервис рассылает уведомления о регистрации нового пакета документов (7) тем получателям, которые были указаны в массиве emailNotifications.to POST /api/package - регистрация пакета документов. Рассылаемые электронные письма содержат ссылки на страницу пакета документов, а так же к ним прикреплены подлинники подписанных документов (можно отключить с помощью флага doNotAttachDocuments). Подлинники подписанных документов могут быть не прикреплены к письму в том случае, если прикрепляемые файлы не прошли проверку антивирусным программным обеспечением, либо если они большого размера. Так же подлинники подписанных документов не будут прикреплены к письму в том случае, если они не находятся в архиве.

Уведомления, связанные с архивированием подписанных данных - уведомление о превышении квоты архива подписанных данных (4) и уведомление об истечении срока действия квоты архива подписанных данных (5), сервис рассылает на отдельные адреса электронной почты указанные в поле dataArchiveContactEmail в ностройках пользователей (POST /api/settings - сохранить настройки аутентифицированного пользователя) и организаций (POST /api/organizationSettings - сохранить настройки организации).

# Дополнительные уведомления по электронной почте запрашиваемые при регистрации подписей

Предусмотрена возможность отправки уведомлений по электронной почте на произвольные адреса при регистрации подписей под документами и пакетами документов следующими вызовами:

• POST /api/{id} - добавление подписи к документу
• POST /api/package/{packageId} - добавление подписей к документам пакета

За отправку уведомлений отвечает поле signatureEmailNotifications.

# Уведомления по электронной почте рассылаемые по запросу

С помощью следующих вызовов можно запросить отправку уведомлений на произвольные адреса в произвольный момент времени:

• POST /api/{id}/notify - отправка уведомлений о документе
• POST /api/package/{packageId}/notify - отправка уведомлений о пакете документов

# Webhook уведомления

Для информирования интегрированных систем и приложений о новых зарегистрированных в SIGEX подписях можно использовать механизм Webhook уведомлений. Параметры рассылки Webhook уведомлений настраиваются индивидуально для каждой организации в настройках соответствующей организации (POST /api/organizationSettings - сохранить настройки организации).

Сервис отправляет POST запросы на указанные в настройках организации URL, тело запроса будет содержать идентификаторы пакета документов, документа и подписи в формате JSON:

{
  "packageId": "xxx",
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 123
}

• packageId - опциональное поле, идентификатор пакета документов, присутствует только в том случае, если уведомление относится ко всему пакету документов или к документу из пакета документов;
• documentId - опциональное поле, идентификатор документа, отсутствует в том случае, если уведомление относится к действию над всем пакетом;
• signId - опциональное поле, идентификатор подписи, отсутствует в том случае, если уведомление относится к действию над всем пакетом.

Получателю следует ответить HTTP кодом 200 (Success) с пустым телом. В том случае, если отправить запрос не удастся, либо получатель ответит иным кодом, сервис попробует повторно отправить запрос через некоторый промежуток времени.

Сервис отправляет Webhook уведомления о новой зарегистрированной подписи в том случае, если:

• Webhook уведомления настроены для организации, сертификат сотрудника юридического лица которой был использован для формирования регистрируемой подписи;
• новая подпись добавлена к документу уже подписанному сотрудником организации, для которой настроены Webhook уведомления;
• новая подпись добавлена к документу зарегистрированному информационной системой организации, для которой настроены Webhook уведомления.

Рассмотрим пример:

• у организации A настроена отправка Webhook уведомлений по URL https://a.kz/webhooks
• у организации B настроена отправка Webhook уведомлений по URL https://b.kz/webhooks
• сотрудник организации A подписывает документ, идентификатор документа D1, идентификатор подписи S-A
• сервис отправляет Webhook уведомление с идентификатором документа D1 и идентификатором подписи S-A по URL одному https://a.kz/webhooks
• сотрудник организации B добавляет подпись к документу D1, идентификатор новой подписи S-B
• сервис отправляет Webhook уведомление с идентификатором документа D1 и идентификатором подписи S-B по URL двум https://a.kz/webhooks и https://b.kz/webhooks
• физическое лицо добавляет подпись к документу D1, идентификатор новой подписи S-P
• сервис отправляет Webhook уведомление с идентификатором документа D1 и идентификатором подписи S-P по URL двум https://a.kz/webhooks и https://b.kz/webhooks

# Архивирование подписанных данных

В сервисе реализована опциональная функция архивирования подписанных данных, именно тех электронных документов (или просто файлов), которые были подписаны электронной цифровой подписью. Данные хранятся в архиве бессрочно, изменять, либо удалять данные в архиве невозможно. Функция может быть полезна, к примеру, в следующих сценариях:

• для предприятий - в качестве архива электронных документов, под которыми присутствуют подписи сотрудников компании;
• для разработчиков и операторов систем, порталов и приложений - для обеспечения сохранности и неизменности подлинников электронных документов в отдельном независимом хранилище;
• для физических лиц - в качестве архива электронных документов, подписанных, как в качестве физического лица, так и в качестве сотрудника различных компаний.

Активировать функцию архивирования подписанных данных нужно в настройках пользователя или организации, по умолчанию она отключена. В том случае, если функция включена в настройках пользователя, то сервис будет архивировать все документы, которое подписывает этот пользователь как физическое лицо. В том случае, если функция архивирования включена в настройках организации, то сервис будет архивировать все документы подписанные сотрудниками соответствующего юридического лица.

Так же доступна опция принудительного архивирования определенного документа с помощью параметра forceArchive настроек документа: POST /api/{id}/settings - изменение настроек документа, этот параметр можно указывать только на этапе первоначальной регистрации/предрегистрации документа.

Архивирование данных выполняется автоматически (в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота) в рамках обработки следующих API:

• POST /api/{id}/data - фиксация значений хешей документа
• POST /api/{id}/verify - проверка подписей
• POST /api/{id}/buildDDC?fileName=X&withoutDocumentVisualization=false&withoutSignaturesVisualization=false&withoutQRCodesInSignaturesVisualization=false&withoutID=false&qrWithIDLink=false&language=ru - формирование карточки электронного документа
• POST /api/{id}/buildEzSigner - формирование CMS для сервиса ezSigner.kz
• POST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документа

Единственное техническое требование - наличие HTTP заголовка Content-Length с корректным размером данных, большинство библиотек для работы с HTTP устанавливают этот заголовок автоматически.

Отдельного выделенного API для архивирования данных не предусмотрено, в том случае, если необходимо добавить в архив данные уже зарегистрированного документа (к примеру для того, чтобы добавить в архив ранее подписанные документы после включения архивирования), можно воспользоваться POST /api/{id}/verify - проверка подписей.

Для получения данных из архива следует использовать API GET /api/{id}/data - получение подписанных данных из архива.

Определить, добавлены ли данные в архив, можно по полю dataArchived в ответах API, выполняющих архивирование данных, а так же [GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе] и GET /api?from=xxx&until=yyy&organization=true&dataArchived=true - перечисление документов аутентифицированного пользователя или системы.

Для каждого пользователя и организации существует квота, ограничивающая объем соответствующего архива. Информация о квотах и способах их увеличения доступна на странице Для корпоративных клиентов. Текущую квоту и объем данных в архиве можно получить с помощью GET /api/settings - получить настройки аутентифицированного пользователя и GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя.

Для информирования пользователей о событиях, связанных с архивированием, предусмотрены специальные уведомления, рассылаемые по электронной почте. Эти уведомления рассылаются на отдельный настраиваемый адрес электронной почты, указанный в поле dataArchiveContactEmail, настраиваемый через POST /api/settings - сохранить настройки аутентифицированного пользователя и POST /api/organizationSettings - сохранить настройки организации.

# Методы API

Коллекции для Postman:

• ЭЦП через QR на базе eGov mobile
• Регистрация документа и подписей
• Добавление подписи к документу
• Аутентификация по ЭЦП

# POST /api - регистрация нового документа в системе

Важно! Регистрация документа не будет завершена до успешного вызова POST /api/{id}/data - фиксация значений хешей документа.

В рамках регистрации нового документа и его первой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.

Сервис допускает регистрацию двух типов подписей:

• CMS - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics или методом createCAdESFromBase64;
• XML - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics или методом signXml, но в обоих случаях с некоторыми оговорками (см. ниже).

JS библиотека с открытым исходным кодом https://github.com/sigex-kz/ncalayer-js-client поддерживает все эти варианты.

CMS подписи могут включать в себя подписанные данные (рекомендуется не включать данные в подпись, так как у сервиса есть ограничение на размер принимаемых данных для этого вызова), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).

В том случае, если переданная CMS подпись содержит подписанные данные, эти данные перед сохранением будут извлечены из подписи.

CMS подписи поддерживаются в DER и PEM кодировках.

Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.

Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.

Под XML подписью сервис подразумевает только ту часть XML, которая содержит данные о подписи - то есть только элемент <ds:Signature xmlns:ds=“http://www.w3.org/2000/09/xmldsig#">. В том случае, если подпись была сформирована с помощью вызова signXml утилиты NCALayer, то корректное извлечение необходимого элемента и оформление его в соответствии с https://www.w3.org/TR/xmldsig-core1 ложится на плечи разработчика.

Так же при регистрации нового документа можно запросить отправку уведомлений по электронной почте нескольким получателям. Эта функция может быть полезна в том случае, если документ должен быть подписан несколькими лицами - первый подписавший таким образом может запросить отправку уведомлений всем остальным. В сервисе реализовано ограничение на количество адресов. Отправка уведомлений сервисом осуществляется после завершения регистрации документа вызовом POST /api/{id}/data.

Функция предрегистрации позволяет регистрировать документы без подписей (без поля signature), но она доступна только информационным системам прошедшим аутентификацию по двустороннему mTLS. Данная функция позволяет отправить документ на подписание внешнему контрагенту первому вместо того, чтобы сначала подписывать документ со своей стороны, потом регистрировать его и только после этого внешний контрагент получит уведомление с вложенным документом и ссылкой на страницу подписанного документа. Так же в этом случае сервис отправляет уведомления по электронной почте (см. Уведомления по электронной почте) специального типа.

В случае использования функции предрегистрации доступен специальный режим контроля доступа к документу и подписываемым данным (см. Контроль доступа), для активации этого режима следует установить флаг настроек документа publicDuringPreregistration в true. В этом режиме до регистрации первой подписи под документом информация о документе и подписываемые данные доступны всем без ограничений, это реализовано для того, чтобы внешним контрагентам было проще подписывать документы.

Попробовать этот API в Postman

Запрос (Content-Type необходимо установить в application/json):

{
  "title": "document title",
  "description": "document description",
  "signType": "cms",
  "signature": "signature",
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocument": false
  },
  "settings": {
    "private": false,
    "signaturesLimit": 2,
    "switchToPrivateAfterLimitReached": true,
    "unique": ["iin"],
    "strictSignersRequirements": false,
    "signersRequirements": [
      {
        "iin": "IIN112233445566"
      }
    ],
    "publicDuringPreregistration": false,
    "documentAccess": [],
    "forceArchive": false
  }
}

• title - опциональное поле, заголовок документа (так как значение этого поля в некоторых случаях интерпретируется как имя файла, то его содержимое должно соответствовать требованиям, предъявляемым к именам файлов);
• description - опциональное поле, описание документа;
• signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
• signature - опциональное поле (см. выше про предрегистрацию), в случае CMS это должна быть подпись в кодировке DER дополнительно закодированная в base64, либо в кодировке PEM без дополнительного кодирования, в случае XML - текстовое представление XML;
• emailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о подписании документа с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocument - опциональное поле, позволяет отправлять уведомления без прикрепленного документа, по умолчанию false;
• settings - опциональное поле, объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 123,
  "data": "MTEK"
}

• documentId - уникальный идентификатор зарегистрированного документа;
• signId - уникальный идентификатор добавленной подписи;
• data - опциональное поле, извлеченные из CMS подписанные данные в виде base64 строки, присутствует только в том случае, если переданная в запросе подпись включала подписанные данные.

# POST /api/{id}/data - фиксация значений хешей документа

• {id} - идентификатор документа.

Сервис SIGEX, по умолчанию, не хранит подписанных документов и ему необходим какой-то способ определить относятся ли две подписи к одному и тому же документу. В том случае, когда алгоритмы подписей идентичны, это просто - в подписях присутствуют хеши документа и достаточно требовать их идентичности. В том же случае, если алгоритмы подписей отличаются, то и значения хешей не будут совпадать, так как они вычисляются по разным алгоритмам.

Отличаться алгоритмы подписей могут в том случае, когда один и тот же документ подписывают юридическое лицо (НУЦ выпускает в этом случае сертификаты ГОСТ 34.310-2004) и физическое лицо (НУЦ выпускает сертификаты RSA).

Выбранное нами решение - попросить передать сервису подписанный документ один раз для завершения его регистрации в системе. SIGEX вычислит все необходимые значения хешей и сохранит их в своей базе данных. Содержимое переданного документа сохранено не будет.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.

В качестве тела запроса следует передать оригинальный документ.

В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.

В том случае, если при регистрации документа было указано поле emailNotifications с не пустым списокм получателей, то сервис попробует отправить уведомления получателям по электронной почте. В том случае, если размер документа не большой (ограничение определяется почтовой системой), то сервис прикрепит документ к отправляемым уведомлениям. О том, был ли прикреплен документ к отправленным уведомлениям, сигрализирует значение поля emailNotifications.attached в ответе.

При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.

Попробовать этот API в Postman

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signedDataSize": 0,
  "digests": {
    "oid": "base64_encoded_digest_value",
    "otherOid": "base64_encoded_digest_value",
  },
  "emailNotifications": {
    "attached": true,
    "message": "Failed to send  notification"
  },
  "automaticallyCreatedUserSettings": {},
  "automaticallyCreatedOrgSettings": {},
  "dataArchived": false
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0);
• digests - объект, содержащий вычисленные значения хешей;
• emailNotifications - опциональное поле, присутствует только в том случае, если при регистрации документа было указано аналогичное поле с не пустым списком получателей, его поле attached говорит о том, был ли прикреплен документ к отправленным уведомлениям, поле message присутствует только в том случае, если в процессе отправки уведомлений произошла ошибка и описывает эту ошибку;
• automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings - получить настройки аутентифицированного пользователя;
• automaticallyCreatedOrgSettings - опциональное поле, присутствует только в том случае, если сотрудник огранизации (идентифицируется по БИН) первый раз регистрирует подпись на сервисе, информирует о том, что сервис создал запись с настройками данной организации, содержимое идентично GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве.

# GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе

• {id} - идентификатор документа;
• lastSignId=X - опционально, последний идентификатор подписи после которого нужно возвращаться подписи.

Следует учитывать то, что данная функция возвращает ограниченное количество подписей - то есть в том случае, если подписей много, то за один вызов их получить не получится.

Алгоритм получения всех подписей:

1. получить первый блок подписей не указывая lastSignId;
2. получить следующий блок подписей установив lastSignId=signId из последнего элемента массива подписей;
3. повторять до тех пор пока сервис не вернет пустой массив.

Попробовать этот API в Postman

Ответ:

{
  "title": "document title",
  "description": "document description",
  "signedDataSize": 0,
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocument": false
  },
  "signatureEmailNotifications": [
    {
      "signId": 1,
      "doNotAttachDocument": false,
      "to": ["user@example.com","otherUser@example.com"]
    },
    {
      "signId": 2,
      "doNotAttachDocument": true,
      "to": ["3@example.com","4@example.com"]
    },
  ],
  "settings": {
    "private": false,
    "signaturesLimit": 2,
    "switchToPrivateAfterLimitReached": true,
    "unique": ["iin"],
    "strictSignersRequirements": false,
    "signersRequirements": [
      {
        "iin": "IIN112233445566"
      }
    ],
    "publicDuringPreregistration": false,
    "documentAccess": [],
    "forceArchive": false
  },
  "signaturesTotal": 2,
  "signatures": [
  ],
  "dataArchived": false,
  "canBeArchived": true,
  "registrator": {
    "businessId":"BIN012345678901",
    "certificate":"base64_encoded_mtls_certificate"
  }
}

• title - заголовок документа;
• description - описание документа;
• signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0);
• emailNotifications - информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации документа;
• signatureEmailNotifications - массив объектов, информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации подписей;
• settings - объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа;
• signaturesTotal - общее количество подписей документа;
• signatures - массив объектов с данными о подписях документа;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве;
• canBeArchived - информирует о том, что документ может быть добавлен в архив (такая ситуация может возникнуть если в настройках первого подписавшего архивирование отключено, но включено у кого-то из других подписавших), для того, чтобы добавить документ в архив, следует использовать POST /api/{id}/verify - проверка подписей;
• registrator - опциональное поле, информация об информационной системе, зарегистрировавшей документ (БИН и mTLS сертификат в base64), присутствует только в том случае, если регистрация (либо предрегистрация) документа была выполнена аутентифицированной информационной системой.

Структура объекта данных подписи:

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "subject": "SERIALINUMBER=IIN1234567890AB,CN=User",
  "subjectStructure": [
    [
      {
        "oid": "2.5.4.5",
        "name": "SERIALINUMBER",
        "valueInB64": false,
        "value": "IIN1234567890AB"
      }
    ],
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "User"
      }
    ]
  ],
  "subjectAltName": "rfc822Name=user@example.com",
  "subjectAltNameStructure": [
    {
      "type": "rfc822Name",
      "value": "user@example.com"
    }
  ],
  "certSignAlgorithm": "1.2.840.113549.1.1.11",
  "serialNumber": "4beb939d4fb14b047f3bcddf3881eb2ff9acbeb5",
  "from": 1535622190000,
  "until": 1630120980000,
  "issuer": "C=KZ,CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)",
  "issuerStructure": [
    [
      {
        "oid": "2.5.4.6",
        "name": "C",
        "valueInB64": false,
        "value": "KZ"
      }
    ],
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)"
      }
    ]
  ],
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "keyStorage": "1.2.398.3.3.5.1.1",
  "policyIds": ["OID.0","OID.1"],
  "keyUsages": ["digitalSignature", "nonRepudiation"],
  "extKeyUsages": ["OID.0","OID.1"],
  "storedAt": 1568809427182,
  "signId": 1,
  "signType": "cms",
  "tsp": {},
  "ocsp": {}
}

• userId - ИИН подписавшего;
• businessId - БИН подписавшего, доступен только в случае использования сертификата юридического лица;
• subject - имя владельца (Subject) сертификата сформированное в соответствии с RFC 4514;
• subjectStructure - структурированное представление имени владельца (Subject) сертификата;
• subjectAltName - альтернативное имя владельца сертификата в соответствии с RFC 4514 (опциональное поле);
• subjectAltNameStructure - структурированное представление альтернативного имени владельца сертификата (опциональное поле);
• certSignAlgorithm - OID алгоритма подписи сертификата;
• serialNumber - серийный номер сертификата;
• from - начало срока действия сертификата;
• until - окончание срока действия сертификата;
• issuer - имя издателя (Issuer) сертификата сформированное в соответствии с RFC 4514;
• issuerStructure - структурированное представление имени издателя (Issuer) сертификата;
• signAlgorithm - OID алгоритма подписи;
• keyStorage - OID типа хранилища (опциональное поле);
• policyIds - массив OID-ов политик использования сертификата подписавшего;
• keyUsages - массив строк использования ключа (в соответствии с https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3);
• extKeyUsages - массив OID-ов расширенного использования ключа;
• storedAt - время сохранения подписи в системе (миллисекунд с UNIX Epoch);
• signId - уникальный идентификатор подписи в системе;
• signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
• tsp - структура метки времени TSP (опциональное поле);
• ocsp - структура OCSP ответа о статусе сертификата (опциональное поле).

Структура метки времени TSP:

{
  "timeStamp": 1621518969000,
  "timeStampPolicy": "1.2.398.3.3.2.6.2",
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "certSignAlgorithm": "1.2.840.113549.1.1.11",
  "serialNumber": "3d9de56d5f379c5d06ec7d8b83aa50bdeb437d34",
  "from": 1576128125000,
  "until": 1670736125000,
  "subject": "CN=TSA SERVICE,C=KZ",
  "subjectStructure": [
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "TSA SERVICE"
      }
    ],
    [
      {
        "oid": "2.5.4.6",
        "name": "C",
        "valueInB64": false,
        "value": "KZ"
      }
    ]
  ],
  "issuer": "C=KZ,CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)",
  "issuerStructure": [
    [
      {
        "oid": "2.5.4.6",
        "name": "C",
        "valueInB64": false,
        "value": "KZ"
      }
    ],
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)"
      }
    ]
  ],
  "policyIds": [],
  "keyUsages": [],
  "extKeyUsages": [
    "1.3.6.1.5.5.7.3.8"
  ]
}

• timeStamp - метка времени (миллисекунды с UNIX Epoch);
• timeStampPolicy - OID политики выпуска метки времен;
• signAlgorithm - OID алгоритма подписи;
• certSignAlgorithm - OID алгоритма подписи сертификата, использованного УЦ для подписания метки времени;
• serialNumber - серийный номер сертификата, использованного УЦ для подписания метки времени;
• from - начало срока действия сертификата, использованного УЦ для подписания метки времени;
• until - окончание срока действия сертификата, использованного УЦ для подписания метки времени.
• subject - имя владельца (Subject) сертификата, использованного УЦ для подписания метки времени, сформированное в соответствии с RFC 4514;
• subjectStructure - структурированное представление имени владельца (Subject) сертификата, использованного УЦ для подписания метки времени;
• issuer - имя издателя (Issuer) сертификата, использованного УЦ для подписания метки времени, сформированное в соответствии с RFC 4514;
• issuerStructure - структурированное представление имени издателя (Issuer) сертификата, использованного УЦ для подписания метки времени;
• policyIds - массив OID-ов политик использования сертификата, использованного УЦ для подписания метки времени;
• keyUsages - массив строк использования ключа (в соответствии с https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3) сертификата, использованного УЦ для подписания метки времени;
• extKeyUsages - массив OID-ов расширенного использования ключа сертификата, использованного УЦ для подписания метки времени.

Структура OCSP ответа о статусе сертификата:

{
  "producedAt": 1621518968000,
  "thisUpdate": 1621518968000,
  "certStatus": "good",
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "certSignAlgorithm": "1.2.840.113549.1.1.11",
  "serialNumber": "1dd4d03a63db59beea1375d34908fd6655e7e4a9",
  "from": 1607001246000,
  "until": 1638537246000,
  "subject": "CN=OCSP RESPONDER,C=KZ",
  "subjectStructure": [
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "OCSP RESPONDER"
      }
    ],
    [
      {
        "oid": "2.5.4.6",
        "name": "C",
        "valueInB64": false,
        "value": "KZ"
      }
    ]
  ],
  "issuer": "C=KZ,CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)",
  "issuerStructure": [
    [
      {
        "oid": "2.5.4.6",
        "name": "C",
        "valueInB64": false,
        "value": "KZ"
      }
    ],
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)"
      }
    ]
  ],
  "policyIds": [],
  "keyUsages": [],
  "extKeyUsages": [
    "1.3.6.1.5.5.7.3.9"
  ]
}

• producedAt - момент формирования ответа сервером УЦ (миллисекунды с UNIX Epoch);
• thisUpdate - дата с которой можно считать предоставленную информации о статусе сертификата актуальной (миллисекунды с UNIX Epoch);
• nextUpdate - дата до которой можно считать предоставленную информации о статусе сертификата актуальной (миллисекунды с UNIX Epoch)(опциональное поле);
• certStatus - строка, должна быть "good", так как сервис не принимает подписи для которых не удалось получить ответа с хорошим статусом;
• signAlgorithm - OID алгоритма подписи;
• certSignAlgorithm - OID алгоритма подписи сертификата, использованного УЦ для подписания ответа;
• serialNumber - серийный номер сертификата, использованного УЦ для подписания ответа;
• from - начало срока действия сертификата, использованного УЦ для подписания ответа;
• until - окончание срока действия сертификата, использованного УЦ для подписания ответа.
• subject - имя владельца (Subject) сертификата, использованного УЦ для подписания ответа, сформированное в соответствии с RFC 4514;
• subjectStructure - структурированное представление имени владельца (Subject) сертификата, использованного УЦ для подписания ответа;
• issuer - имя издателя (Issuer) сертификата, использованного УЦ для подписания ответа, сформированное в соответствии с RFC 4514;
• issuerStructure - структурированное представление имени издателя (Issuer) сертификата, использованного УЦ для подписания ответа;
• policyIds - массив OID-ов политик использования сертификата, использованного УЦ для подписания ответа;
• keyUsages - массив строк использования ключа (в соответствии с https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3) сертификата, использованного УЦ для подписания ответа;
• extKeyUsages - массив OID-ов расширенного использования ключа сертификата, использованного УЦ для подписания ответа.

Структурированные представления имен владельца (Subject) сертификата и издателя (Issuer) сертификата - это массивы, содержащий набор RDN, каждый из которых, в свою очередь, является массивом аттрибутов. Представление основывается на структуре поля Subject сертификата, описанного в RFC 5280.

Каждый атрибут представлен в виде объекта:

{
  "oid": "2.5.4.3",
  "name": "CN",
  "valueInB64": false,
  "value": "User CommonName",
}

• oid - объектный идентификатор типа атрибута;
• name - тестовое представление типа атрибута в соответствии со структурами регистрационных свидетельств (сертификатов) описанных в документе “Правила применения регистрационных свидетельств НУЦ РК” доступного на портале НУЦ РК в разделе Документация;
• valueInB64 - флаг, определяющий является ли значение в поле value строкой, либо base64 представлением бинарных данных;
• value - значение атрибута, значения некоторых атрибутов не могут быть представлены в текстовом виде, в этом случае в это поле будет записано base64 представление бинарного значения атрибута и valueInB64 будет установлен в true.

# GET /api/{id}/data - получение подписанных данных из архива

• {id} - идентификатор документа.

Позволяет получить подписанные данные в том случае, если они предварительно были помещены в архив.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "document": "MTEK",
  "signedDataSize":13567
}

• documentId - уникальный идентификатор зарегистрированного документа;
• document - подписанные данные в виде base64 строки;
• signedDataSize - размер подписанного документа (в байтах).

# POST /api/{id} - добавление подписи к документу

• {id} - идентификатор документа.

В рамках регистрации новой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.

Сервис допускает регистрацию двух типов подписей:

• CMS - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics или методом createCAdESFromBase64;
• XML - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics или методом signXml, но в обоих случаях с некоторыми оговорками (см. ниже).

JS библиотека с открытым исходным кодом https://github.com/sigex-kz/ncalayer-js-client поддерживает все эти варианты.

CMS подписи могут включать в себя подписанные данные (рекомендуется не включать данные в подпись, так как у сервиса есть ограничение на размер принимаемых данных для этого вызова), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).

В том случае, если переданная CMS подпись содержит подписанные данные, эти данные перед сохранением будут извлечены из подписи.

CMS подписи поддерживаются в DER и PEM кодировках.

Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.

Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.

Под XML подписью сервис подразумевает только ту часть XML, которая содержит данные о подписи - то есть только элемент <ds:Signature xmlns:ds=“http://www.w3.org/2000/09/xmldsig#">. В том случае, если подпись была сформирована с помощью вызова signXml утилиты NCALayer, то корректное извлечение необходимого элемента и оформление его в соответствии с https://www.w3.org/TR/xmldsig-core1 ложится на плечи разработчика.

Попробовать этот API в Postman

Запрос (Content-Type необходимо установить в application/json):

{
  "signType": "cms",
  "signature": "signature",
  "signatureEmailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocument": false
  }
}

• signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
• signature - в случае CMS это должна быть подпись в кодировке DER дополнительно закодированная в base64, либо в кодпировке PEM без дополнительного кодирования, в случае XML - текстовое представление XML;
• signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новой подписи под документом с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocument - опциональное поле, позволяет отправлять уведомления без прикрепленного документа, по умолчанию false.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 123,
  "data": "MTEK",
  "automaticallyCreatedUserSettings": {},
  "automaticallyCreatedOrgSettings": {},
  "dataArchived": false,
  "canBeArchived": true
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• signId - уникальный идентификатор добавленной подписи;
• data - опциональное поле, извлеченные из CMS подписанные данные в виде base64 строки, присутствует только в том случае, если переданная в запросе подпись включала подписанные данные;
• automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings - получить настройки аутентифицированного пользователя;
• automaticallyCreatedOrgSettings - опциональное поле, присутствует только в том случае, если сотрудник огранизации (идентифицируется по БИН) первый раз регистрирует подпись на сервисе, информирует о том, что сервис создал запись с настройками данной организации, содержимое идентично GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве;
• canBeArchived - информирует о том, что документ может быть добавлен в архив (такая ситуация может возникнуть если в настройках первого подписавшего архивирование отключено, но включено у кого-то из других подписавших), для того, чтобы добавить документ в архив, следует использовать POST /api/{id}/verify - проверка подписей.

# POST /api/{id}/verify - проверка подписей

• {id} - идентификатор документа.

Данный метод выполнит следующее:

• удостоверится в том, что сохраненные в системе подписи являются подписями именно под переданным документом (то есть что не произошло подмены или изменения документа);
• выполнит проверку каждой подписи на момент ее регистрации в системе используя сохраненные данные OCSP и TSP.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.

В качестве тела запроса следует передать оригинальный документ.

В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.

При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "dataArchived": false
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве.

# POST /api/{id}/notify - отправка уведомлений о документе

• {id} - идентификатор документа.

На данный момент поддерживается отправка уведомлений только по электронной почте.

Запрос (Content-Type необходимо установить в application/json):

{
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocument": false
  }
}

• emailNotifications - параметры отправки email уведомлений:
  • to - массив адресов электронной почты;
  • doNotAttachDocument - опциональное поле, позволяет отправлять уведомления без прикрепленного документа, по умолчанию false.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "emailNotifications": {
    "attached": true,
  }
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• emailNotifications - результат отправки уведомлений:
  • attached - флаг указывающий был ли прикреплен документ к отправленным уведомлениям.

# GET /api/{id}/signature/{signId}?signFormat=X&cmsAsPem=false - экспорт одной подписи документа

• {id} - идентификатор документа;
• {signId} - идентификатор подписи;
• signFormat=X - опционально, формат экспорта, по умолчанию 0;
• cmsAsPem=X - опционально, экспорт в кодировке PEM, по умолчанию false (то есть DER).

Поддерживаются следующие форматы экспорта:

• 0 (по умолчанию) - CMS с интегрированными меткой времени (TimeStampToken, CMS атрибут с OID 1.2.840.113549.1.9.16.2.14) и квитанцией OCSP (BasicOCSPResponse, CMS атрибут с OID-ом 1.2.840.113549.1.9.16.2.24);
• 1 - оригинальный CMS, принятый в систему при добавлении подписи.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1,
  "signType": "cms",
  "signFormat": 0,
  "signature": "signature"
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• signId - уникальный идентификатор подписи в системе;
• signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
• signFormat - формат подписи;
• signature - в случае CMS это закодированная в base64 подпись, в случае XML - текстовое представление XML.

# GET /api/{id}/signature/{signId}/qr?signFormat=X&qrVersion=25&qrLevel=M - экспорт подписи в виде набора QR кодов

• {id} - идентификатор документа;
• {signId} - идентификатор подписи;
• signFormat=X - опционально, формат экспорта, по умолчанию 0;
• qrVersion=25 - опционально, версия QR кода (размер), по умолчанию 25, версии ниже 11 не поддерживаются, детали тут https://www.qrcode.com/en/about/version.html;
• qrLevel=M - опционально, уровень коррекции ошибок (ECC), по умолчанию M, детали тут https://www.qrcode.com/en/about/version.html.

Поддерживаются следующие форматы экспорта:

• 0 (по умолчанию) - CMS с интегрированными меткой времени (TimeStampToken, CMS атрибут с OID 1.2.840.113549.1.9.16.2.14) и квитанцией OCSP (BasicOCSPResponse, CMS атрибут с OID-ом 1.2.840.113549.1.9.16.2.24);
• 1 - оригинальный CMS, принятый в систему при добавлении подписи.

Формирование набора QR кодов осуществляется по следующему алгоритму:

• Подпись в запрошенном представлении упаковывается в ZIP архив методом DEFLATE. Имя файла, содержащегося в архиве формируется как {signId}.{signType}, то есть имя файла - это идентификатор подписи, а расширение - тип подписи (в текущей реализации "xml" или "cms").
• Формируется base64 представление ZIP архива.
• Base64 представление разбивается на части, каждая часть упаковывается в описанную ниже JSON структуру. Размер каждой части определяется исходя из параметров запроса qrVersion (версия) и qrLevel (уровень коррекции ошибок).
• Полученные JSON структуры кодируются в изображения, QR коды, в формате PNG.
• Из набора изображений формируется массив qrCodes который является частью ответа, изображения в нем закодированы в base64.

JSON структура части подписи:

{
  "documentId": "Nzxn6JCumwKKhEv4",
  "signId": 9,
  "signType": "xml",
  "total": 7,
  "index": 1,
  "data": "part_of_archived_and_base64_encoded_signature"
}

где:

• documentId - идентификатор документа;
• signId - уникальный идентификатор подписи в системе;
• signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
• total - общее количество частей;
• index - индекс данной части;
• data - строка, часть base64 представления ZIP архива.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1,
  "signType": "cms",
  "signFormat": 0,
  "qrCodes": [
    "base64_encoded_png_with_qr_code_part1",
    ...
    "base64_encoded_png_with_qr_code_partn"
  ]
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• signId - уникальный идентификатор подписи в системе;
• signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
• signFormat - формат подписи;
• qrCodes - массив строк каждая из которых содержит закодированное в base64 изображение в формате PNG с закодированным QR кодом.

# POST /api/{id}/buildDDC?fileName=X&withoutDocumentVisualization=false&withoutSignaturesVisualization=false&withoutQRCodesInSignaturesVisualization=false&withoutID=false&qrWithIDLink=false&language=ru - формирование карточки электронного документа

• {id} - идентификатор документа;
• fileName=X - опционально, имя файла для встраивания подлинника электронного документа, если не передан, будет использован заголовок документа в системе;
• withoutDocumentVisualization=false - опционально, отключить визуализацию электронного документа, по умолчанию false;
• withoutSignaturesVisualization=false - опционально, отключить визуализацию цифровых подписей, по умолчанию false;
• withoutQRCodesInSignaturesVisualization=false - опционально, не отображать QR коды в визуализации цифровых подписей (работает только в том случае, если withoutSignaturesVisualization=false), по умолчанию false;
• withoutID=false - не отображать идентификатор документа и QR код с идентификатором документа в верхнем колонтитуле каждой страницы, по умолчанию false;
• qrWithIDLink=false - отображать QR коды с URL на страницу подписанного документа, по умолчанию false;
• language=ru - опционально, язык формирования, поддерживаются "ru", "kk" и "kk/ru", по умолчанию "ru".

Важно! В данный момент визуализация электронных документов поддерживаются исключительно для документов в формате PDF. Сервис выполняет предварительную проверку типа файла по расширению в имени файла, то есть в имени файла явно должно быть указано расширение ".pdf". В том случае, если указан параметр fileName, то сервис использует это значение в качестве имени файла, иначе поле title зарегистрированного электронного документа. Таким образом для того, чтобы сервис смог сформировать карточку электронного документа, необходимо указать расширение ".pdf" либо в title зарегистрированного электронного документа, либо в параметре fileName.

Сервис выполнит следующее:

• удостоверится в том, что под документом зарегистрированы исключительно CMS подписи, так как спецификация карточки электронного документа допускает только такие подписи;
• удостоверится в том, что зарегистрированные в сервисе подписи являются подписями именно под переданным документом (то есть что не произошло подмены или изменения документа);
• выполнит проверку каждой подписи на момент ее регистрации в сервисе используя сохраненные данные OCSP и TSP;
• сформирует карточку электронного документа - PDF файл, содержащий в себе подлинник электронного документа, подписи и визуализацию.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.

В качестве тела запроса следует передать оригинальный документ.

При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "ddc": "MTEK",
  "dataArchived": false
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• ddc - файл карточки электронного документа в виде base64 строки;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве.

# POST /api/{id}/buildEzSigner - формирование CMS для сервиса ezSigner.kz

• {id} - идентификатор документа.

Сервис выполнит следующее:

• удостоверится в том, что под документом зарегистрированы исключительно CMS подписи, так как сервис ezSigner поддерживает только такие подписи;
• удостоверится в том, что зарегистрированные в сервисе подписи являются подписями именно под переданным документом (то есть что не произошло подмены или изменения документа);
• выполнит проверку каждой подписи на момент ее регистрации в сервисе используя сохраненные данные OCSP и TSP;
• сформирует CMS файл в формате, совместимом с сервисом https://ezSigner.kz.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.

В качестве тела запроса следует передать оригинальный документ.

При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.

Ответ:

{
  "documentId": "Uthhymv7TN5vPxVl",
  "signature": "CMSasBASE64",
  "dataArchived": false
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• signature - закодированный в base64 сформированный CMS, содержащий переданные в обработчик данные и зарегистрированные на сервисе подписи;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве.

# POST /api/{id}/settings - изменение настроек документа

• {id} - идентификатор документа.

Отправка нового объекта с настройками документа. Все поля объекта опциональны, то есть можно указывать только те настройки, которые должны отличаться от настроек по умолчанию, а не старое значение.

Все текущие настройки документа будут перезаписаны. В том случае, если в передаваемом новом объекте настроек какая-то настройка отсутствует, будет использовано значение по умолчанию.

Запрос (Content-Type необходимо установить в application/json):

{
  "private": false,
  "signaturesLimit": 2,
  "switchToPrivateAfterLimitReached": true,
  "unique": ["iin", "bin"],
  "strictSignersRequirements": false,
  "sequentialSignersRequirements": false,
  "signersRequirements": [
    {
      "iin": "IIN112233445566",
      "ca": "btsd"
    },
    {
      "bin": "BIN112233445566",
      "authorities": ["OID1", "OID2"],
      "ca": "nca"
    },
    {
      "bin": "BIN112233445566",
      "iin": "IIN112233445566"
    },
    {
      "bin": "BIN112233445566",
      "authorities": ["OID1", "OID2"],
      "iin": "IIN112233445566"
    }
  ],
  "publicDuringPreregistration": false,
  "documentAccess": [
    { "iin": "IIN112233445566" },
    { "iin": "IIN665544332211", "bin": "BIN112233445566" },
    { "bin": "BIN112233445566" }
  ],
  "forceArchive": false
}

• private - опциональное поле, определяет ограничен ли доступ к документу (см. Аутентификация и контроль доступа), либо он является общедоступным документом, по умолчанию false;
• signaturesLimit - опциональное поле, ограничение на разрешенное количество подписей под документом (0 - не ограничено), по умолчанию 0;
• switchToPrivateAfterLimitReached - опциональное поле, определяет должен ли сервис автоматически переключить настройку private в true после того, как будет зарегистрировано signaturesLimit подписей, по умолчанию false;
• unique - опциональное поле, массив требований к уникальности, может включать в себя константы "iin" и "bin", константы ограничивают возможность регистрации подписей с идентичными ИИН и БИН, по умолчанию [] (то есть ограничения отсутствуют);
• strictSignersRequirements - опциональное поле, определяет будут ли применены правила signersRequirements к первой регистрируемой подписи, по умолчанию false;
• sequentialSignersRequirements - опциональное поле, позволяет настраивать последовательность подписаний документа, в том случае, если оно установлено в true, то signersRequirements будут интерпретированы как последовательность требований - то есть первый элемент signersRequirements относится к первой регистрируемой подписи, второй элемент относится ко второй подписи и так далее, по умолчанию false;
• signersRequirements - опциональное поле, массив требований к подписям, в том случае, если он не пуст, каждая регистрируемая подпись перед регистрацией должна быть проверена на соответствие требованиям (должна удовлетворить хотя бы одному элементу массива - объединяются через ИЛИ), по умолчанию [] (то есть требования отсутствуют),
• publicDuringPreregistration - опциональное поле, флаг активации специального режима контроля доступа к документу и подписываемым данным (в этом режиме до регистрации первой подписи под документом информация о документе и подписываемые данные доступны всем без ограничений), флаг возможно устанавливать только при предрегистрации документа, менять его значение нельзя;
• documentAccess - опциональное поле, позволяет задавать дополнительные правила предоставления доступа к информации о документе и данным в архиве, то есть дополняет существующие правила контроля доступа основанные на наличии подписей под документом и регистраторе документа, а не заменяет и не ужесточает их, подробности про контроль доступа тут;
• forceArchive - опциональное поле, позволяет принудительно заархивировать документ даже в том случае, если архивирование не активировано в настройках подписантов, его возможно задавать только в момент первоначальной регистрации документа, по умолчанию false.

Требования signersRequirements - это объекты со следующими опциональными полями (необходимо одно любое поле):

{
  "bin": "BIN112233445566",
  "authorities": ["OID1", "OID2"],
  "iin": "IIN112233445566",
  "ca": "nca",
}

• bin - опциональное поле, в сертификате в подписи должен присутствовать соответствующий БИН;
• authorities - опциональное поле, в сертификате в подписи должно присутствовать одно из указанных полномочий;
• iin - опциональное поле, в сертификате в подписи должен присутствовать соответствующий ИИН;
• ca - опциональное поле, наименование удостоверяющего центра, выпустившего сертификат конечного пользователя, поддерживаются константы "nca" и "btsd".

В том случае, если указано несколько полей, то они ужесточают друг друга (объединяются через И).

Дополнительные правила контроля доступа documentAccess - это объекты со следующей структурой:

{
  "iin": "IIN112233445566",
  "bin": "BIN665544332211"
}

• iin - опициональное поле, ИИН пользователя которому необходимо предоставить доступ;
• bin - опициональное поле, БИН организации которой необходимо предоставить доступ.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору.

# GET /api/{id}/settingsAudit?lastEventId=X - аудит изменений настроек документа

• {id} - идентификатор документа;
• lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек документа.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "eventsTotal": 3,
  "events": []
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• eventsTotal - количество изменений зарегистрированных в системе;
• events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedBy": "IIN123456789",
  "modifiedByDigest": "XXXXXXXXXXXXXXX",
  "modifiedAt": 1586167317737
}

• eventId - идентификатор события;
• original - настройки до изменения;
• modified - настройки после изменения;
• modifiedBy - кем были произведены изменения, ИИН;
• modifiedByDigest - хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;
• modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# GET /api/{id}/buildFileName?name=XXX - сформировать имя файла с идентификатором SIGEX

• {id} - идентификатор документа;
• name=XXX - опционально, имя файла без идентификатора, если не указано, то будет использовано значение из title документа.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "fileName": "XXX-SigexId{id}"
}

• documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
• fileName - имя файла со встроенным идентификатором SIGEX.

# POST /api/{id}/egovQr - регистрация процедуры упрощенного подписания через QR или диплинки

• {id} - идентификатор документа.

Позволяет инициировать подписание через eGov mobile/business уже зарегистрированного документа, а так же выполнить регистрацию полученной подписи под данным документом. То есть заменяет следующие четыре вызова:

• POST /api/egovQr - зарегистрировать новую процедуру подписания ЭЦП через QR
• POST /api/egovQr/{qrId} - отправка данных на подписание
• GET /api/egovQr/{qrId} - получение подписей
• POST /api/{id} - добавление подписи к документу

Важно:* Поддерживается только для документов находящихся в архиве, тело подписываемого документа будет отправлено в eGov mobile/business из архива.

В случае успешного выполнения под документом будет зарегистрирована новая подпись, статус выполнения процедуры можно отслеживать с помощью GET /api/{id}/egovOperation/{operationId} - получение статуса процедуры подписания, отменить процедуру можно с помощью DELETE /api/{id}/egovOperation/{operationId} - отмена процедуры подписания.

Запрос (Content-Type необходимо установить в application/json):

{
  "description": "Договор на подпись",
  "meta": [
    {
      "name": "Номер договора",
      "value": "1234"
    },
    {
      "name": "Контрагент",
      "value": "ТОО Контрагент"
    }
  ],
  "signatureEmailNotifications": {
    "to": ["user1@example.com","other1@example.com"],
    "doNotAttachDocument": false
  }
}

• description - описание регистрируемой процедуры подписания, текст будет отображен в eGov mobile/business;
• meta - опциональный массив метаданных подписываемого документа;
• signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новой подписи под документом с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocument - опциональное поле, позволяет отправлять уведомления без прикрепленного документа, по умолчанию false.

Ответ:

{
  "operationId": "12345",
  "expireAt": 1668758024082,
  "qrCode": "XXXXX",
  "eGovMobileLaunchLink": "http://...",
  "eGovBusinessLaunchLink": "http://..."
}

• operationId - строка, идентификатор зарегистрированной процедуры подписания;
• expireAt - момент истечения срока действия процедуры подписания в миллисекундах с UNIX Epoch;
• qrCode - строка, закодированное в base64 изображение в формате PNG с закодированным QR кодом для приложения eGov mobile/business;
• eGovMobileLaunchLink - диплинк для запуска eGov mobile на том же устройстве;
• eGovBusinessLaunchLink - диплинк для запуска eGov Business на том же устройстве.

# GET /api/{id}/egovOperation/{operationId} - получение статуса процедуры подписания

• {id} - идентификатор документа;
• {operationId} - идентификатор процедуры подписания.

Позволяет отслеживать статус процедур подписания зарегистрированных через POST /api/{id}/egovQr - регистрация процедуры упрощенного подписания через QR или диплинки.

Ответ:

{
  "operationId": "12345",
  "status": "meta",
  "createdAt": 1668758020082,
  "expireAt": 1668758024082,
  "description": "Договор на подпись",
  "userId": "123456789012",
  "signId": 17,
  "meta": [
    {
      "name": "Номер договора",
      "value": "1234"
    },
    {
      "name": "Контрагент",
      "value": "ТОО Контрагент"
    }
  ],
  "signatureEmailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocument": false
  },
  "errors": {
    "egov": "ошибка обмена данными",
    "sigex": "ошибка получения метки времени"
  }
}

• operationId - строка, идентификатор зарегистрированной процедуры подписания;
• status - строка, текущий статус процедуры, может принимать одно из следующих значений:
  • "new" - процедура упрощенного подписания зарегистрирована;
  • "meta" - пользователь сканировал QR код или кликнул на диплинк;
  • "data" - приложение eGov mobile/business скачало документ для подписания;
  • "done" - подписание выполнено успешно;
  • "canceled" - операция отменена (пользователем);
  • "fail" - подписание не удалось/завершилось с ошибкой, либо срок действия операции подписания истек (в этом случае в errors.sigex будет приведена ошибка "eGov signing operation expired");
• createdAt - момент регистрации процедуры подписания в миллисекундах с UNIX Epoch;
• expireAt - момент истечения срока действия процедуры подписания в миллисекундах с UNIX Epoch;
• description - описание процедуры подписания установленное при регистрации;
• meta - массив метаданных документа указанный при регистрации;
• userId - опциональная строка содержащая ИИН пользователя для которого была зарегистрирована процедура;
• signId - идентификатор подписи, зарегистрированной в случае успешного завершения процедуры подписания;
• signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новой подписи под документом с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocument - опциональное поле, позволяет отправлять уведомления без прикрепленного документа, по умолчанию false;
• errors - опциональный объект, содержащий информацию об ошибках, возникших при выполнении процедуры:
  • egov - информация об ошибке полученной в процессе взаимодействия с eGov mobile/business;
  • sigex - информация об ошибке полученной при обработке подписи.

# DELETE /api/{id}/egovOperation/{operationId} - отмена процедуры подписания

• {id} - идентификатор документа;
• {operationId} - идентификатор процедуры подписания.

Позволяет отменять процедуры подписания зарегистрированные через POST /api/{id}/egovQr - регистрация процедуры упрощенного подписания через QR или диплинки.

Ответ:

{
  "operationId": "12345"
}

• operationId - строка, идентификатор зарегистрированной процедуры подписания.

# POST /api/package - регистрация пакета документов

Важно! Регистрация пакета документов не будет завершена до тех пор пока для всех документов пакета не будет выполнена POST /api/{id}/data - фиксация значений хешей документа.

Пакет документов - это набор документов для которых можно задавать одинаковые настройки, а так же:

• отправлять одно уведомление по электронной почте с запросом подписания всего пакета и ссылкой на страницу подписания этого пакета;
• требовать атомарности подписания, то есть запрещать подписывать только один документ из пакета, в этом случае контрагент сможет подписать только все документы пакета одновременно.

В рамках регистрации пакета будет зарегистрирован сам пакет и документы этого пакета, то есть будут зарезервированы идентификатор пакета и идентификаторы документов.

Запрос (Content-Type необходимо установить в application/json):

{
  "title": "package title",
  "description": "package description",
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false
  },
  "settings": {
    "private": false,
    "packageAccess": [],
    "packageSettings": [],
    "signWholePackage": false
  },
  "documentsSettings": {},
  "documents": [
    {"title": "some title 1", "description": "some description 1"},
    {"title": "some title 2", "description": "some description 2"},
    {"title": "some title N", "description": "some description N"}
  ]
}

• title - название пакета документов;
• description - описание пакета документа;
• emailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о подписании пакета документов с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
• settings - опциональный параметр, объект настроек пакета документов, описание приведено в POST /api/package/{packageId}/settings - изменение настроек пакета документов;
• documentsSettings - опциональный параметр, объект настроек документов, эти настройки будут применены к документам пакета, на сам пакет они не влияют, описание приведено в POST /api/{id}/settings - изменение настроек документа;
• documents - массив объектов описывающих документы пакета.

Ответ:

{
  "packageId": "xxx",
  "documentsIds": ["id1", "id2", "idN"]
}

• packageId - уникальный идентификатор зарегистрированного пакета документов;
• documentsIds - массив уникальных идентификаторов зарегистрированных документов в этом пакете.

# GET /api/package/{packageId} - получение данных о зарегистрированном пакете документов

• {packageId} - идентификатор пакета документов.

Ответ:

{
  "packageId": "xxx",
  "title": "some title",
  "description": "some description",
  "storedAt": 1568809427182,
  "registrator": {
    "businessId":"BIN012345678901",
    "certificate":"base64_encoded_mtls_certificate"
  },
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false
  },
  "signatureEmailNotifications": [
    {
      "signIds": [1, 2, 3],
      "doNotAttachDocuments": false,
      "to": ["user@example.com","otherUser@example.com"]
    },
    {
      "signIds": [4, 5, 6],
      "doNotAttachDocuments": true,
      "to": ["3@example.com","4@example.com"]
    },
  ],
  "settings": {
    "private": false,
    "packageAccess": [],
    "packageSettings": [],
    "signWholePackage": false
  },
  "documentsSettings": {},
  "documentsIds": ["id1", "id2", "idN"]
}

• packageId - идентификатор пакета документов;
• title - название пакета документов;
• description - описание пакета документа;
• storedAt - время сохранения пакета (миллисекунд с UNIX Epoch);
• registrator - информация об информационной системе зарегистрировавшей пакет документов (БИН и mTLS сертификат в base64);
• emailNotifications - информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации пакета документов;
• signatureEmailNotifications - массив объектов, информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации подписей;
• settings - объект настроек пакета документов, описание приведено в POST /api/package/{packageId}/settings - изменение настроек пакета документов;
• documentsSettings - объект настроек документов, эти настройки будут применены к документам пакета, на сам пакет они не влияют, описание приведено в POST /api/{id}/settings - изменение настроек документа;
• documentsIds - массив идентификаторов документов в этом пакете.

# POST /api/package/{packageId} - добавление подписей к документам пакета

• {packageId} - идентификатор пакета документов.

Количество и порядок передаваемых на регистрацию подписей должно быть идентично количеству документов в пакете, подписи будут зарегистрированы под соответствующими документами, то есть первая подпись под первым документом пакета, вторая под вторым и так далее.

В том случае, если регистрация одной любой подписи невозможна, API вернет ошибку и не зарегистрирует ни одну из переданных подписей.

В том случае, если для пакета установлен signWholePackage, то подписи к документам пакета можно добавлять только через этот API, добавлять подписи под отдельные документы через POST /api/{id} - добавление подписи к документу не получится.

Запрос (Content-Type необходимо установить в application/json):

{
  "signatures": [
    {
      "signType":"cms",
      "signature":"signB641"
    },
    ...
    {
      "signType":"xml",
      "signature":"<xml></xml>"
    }
  ],
  "signatureEmailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false
  }
}

• signatures - массив подписей, структура описана в POST /api/{id} - добавление подписи к документу;
• signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новых подписей под документами пакета с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false.

Ответ:

{
  "packageId": "xxx",
  "registrationResults": [{}]
}

• packageId - идентификатор пакета документов;
• registrationResults - массив объектов с результатами регистрации подписей, структура описана в POST /api/{id} - добавление подписи к документу.

# POST /api/package/{packageId}/notify - отправка уведомлений о пакете документов

• {packageId} - идентификатор пакета документов.

На данный момент поддерживается отправка уведомлений только по электронной почте.

Запрос (Content-Type необходимо установить в application/json):

{
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false
  }
}

• emailNotifications - параметры отправки email уведомлений:
  • to - массив адресов электронной почты;
  • doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false.

Ответ:

{
  "packageId": "lQsqLBaS4nQAIIMm",
  "emailNotifications": {
    "attached": true,
  }
}

• packageId - идентификатор пакета документов;
• emailNotifications - результат отправки уведомлений:
  • attached - флаг указывающий были ли прикреплены документы к отправленным уведомлениям.

# POST /api/package/{packageId}/settings - изменение настроек пакета документов

• {packageId} - идентификатор пакета документов.

Отправка нового объекта с настройками пакета документов. Все поля объекта опциональны, то есть можно указывать только те настройки, которые должны отличаться от настроек по умолчанию.

Все текущие настройки пакета документов будут перезаписаны. В том случае, если в передаваемом новом объекте настроек какая-то настройка отсутствует, будет использовано значение по умолчанию, а не старое значение.

Запрос (Content-Type необходимо установить в application/json):

{
  "private": false,
  "packageAccess": [
    { "iin": "IIN112233445566" },
    { "iin": "IIN665544332211", "bin": "BIN112233445566" },
    { "bin": "BIN112233445566" }
  ],
  "packageSettings": [
    { "iin": "IIN112233445566" },
    { "iin": "IIN665544332211", "bin": "BIN112233445566" },
    { "bin": "BIN112233445566" }
  ],
  "signWholePackage": false
}

• private - опциональное поле, определяет ограничен ли доступ к пакету документов (см. Аутентификация и контроль доступа), либо он является общедоступным пакетом документов, по умолчанию false;
• packageAccess - опциональное поле, позволяет задавать дополнительные правила предоставления доступа к информации о пакете документов (но не к документам в пакете), подробности про контроль доступа тут;
• packageSettings - опциональное поле, позволяет задавать дополнительные правила предоставления доступа к изменению настроек пакета документов (но не изменения настроек документов пакета), подробности про контроль доступа тут;
• signWholePackage - блокирует возможность добавлять подписи под документы пакета через POST /api/{id} - добавление подписи к документу, можно добавлять только через POST /api/package/{packageId} - добавление подписей к документам пакета, то есть подписывать можно только все документы пакета одной операцией, по умолчанию false.

Дополнительные правила предоставления доступа к информации о пакете документов (но не к документам в пакете) packageAccess - это объекты со следующей структурой:

{
  "iin": "IIN112233445566",
  "bin": "BIN665544332211"
}

• iin - опициональное поле, ИИН пользователя которому необходимо предоставить доступ;
• bin - опициональное поле, БИН организации которой необходимо предоставить доступ.

Дополнительные правила предоставления доступа к изменению настроек пакета документов (но не изменения настроек документов пакета) packageSettings - это объекты со следующей структурой:

{
  "iin": "IIN112233445566",
  "bin": "BIN665544332211"
}

• iin - опициональное поле, ИИН пользователя которому необходимо предоставить доступ;
• bin - опициональное поле, БИН организации которой необходимо предоставить доступ.

Ответ:

{
  "packageId": "lQsqLBaS4nQAIIMm"
}

• packageId - идентификатор пакета документов.

# GET /api/package/{packageId}/settingsAudit?lastEventId=X - аудит изменений настроек пакета документов

• {packageId} - идентификатор пакета документов;
• lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек пакета документов.

Ответ:

{
  "packageId": "lQsqLBaS4nQAIIMm",
  "eventsTotal": 3,
  "events": []
}

• packageId - идентификатор пакета документов, должен быть идентичен переданному идентификатору;
• eventsTotal - количество изменений зарегистрированных в системе;
• events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedBy": "IIN123456789",
  "modifiedByDigest": "XXXXXXXXXXXXXXX",
  "modifiedAt": 1586167317737
}

• eventId - идентификатор события;
• original - настройки до изменения;
• modified - настройки после изменения;
• modifiedBy - кем были произведены изменения, ИИН;
• modifiedByDigest - хеш mTLS сертификата в том случае, если изменение было выполненой от имени информационной системы;
• modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки

• {packageId} - идентификатор пакета документов.

Позволяет инициировать подписание через eGov mobile/business всего пакета документов, а так же выполнить регистрацию полученных подписей под данным пакетом.

Важно:* Все документы пакета должны находиться в архиве, так как они будут отправлены в eGov mobile/business из архива.

В случае успешного выполнения под каждый документом пакета будет зарегистрирована новая подпись, статус выполнения процедуры можно отслеживать с помощью GET /api/package/{packageId}/egovOperation/{operationId} - получение статуса процедуры подписания пакета документов, отменить процедуру можно с помощью DELETE /api/package/{packageId}/egovOperation/{operationId} - отмена процедуры подписания пакета документов.

Запрос (Content-Type необходимо установить в application/json):

{
  "description": "Анкета и договор на подпись",
  "meta": [
    [
      {
        "name": "Анкета номер",
        "value": "1234"
      }
    ],
    [],
    [
      {
        "name": "Номер договора",
        "value": "1234"
      },
      {
        "name": "Контрагент",
        "value": "ТОО Контрагент"
      }
    ]
  ],
  "signatureEmailNotifications": {
    "to": ["user1@example.com","other1@example.com"],
    "doNotAttachDocuments": false
  }
}

• description - описание регистрируемой процедуры подписания, текст будет отображен в eGov mobile/business;
• meta - опциональный массив массивов метаданных подписываемого пакета документов, если поле указано, то количество элементов в нем должно быть равно количеству документов в пакете, в том случае, если для какого-то документа метаданные указывать не нужно, следует указать пустой массив;
• signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новых подписей под документами пакета с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false.

Ответ:

{
  "operationId": "12345",
  "expireAt": 1668758024082,
  "qrCode": "XXXXX",
  "eGovMobileLaunchLink": "http://...",
  "eGovBusinessLaunchLink": "http://..."
}

• operationId - строка, идентификатор зарегистрированной процедуры подписания;
• expireAt - момент истечения срока действия процедуры подписания в миллисекундах с UNIX Epoch;
• qrCode - строка, закодированное в base64 изображение в формате PNG с закодированным QR кодом для приложения eGov mobile/business;
• eGovMobileLaunchLink - диплинк для запуска eGov mobile на том же устройстве;
• eGovBusinessLaunchLink - диплинк для запуска eGov Business на том же устройстве.

# GET /api/package/{packageId}/egovOperation/{operationId} - получение статуса процедуры подписания пакета документов

• {packageId} - идентификатор пакета документа;
• {operationId} - идентификатор процедуры подписания.

Позволяет отслеживать статус процедур подписания зарегистрированных через POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки.

Ответ:

{
  "operationId": "12345",
  "status": "meta",
  "createdAt": 1668758020082,
  "expireAt": 1668758024082,
  "description": "Анкета и договор на подпись",
  "meta": [
    [
      {
        "name": "Анкета номер",
        "value": "1234"
      }
    ],
    [],
    [
      {
        "name": "Номер договора",
        "value": "1234"
      },
      {
        "name": "Контрагент",
        "value": "ТОО Контрагент"
      }
    ]
  ],
  "signIds": [17, 18, 19],
  "signatureEmailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false
  },
  "errors": {
    "egov": "ошибка обмена данными",
    "sigex": "ошибка получения метки времени"
  }
}

• operationId - строка, идентификатор зарегистрированной процедуры подписания;
• status - строка, текущий статус процедуры, может принимать одно из следующих значений:
  • "new" - новая операция, никаких действий еще не выполнялось;
  • "meta" - пользователь сканировал QR код или кликнул на диплинк;
  • "data" - приложение eGov mobile/business скачало документ для подписания;
  • "done" - подписание выполнено успешно;
  • "fail" - подписание не удалось;
• createdAt - момент регистрации процедуры подписания в миллисекундах с UNIX Epoch;
• expireAt - момент истечения срока действия процедуры подписания в миллисекундах с UNIX Epoch;
• description - описание процедуры подписания установленное при регистрации;
• meta - массив метаданных указанный при регистрации;
• signIds - идентификаторы подписей, зарегистрированных в случае успешного завершения процедуры подписания;
• signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новых подписей под документами пакета с полями:
  • to - массив адресов электронной почты;
  • doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
• errors - опциональный объект, содержащий информацию об ошибках, возникших при выполнении процедуры:
  • egov - информация об ошибке полученной в процессе взаимодействия с eGov mobile/business;
  • sigex - информация об ошибке полученной при обработке подписи.

# DELETE /api/package/{packageId}/egovOperation/{operationId} - отмена процедуры подписания пакета документов

• {packageId} - идентификатор пакета документов;
• {operationId} - идентификатор процедуры подписания.

Позволяет отменять процедуры подписания зарегистрированные через POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки.

Ответ:

{
  "operationId": "12345"
}

• operationId - строка, идентификатор зарегистрированной процедуры подписания.

# POST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документа

В передаваемой подписи допускается наличие метки времени TSP (signature-time-stamp) и квитанции OCSP (revocation-values). Важно чтобы метка времени и квитанция, в том случае, если они присутствуют, были именно теми же, которые зарегистрированы в сервисе. Это обусловлено тем, что метка времени и квитанция фиксируют момент подписания и, в том случае, если были получены другие метка времени и квитанция, эти данные не будут совпадать с теми, которые зарегистрированы в сервисе.

Запрос (Content-Type необходимо установить в application/json):

{
  "signType": "cms",
  "signature": "signature"
}

• signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
• signature - в случае CMS это должна быть подпись в кодировке DER дополнительно закодированная в base64, либо в кодпировке PEM без дополнительного кодирования, в случае XML - текстовое представление XML.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1
}

• documentId - уникальный идентификатор документа;
• signId - уникальный идентификатор подписи.

# POST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документа

• registerUnknownSignatures=false - опционально, определяет должен ли сервис регистрировать новые неизвестные подписи, по умолчанию false.

Сервис выполнит следующее:

• выполнит разбор полученного файла, удостоверится в том, что это файл карточки электронного документа;
• проверит зарегистрированы ли в SIGEX все вложенные подписи;
• в том случае, если были обнаружены еще не зарегистрированные вложенные подписи и registerUnknownSignatures=true, попробует их зарегистрировать, вернет ошибку в том случае, если не удалось зарегистрировать какую-либо из них;
• в том случае, если были обнаружены еще не зарегистрированные вложенные подписи и registerUnknownSignatures=false, вернет ошибку;
• удостоверится в том, что все вложенные подписи относятся к одному и тому же зарегистрированному в SIGEX документу;
• удостоверится в том, что вложенные подписи являются подписями именно под вложенным в карточку документом (то есть что не произошло подмены или изменения документа);
• выполнит проверку каждой подписи на момент ее регистрации в системе используя сохраненные данные OCSP и TSP;
• вернет идентификатор электронного документа, идентификаторы подписей и извлеченный вложенный подлинник электронного документа.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.

В качестве тела запроса следует передать файл Карточки электронного документа.

При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signIds": [1, 2],
  "document": "MTEK",
  "dataArchived": false
}

• documentId - идентификатор документа;
• signIds - массив идентификаторов подписей;
• document - файл извлеченного подлинника подписанного документа в виде base64 строки;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве.

# POST /api/checkPDFForDDC - проверка PDF на возможность визуализации в карточке

Так как для визуализации PDF файлов в Карточках электронных документов сервису необходимо выполнять специфические манипуляции с содержимым и структурой этих PDF файлов, то необходимо быть уверенными в том, что каждый конкретный PDF файл обрабатывается сервисом корректно. Такая проверка выполняется сервисом в начале обработки POST /api/{id}/buildDDC?fileName=X&withoutDocumentVisualization=false&withoutSignaturesVisualization=false&withoutQRCodesInSignaturesVisualization=false&withoutID=false&qrWithIDLink=false&language=ru - формирование карточки электронного документа, но если она завершается ошибкой возникает неприятная ситуация - электронный документ (PDF файл) уже подписан ЭЦП, но сформировать из него Карточку невозможно.

Для того, чтобы удостовериться в том, что из PDF после подписания точно получится сформировать Карточку, можно воспользоваться этим API. Он сформирует Карточку с пробными данными.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.

В качестве тела запроса следует передать PDF файл.

Ответ:

{
  "sampleDDC": "MTEK"
}

• sampleDDC - сформированная Карточка с пробными данными.

# POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данных

Аутентификация основана на подписании пользователем блока случайных данных полученных от сервиса. Подготовительный этап заключается в передаче сервису запроса на новый блок случайных данных.

Важно! Каждый блок случйных данных может быть использован только один раз и имеет ограниченный срок действия.

Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам

Попробовать этот API в Postman

Запрос (Content-Type необходимо установить в application/json):

{
}

Ответ:

{
  "nonce": "base64_encoded_nonce"
}

• nonce - блок случайных данных в base64.

# POST /api/auth - аутентификация

Для выполнения аутентификации необходимо передать сервису цифровую подпись ранее полученного блока случайных данных. В том случае, если проверка подписи сервисом пройдет успешно, пользователь будет идентифицирован по данным содержащемся в его сертификате.

Поддерживается два режима работы:

• внутренняя аутентификация для нужд сервиса SIGEX;
• внешняя аутентификация для нужд сторонней информационной системы.

В режиме внутренней аутентификации для хранения информации об аутентификации используется cookie (Secure, HttpOnly и SameSite=Strict) с именем jwt в котором хранятся данные о прошедшем аутентификацию пользователе в формате JWT. Полезная нагрузка JWT токена содержит информацию, необходимую для идентификации пользователя.

При обращении к защищенным API сервис проверяет наличие в заголовках запроса cookie jwt и на основании данных в JWT токене принимает решение об авторизации.

В рамках обработки всех API выполняется проверка оставшего времени жизни JWT токена в cookie jwt и, при необходимости, его обновление. Новый JWT токен передается в ответе в cookie jwt.

Так же в режиме внутренней аутентификации в SIGEX будет создан профиль с настройками нового пользователя.

В режиме внешней аутентификации никаких cookie не устанавливается и профилей не создается, сторонняя информационная система получает ответ с данными сертификата которые она может использовать для авторизации (принятия решения о предоставлении пользователю прав доступа в систему).

Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам

Поддерживаются два типа подписей:

• CMS - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics или методом createCAdESFromBase64;
• XML - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics или методом signXml.

JS библиотека с открытым исходным кодом https://github.com/sigex-kz/ncalayer-js-client поддерживает все эти варианты.

CMS подписи поддерживаются в DER и PEM кодировках.

Попробовать этот API в Postman

Запрос (Content-Type необходимо установить в application/json):

{
  "nonce": "base64_encoded_nonce",
  "signature": "signature",
  "external": true
}

• nonce - блок случайных данных в base64 полученный от сервиса на подготовительном этапе;
• signature - в случае CMS это должна быть подпись в кодировке DER дополнительно закодированная в base64, либо в кодпировке PEM без дополнительного кодирования, в случае XML - текстовое представление XML;
• external - опциональное поле, позволяет установить режим внешней аутентификации, по умолчанию false.

Ответ:

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "email": "user@example.com",
  "subject": "SERIALINUMBER=IIN1234567890AB,CN=User",
  "subjectStructure": [
    [
      {
        "oid": "2.5.4.5",
        "name": "SERIALINUMBER",
        "valueInB64": false,
        "value": "IIN1234567890AB"
      }
    ],
    [
      {
        "oid": "2.5.4.3",
        "name": "CN",
        "valueInB64": false,
        "value": "User"
      }
    ]
  ],
  "subjectAltName": "rfc822Name=user@example.com",
  "subjectAltNameStructure": [
    {
      "type": "rfc822Name",
      "value": "user@example.com"
    }
  ],
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "keyStorage": "1.2.398.3.3.5.1.1",
  "policyIds": ["OID.0","OID.1"],
  "extKeyUsages": ["OID.0","OID.1"]
}

• userId - ИИН пользователя прошедшего аутентификацию;
• businessId - БИН пользователя прошедшего аутентификацию, доступен только в случае использования сертификата юридического лица;
• email - адрес электронной почты из subject, либо из subjectAltName, поле может отсутствовать в том случае, если электронная почта не указана (опциональное поле);
• subject - имя владельца (Subject) сертификата сформированное в соответствии с RFC 4514;
• subjectStructure - структурированное представление имени владельца (Subject) сертификата;
• subjectAltName - альтернативное имя владельца сертификата в соответствии с RFC 4514 (опциональное поле);
• subjectAltNameStructure - структурированное представление альтернативного имени владельца сертификата (опциональное поле);
• signAlgorithm - OID алгоритма подписи;
• keyStorage - OID типа хранилища (опциональное поле);
• policyIds - массив OID-ов политик использования сертификата;
• extKeyUsages - массив OID-ов расширенного использования ключа.

Структурированное представление имени владельца (Subject) сертификата - это массив, содержащий набор RDN, каждый из которых, в свою очередь, является массивом аттрибутов. Представление основывается на структуре поля Subject сертификата, описанного в RFC 5280.

Каждый атрибут представлен в виде объекта:

{
  "oid": "2.5.4.3",
  "name": "CN",
  "valueInB64": false,
  "value": "User CommonName",
}

• oid - объектный идентификатор типа атрибута;
• name - тестовое представление типа атрибута в соответствии со структурами регистрационных свидетельств (сертификатов) описанных в документе “Правила применения регистрационных свидетельств НУЦ РК” доступного на портале НУЦ РК в разделе Документация;
• valueInB64 - флаг, определяющий является ли значение в поле value строкой, либо base64 представлением бинарных данных;
• value - значение атрибута, значения некоторых атрибутов не могут быть представлены в текстовом виде, в этом случае в это поле будет записано base64 представление бинарного значения атрибута и valueInB64 будет установлен в true.

# POST /api/auth - сброс аутентификации

Технически сброс аутентификации заключается в возврате cookie с именем jwt с пустым значением, атрибутом Max-Age установленным в 0 и атрибутом Expires содержащим дату до текущей даты. Ожидаемая реакция совместимого браузера заключается в удалении cookie с именем jwt из локального хранилища.

Запрос (Content-Type необходимо установить в application/json):

{
  "logout": true
}

• logout - должно быть установлено в true.

Ответ:

{
}

# GET /api/auth - текущее состояние аутентификации

В случае том случае, если аутентификация пройдена и в заголовках запроса присутствовал cookie jwt, то ответ будет идентичен тому, который возвращает POST /api/auth - аутентификация.

# GET /api?from=xxx&until=yyy&organization=true&dataArchived=true - перечисление документов аутентифицированного пользователя или системы

• from=xxx - с какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;
• until=yyy - до какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;
• organization=true - опциональный параметр, определяет следует ли искать документы физического лица или организации, по умолчанию false;
• dataArchived=true - опциональный параметр, определяет следует ли искать документы, данные которых находятся в архиве или нет.

Ответ сервиса зависит от значения organization:

• false - в этом случае сервис вернет документы которые подписывал аутентифицированный пользователь:
  • при аутентификации с использованием сертификата физического лица сервис перечислит документы подписанные пользователем как физическим лицом;
  • при аутентификации с использованием сертификата сотрудника организации (юридического лица) сервис перечислит документы подписанные им как сотрудником организации;
  • при аутентификации информационной системой по двустороннему mTLS не перечислит ничего;
• true - в этом случае сервис вернет документы относящиеся к этой организации:
  • если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, либо в настройках организации указан ИИН данного сотрудника, либо сотрудник является первым руководителем, то сервис перечислит документы относящиеся к этой организации;
  • при аутентификации информационной системой по двустороннему mTLS и если для этой информационной системы в настройках организации предоставлены права перечисления документов организации, то сервис перечислит документы относящиеся к этой организации.

К документам организации относятся документы подписанные сотрудниками этой организации, а так же документы зарегистрированные информационными системами этой организации выполнившими аутентификацию по двустороннему mTLS.

Так же на ответ влияет значение dataArchived:

• false - в этом случае сервис вернет только те документы, подписанные данные которых не сохранены в архиве;
• true - в этом случае сервис вернет только те документы, подписанные данные которых сохранены в архиве;
• параметр отсутствует - в этом случае сервис не будет учитывать сохранены ли подписанные данные.

Сервис будет возвращать документы сортированными в порядке убывания даты их регистрации, то есть сначала самые новые.

Следует учитывать то, что данный метод возвращает ограниченное количество документов за один вызов, алгоритм получения всех документов:

1. получить первый блок документов установив желаемые from=xxx и until=yyy;
2. получить следующий блок докментов установив until=storedAt из последнего элемента массива документов;
3. повторять до тех пор пока сервис не вернет пустой массив.

Ответ:

{
  "documentsTotal": 3,
  "documents": []
}

• documentsTotal - количество документов удовлетворяющих запросу;
• documents - массив объектов документов.

Структура объекта данных документа:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "storedAt": 11111111111,
  "title": "document title",
  "description": "document description",
  "dataArchived": false,
  "signedDataSize": 123
}

• documentId - идентификатор документа;
• storedAt - момент регистрации документа в системе (миллисекунд с UNIX Epoch);
• title - заголовок документа;
• description - описание документа;
• dataArchived - информирует о том, находятся ли подписанные данные в архиве;
• signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0).

# GET /api/package?from=xxx&until=yyy&organization=true - перечисление пакетов документов аутентифицированного пользователя или системы

• from=xxx - с какого момента следует искать пакеты документов, значение следует указывать в миллисекундах с UNIX Epoch;
• until=yyy - до какого момента следует искать пакеты документов, значение следует указывать в миллисекундах с UNIX Epoch;
• organization=true - опциональный параметр, определяет следует ли искать пакеты документов физического лица или организации, по умолчанию false.

Ответ сервиса зависит от значения organization:

• false - в этом случае сервис вернет пакеты документов относящиеся к аутентифицированному пользователю:
  • при аутентификации с использованием сертификата физического лица сервис перечислит пакеты документов в правилах доступа к которым присутствует ИИН данного физического лица;
  • при аутентификации с использованием сертификата сотрудника организации (юридического лица) сервис перечислит пакеты документов в правилах доступа к которым присутствует комбинация ИИН (сотрудника) и БИН (юридического лица);
  • при аутентификации информационной системой по двустороннему mTLS сервис не перечислит ничего;
• true - в этом случае сервис вернет пакеты документов относящиеся к организации:
  • если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, либо в настройках организации указан ИИН данного сотрудника, либо сотрудник является первым руководителем, то сервис перечислит пакеты документов относящиеся к этой организации;
  • при аутентификации информационной системой по двустороннему mTLS и если для этой информационной системы в настройках организации предоставлены права перечисления пакетов документов организации, то перечислит пакеты документов относящиеся к этой организации.

К пакетам документов организации относятся такие пакеты документов, в правилах доступа к которым присутствует БИН данной организации, а так же пакеты документов зарегистрированные информационными системами этой организации выполнившими аутентификацию по двустороннему mTLS.

Сервис будет возвращать документы сортированными в порядке убывания даты их регистрации, то есть сначала самые новые.

Следует учитывать то, что данный метод возвращает ограниченное количество пакетов документов за один вызов, алгоритм получения всех пакетов документов:

1. получить первый блок пакетов документов установив желаемые from=xxx и until=yyy;
2. получить следующий блок пакетов документов установив until=storedAt из последнего элемента массива пакетов документов;
3. повторять до тех пор пока сервис не вернет пустой массив.

Ответ:

{
  "packagesTotal": 3,
  "packages": []
}

• packagesTotal - количество пакетов документов удовлетворяющих запросу;
• packages - массив объектов пакетов документов.

Структура объекта данных пакета документов:

{
  "packageId": "lQsqLBaS4nQAIIMm",
  "title": "package title",
  "description": "package description",
  "storedAt": 11111111111,
  "documentsIds": ["lQsqLBaS4nQAIIMm", "lQsqLBaS4nQAIIMm"]
}

• packageId - идентификатор пакета документов;
• title - заголовок пакета документов;
• description - описание пакета документов;
• storedAt - момент регистрации пакета документов в системе (миллисекунд с UNIX Epoch);
• documentsIds - массив идентификаторов документов входящих в данный пакет.

# GET /api/settings - получить настройки аутентифицированного пользователя

Ответ:

{
  "userId": "IIN123456789012",
  "emailNotificationsEnabled": true,
  "email": "user@example.com",
  "modifiedAt": 1585827107000,
  "dataArchiveEnabled": false,
  "dataArchiveQuota": 123,
  "dataArchiveQuotaExpires": 1585827107001,
  "dataArchiveUsage": 123,
  "dataArchiveContactEmail": "userArchiver@example.com"
}

• userId - ИИН пользователя;
• emailNotificationsEnabled - флаг указывающий включена ли отправка уведомлений по электронной почте для данного пользователя;
• email - электронный адрес пользователя, поле может содержать пустую строку ("");
• modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0;
• dataArchiveEnabled - флаг, указывающий активировано ли архивирование подписанных данных, если включен, необходимо указать dataArchiveContactEmail;
• dataArchiveQuota - размер текущей квоты архивирования (в байтах);
• dataArchiveQuotaExpires - опциональное поле, содержащее дату истечения срока действия дополнительной квоты (в миллисекундах с UNIX Epoch);
• dataArchiveUsage - объем хранящихся в архиве данных (в байтах);
• dataArchiveContactEmail - электронный адрес для отправки уведомлений, связанных с архивированием данных.

# POST /api/settings - сохранить настройки аутентифицированного пользователя

Запрос (Content-Type необходимо установить в application/json):

{
  "emailNotificationsEnabled": false,
  "email": "otheruser@example.com",
  "dataArchiveEnabled": true,
  "dataArchiveContactEmail": "userArchiver@example.com"
}

• emailNotificationsEnabled - новое значение флага указывающего включена ли отправка уведомлений по электронной почте для данного пользователя;
• email - новый электронный адрес пользователя, разрешено передавать пустую строку ("");
• dataArchiveEnabled - новое значение флага, позволяющего включить/отключить архивирование подписанных данных;
• dataArchiveContactEmail - новый электронный адрес для отправки уведомлений, связанных с архивированием данных.

Ответ:

{
  "userId": "IIN123456789012",
  "modifiedAt": 1585827107000
}

• userId - ИИН пользователя;
• modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.

# GET /api/settingsAudit?lastEventId=X - аудит изменений настроек пользователя

• lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек пользователя.

Ответ:

{
  "userId": "IIN112233445566",
  "eventsTotal": 3,
  "events": []
}

• userId - ИИН пользователя;
• eventsTotal - количество изменений зарегистрированных в системе;
• events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedAt": 1586167317737
}

• eventId - идентификатор события;
• original - настройки до изменения;
• modified - настройки после изменения;
• modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя

Настройки организации определяют уровень доступа к документам организации сотрудникам, имеющим указанные полномочия, и информационным системам, прошедшим аутентификацию по указанным клиентским сертификатам.

Подробнее о методах аутентификации и настройках читайте в разделе Аутентификация и контроль доступа.

Ответ:

{
  "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",
        "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"]
  },
  "webhooks":{
    "urls":["https://example.com/webhook-for-sigex","http://192.168.1.12"]
  },
  "modifiedAt": 1585827107000,
  "dataArchiveEnabled": false,
  "dataArchiveQuota": 123,
  "dataArchiveQuotaExpires": 1585827107001,
  "dataArchiveUsage": 123,
  "dataArchiveContactEmail": "orgArchiver@example.com",
  "subscriptionContactEmail": "orgSubscriber@example.com"
}

• businessId - БИН организации;
• tlsCertificatesList - массив клиентских сертификатов информационных систем;
• documentsAccess - контроль доступа к документам организации;
• documentsList - контроль доступа к перечислению документов организации;
• documentsSettings - контроль доступа к редактированию настроек документов организации;
• organizationSettings - контроль доступа к просмотру и редактированию настроек организации;
• webhooks - параметры доставки Webhook уведомлений;
• modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0;
• dataArchiveEnabled - флаг, указывающий активировано ли архивирование подписанных данных, если включен, необходимо указать dataArchiveContactEmail;
• dataArchiveQuota - размер текущей квоты архивирования (в байтах);
• dataArchiveQuotaExpires - опциональное поле, содержащее дату истечения срока действия дополнительной квоты (в миллисекундах с UNIX Epoch);
• dataArchiveUsage - объем хранящихся в архиве данных (в байтах);
• dataArchiveContactEmail - электронный адрес для отправки уведомлений, связанных с архивированием данных;
• subscriptionContactEmail - электронный адрес для отправки уведомлений, связанных с подпиской организации.

Элементы массива 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 (точно 100x200 пикселей) закодированный в base64;
• ddcLogoDisable - флаг позволяющий отключить нанесение логотипа на формируемые карточки электронных документов.

Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:

• authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;
• tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ;
• iins - массив ИИНов сотрудников организации, которые имеют доступ.

Поле webhooks имеет следующую структуру:

• urls - массив строк с URL для отправки Webhook уведомлений.

# POST /api/organizationSettings - сохранить настройки организации

Настройки организации позволяют предоставлять доступ к документам организации сотрудникам, имеющим указанные полномочия, и информационным системам, прошедшим аутентификацию по указанным клиентским сертификатам.

Подробнее о методах аутентификации и настройках читайте в разделе Аутентификация и контроль доступа.

Запрос (Content-Type необходимо установить в application/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",
        "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": []
  },
  "webhooks":{
    "urls":["https://example.com/webhook-for-sigex","http://192.168.1.12"]
  },
  "dataArchiveEnabled": true,
  "dataArchiveContactEmail": "orgArchiver@example.com",
  "subscriptionContactEmail": "orgSubscriber@example.com"
}

• tlsCertificatesList - массив клиентских сертификатов информационных систем;
• documentsAccess - контроль доступа к документам организации;
• documentsList - контроль доступа к перечислению документов организации;
• documentsSettings - контроль доступа к редактированию настроек документов организации;
• packagesAccess - контроль доступа к пакетам документов организации;
• packagesList - контроль доступа к перечислению пакетов документов организации;
• packagesSettings - контроль доступа к редактированию настроек пакетов документов организации;
• organizationSettings - контроль доступа к просмотру и редактированию настроек организации;
• webhooks - параметры доставки Webhook уведомлений;
• dataArchiveEnabled - новое значение флага, позволяющего включить/отключить архивирование подписанных данных;
• dataArchiveContactEmail - новый электронный адрес для отправки уведомлений, связанных с архивированием данных;
• subscriptionContactEmail - электронный адрес для отправки уведомлений, связанных с подпиской организации.

Элементы массива 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 (точно 100x200 пикселей) закодированный в base64;
• ddcLogoDisable - флаг позволяющий отключить нанесение логотипа на формируемые карточки электронных документов.

Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:

• authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;
• tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ;
• iins - массив ИИНов сотрудников организации, которым необходимо предоставить доступ.

Поле webhooks имеет следующую структуру:

• urls - массив строк с URL для отправки Webhook уведомлений.

Ответ:

{
  "businessId": "BIN123456789012",
  "modifiedAt": 1585827107000
}

• businessId - БИН организации;
• modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.

# GET /api/organizationSettingsAudit?lastEventId=X - аудит изменений настроек организации

• lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек организации.

Ответ:

{
  "businessId": "BIN112233445566",
  "eventsTotal": 3,
  "events": []
}

• businessId - БИН организации;
• eventsTotal - количество изменений зарегистрированных в системе;
• events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedBy": "IIN123456789",
  "modifiedByDigest": "XXXXXXXXXXXXXXX",
  "modifiedAt": 1586167317737
}

• eventId - идентификатор события;
• original - настройки до изменения;
• modified - настройки после изменения;
• modifiedBy - кем были произведены изменения, ИИН;
• modifiedByDigest - хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;
• modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# GET /api/organizationPermissions - получить права аутентифицированного пользователя в разрезе его организации

Ответ:

{
  "documentsAccess": true,
  "documentsList": true,
  "documentsSettings": true,
  "organizationSettings": true
}

• documentsAccess - имеет ли текущий аутентифицированный пользователь доступ к документам организации;
• documentsList - имеет ли текущий аутентифицированный пользователь право перечислять документы организации;
• documentsSettings - имеет ли текущий аутентифицированный пользователь право менять настройки документов организации;
• organizationSettings - имеет ли текущий аутентифицированный пользователь право менять настройки организации.

# GET /api/organizationSubscription - получить сведения о текущем тарифном плане организации

Для доступа к обработчику необходимы права доступа к настройкам организации.

Ответ:

{
	"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 - перечень известных строк через consts.subscriptions[name];
• expires - опциональная дата окончания действия подписки (миллисекунды с UNIX Epoch), для подписок без срока действия (в том числе базового бесплатного) вернет 0;
• contactEmail - опциональный email адрес по которому сервис отправляет уведомления, связанные с подпиской;
• features - массив объектов описывающих поддерживаемые сервисом функции:
  • name - имя функции на английском языке, переводы доступны в GET /api/strings - перечень известных строк через consts.subscriptionFeatures[name];
  • enabled - включена ли функция на данном уровне подписки.

# GET /api/idFromFileName/?name=XXX - получить идентификатор SIGEX из имени файла

• name=XXX - имя файла из которого необходимо извлечь идентификатор.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}

• documentId - полученный из имени файла идентификатор документа.

# GET /api/normalizeId/{specialId} - получить нормализованный идентификатор и его тип по специальному идентификатору

• specialId - специальный идентификатор.

Ответ:

{
  "id": "lQsqLBaS4nQAIIMm",
  "type": "document"
}

• id - нормализованный идентификатор;
• type - тип идентификатора, может быть:
  • "document" - идентификатор документа.

# GET /api/externalServicesStats - статистика доступности сторонних сервисов

Сервис постоянно поддерживает текущую статистику доступности различных сторонних сервисов, таких как OCSP и TSP НУЦ РК. Статистика формируется за некий определенный промежуток времени, обычно от 10 до 30 минут.

Для того, чтобы не раскрывать лишней информации, но при этом предотсавлять полезную статистику, мы решили выделить следующие статусы доступности:

• "white" - наш сервис в последнее время не обращался к данному сервису, статистика не доступна;
• "green" - в последнее время все обращения к сервису были успешны;
• "yellow" - в последнее время были как успешные, так и не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису;
• "red" - в последнее время были только не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису.

Ответ:

[
  {
    "protocol": "ocsp",
    "url": "http://ocsp.pki.gov.kz",
    "status": "yellow"
  },
  {
    "protocol": "tsp",
    "url": "http://tsp.pki.gov.kz",
    "status": "green"
  }
]

• protocol - протокол, такой как "ocsp", "tsp", либо какой-то другой;
• url - URL стороннего сервиса;
• status - состояние доступности в последнее время, может быть "white", "green", "yellow" или "red".

# GET /api/strings - перечень известных строк

Ответ:

{
  "errorMessages": {
    "Access denied": {
      "ru": "доступ запрещен",
      "kk": "қосылуға мүмкіндік жоқ",
      "description": "сервис возвращает эту ошибку при попытке выполнить действие, для выполнения которого у текущего аутентифицированного пользователя или ИС не достаточно прав"
    },
    ...
  },
  "consts": {
    "OIDs": {
      "1.2.398.3.10.1.1.1.1": {
        "ru": "Ключ ГОСТ 34.310-2004",
        "kk": "МЕМСТ 34.310-2004 кілт"
      },
      ...
    },
    "policyOIDs": {
      "1.2.398.3.3.2.1": {
        "ru": "Политика применения регистрационных свидетельств электронной цифровой подписи юридических лиц Республики Казахстан",
        "kk": "Қазақстан Республикасы заңды тұлғаларының электрондық цифрлық қолтаңбасын тіркеу куәліктерін қолдану саясаты"
      },
      ...
    },
    "timeStampPolicyOIDs": {
      "1.2.398.3.3.2.6.1": {
        "ru": "Политика для подписи квитанции метки времени на алгоритме ГОСТ 34.310-2004 с OID 1.2.398.3.10.1.1.1.2",
        "kk": "OID 1.2.398.3.10.1.1.1.2 бар ГОСТ 34.310-2004 алгоритмінде уақыт белгісі түбіртегіне қол қоюға арналған саясат"
      },
      ...
    },
    "extKeyUsageOIDs": {
      "1.2.398.3.3.4.1.1": {
        "ru": "Физическое лицо",
        "kk": "Жеке тұлға"
      },
      ...
    },
    "signatureAlgorithmOIDs": {
      "1.2.398.3.10.1.1.1.2": {
        "ru": "Подпись ГОСТ 34.310-2004",
        "kk": "МЕМСТ 34.310-2004 қолтаңбасы"
      },
      ...
    },
    "ncaAuthorityOIDs": {
      "1.2.398.3.3.4.1.2.1": {
        "ru": "Первый руководитель юридического лица/совместное предпринимательство",
        "kk": "Заңды тұлғаның бірінші басшысы/бірлескен кәсіпкерлік"
      },
      ...
    },
    "keyStorageOIDs": {
      "1.2.398.3.3.5": {
        "ru": "Хранилище ключей",
        "kk": "Кілттер қоймасы"
      },
      ...
    },
    "keyUsages": {
      "cRLSign": {
        "ru": "Подписание CRL",
        "kk": "CRL қол қою"
      },
      ...
    }
  }
}

• errorMessages - реестр всех сообщений об ошибках, которые может возвращать сервис в виде объекта, поля которого - строки сообщений, а значения содержат перевод и описание;
• consts - реестр известных OIDов и других специфических строк, поля - строки, значения содержат перевод:
  • OIDs - все известные OIDы,
  • policyOIDs - OIDы политик сертификатов,
  • timeStampPolicyOIDs - OIDы политик TSP,
  • extKeyUsageOIDs - OIDы значений расширенного использования ключа,
  • signatureAlgorithmOIDs - OIDы алгоритмов ЭЦП,
  • ncaAuthorityOIDs - OIDы полномочий НУЦ,
  • keyStorageOIDs - OIDы типов хранилищ ключей ЭЦП,
  • keyUsages - константы использования ключа.

# GET /api/version - версия сервиса

Ответ:

{
  "version":"vX.X.X",
  "buildTimeStamp":"XXXXXXXXXX",
  "licenseOwner":"BIN200240002381",
  "licenseUntil":"2030-09-04"
}

• version - версия сервиса;
• buildTimeStamp - время сборки сервиса в секундах с UNIX Epoch;
• licenseOwner - владелец лицензии (BIN);
• licenseUntil - дата окончания действия лицензии (UTC).

# POST /api/egovQr - зарегистрировать новую процедуру подписания ЭЦП через QR

Поддержка подписания ЭЦП через QR (так же известного как QR подписание) реализована с помощью трех обращений к сервису:

• регистрация новой процедуры подписания, в результате клиент получает QR код (плюс ссылки для запуска приложений) и две ссылки для последующих обращений, одну для отправки данных, другую для получения подписей;
• отправку данных на подписание методом POST по полученной ранее ссылке для отправки данных;
• получение подписей методом GET по полученной ранее ссылке для получения подписей.

QR код следует отобразить пользователю для того, чтобы он считал его приложением eGov mobile (либо eGov Business) на своем мобильном телефоне. То есть участвуют два устройства:

• на первом устройстве (ПК, ноутбук, планшет или первый мобильный телефон) отображается QR код;
• на втором (планшет или мобильный телефон) пользователь открывает eGov mobile или eGov Business и сканирует QR код отображенный на экране первого устройства.

Так же в ответ включены диплинки для запуска приложений eGov mobile и eGov Business на том же устройстве. Эти диплинки можно отобразить на мобильном устройстве в том случае, если предполагается использовать только одно устройство (мобильный телефон), на котором установлен eGov mobile или eGov Business (кросс подписание). Когда пользователь кликнет по диплинку, откроется соответствующее приложение с запущенной процедурой подписания.

Каждый полученный QR код (либо один из диплинков) можно использовать только один раз. Срок действия процедуры подписания ограничен, он указан в поле expireAt.

Доступен упрощенный API для работы с eGov mobile/business: POST /api/{id}/egovQr - регистрация процедуры упрощенного подписания через QR или диплинки.

Попробовать этот API в Postman

Запрос (Content-Type необходимо установить в application/json):

{
  "description": "Пакет документов на подписание"
}

• description - описание подписываемых данных, эта строка будет отображна в приложении eGov mobile после считывания QR кода.

Ответ:

{
  "expireAt": 1668758024082,
  "qrCode": "XXXXX",
  "eGovMobileLaunchLink": "http://...",
  "eGovBusinessLaunchLink": "http://...",
  "dataURL": "some-url",
  "signURL": "some-url"
}

• expireAt - момент истечения срока действия процедуры подписания ЭЦП через QR в миллисекундах с UNIX Epoch;
• qrCode - строка, закодированное в base64 изображение в формате PNG с закодированным QR кодом для приложения eGov mobile;
• eGovMobileLaunchLink - диплинк для запуска eGov mobile на том же устройстве;
• eGovBusinessLaunchLink - диплинк для запуска eGov Business на том же устройстве;
• dataURL - ссылка для отправки данных на подписание, это полная ссылка, ее следует использовать “как есть” для POST /api/egovQr/{qrId} - отправка данных на подписание;
• signURL - ссылка для получения сформированных подписей, это полная ссылка, ее следует использовать “как есть” для GET /api/egovQr/{qrId} - получение подписей.

# POST /api/egovQr/{qrId} - отправка данных на подписание

Ссылку на этот API не следует формировать самостоятельно, ее следует получать из поля dataURL ответа POST /api/egovQr - зарегистрировать новую процедуру подписания ЭЦП через QR.

В рамках обработки этого запроса сервис откроет соединение, но не будет принимать данные запроса до тех пор, пока к нему не подключится приложение eGov mobile и не начнет скачивать данные, то есть:

• этот запрос может обрабатываться довольно долго, фактически сервис вернет ответ примерно в то же время, когда приложение eGov mobile на мобильном телефоне пользователя закончит выкачивать данные и отобразит их пользователю;
• так как сервис откроет соединение, но не будет принимать данные продолжительное время, соединение может разорваться по таймауту (установленном в клиентской библиотеке, либо на промежуточном сетевом оборудовании);
• до тех пор, пока клиент не получил HTTP ответа от сервиса (то есть в случае разрыва соединения по таймауту, либо других ошибок уровня TCP) он может повторно пытаться отправлять этот запрос, сервис будет обрабатывать только последний поступивший запрос.

Тело запроса должно представлять из себя тот блок данных, который ожидает получить приложение eGov mobile (GET запрос на API N2 в документации по подписанию ЭЦП через QR), сервис не будет его анализировать, дополнять или изменять.

Структура запроса здесь приведена для ознакомительных целей, актуальная структура доступна в документации по подписанию ЭЦП через QR eGov mobile.

Попробовать этот API в Postman

Запрос (Content-Type необходимо установить в application/json):

{
  "signMethod": "CMS_SIGN_ONLY",
  "documentsToSign": []
}

• signMethod - метод подписания, поддерживатся "CMS_WITH_DATA", "CMS_SIGN_ONLY" и "XML";
• documentsToSign - массив объектов данных для подписания.

Формат объекта данных для подписания:

{
  "id": 1,
  "nameRu": "Договор поставки",
  "nameKz": "Жеткізу шарты",
  "nameEn": "Supply contract",
  "meta": [
    {
      "name": "Номер договора",
      "value": "1234"
    },
    {
      "name": "Контрагент",
      "value": "ТОО Контрагент"
    }
  ],
  "document": {
    "file": {
      "mime": "@file/pdf",
      "data": "MTEK"
    }
  },
  "documentXml": "<groupId>2</groupId>"
}

• id - уникальный идентификатор подписываемого документа;
• nameRu - имя подписываемого документа для отображения в интерфейсе eGov mobile на русском языке;
• nameKz - имя подписываемого документа для отображения в интерфейсе eGov mobile на казахском языке;
• nameEn - имя подписываемого документа для отображения в интерфейсе eGov mobile на английском языке;
• meta - массив объектов метаинформации, содержащих поля name и value;
• document - это поле должно присутствовать только в том случае, если signMethod установлен в "CMS_WITH_DATA" или "CMS_SIGN_ONLY", в качестве значения следует использовать объект с единственным полем file, содержащий объект с полями mime (в том случае, если передаваемые на подпись данные являются PDF файлом, рекомендуется установить в "@file/pdf") и data (бинарные подписываемые данные закодированные в base64 строку);
• documentXml - это поле должно присутствовать только в том случае, если signMethod установлен в "XML", в качестве значения следует использовать строку XML данных на подписание.

Ответ:

{
  "expireAt": 1668758024082,
  "signURL": "some-url"
}

• expireAt - момент истечения срока действия процедуры подписания ЭЦП через QR в миллисекундах с UNIX Epoch;
• signURL - ссылка для получения сформированных подписей, это полная ссылка, ее следует использовать “как есть”.

# GET /api/egovQr/{qrId} - получение подписей

Ссылку на этот API не следует формировать самостоятельно, ее следует получать из поля signURL ответа POST /api/egovQr - зарегистрировать новую процедуру подписания ЭЦП через QR.

В рамках обработки этого запроса сервис откроет соединение, но не будет возвращать ответ до тех пор, пока к нему не подключится приложение eGov mobile и не начнет возвращать ответ, то есть:

• этот запрос может обрабатываться довольно долго, фактически сервис вернет ответ только после того, как пользователь подпишет данные в мобильном приложении eGov mobile;
• так как сервис откроет соединение, но не будет возвращать ответ продолжительное время, соединение может разорваться по таймауту (установленном в клиентской библиотеке, либо на промежуточном сетевом оборудовании);
• до тех пор, пока клиент не получил HTTP ответа от сервиса (то есть в случае разрыва соединения по таймауту, либо других ошибок уровня TCP) он может повторно пытаться отправлять этот запрос, сервис будет обрабатывать только последний поступивший запрос.

Тело ответа будет представлять из себя тот блок данных, который возвращает приложение eGov mobile (PUT запрос на API N2 в документации по подписанию ЭЦП через QR), сервис не будет его анализировать, дополнять или изменять.

Структура ответа здесь приведена для ознакомительных целей, актуальная структура доступна в документации по подписанию ЭЦП через QR eGov mobile.

Попробовать этот API в Postman

Ответ::

{
  "signMethod": "CMS_SIGN_ONLY",
  "documentsToSign": []
}

• signMethod - метод подписания;
• documentsToSign - массив объектов данных с подписями.

Формат обекта данных с подписью:

{
  "id": 1,
  "nameRu": "Договор поставки",
  "nameKz": "Жеткізу шарты",
  "nameEn": "Supply contract",
  "meta": [
    {
      "name": "Номер договора",
      "value": "1234"
    },
    {
      "name": "Контрагент",
      "value": "ТОО Контрагент"
    }
  ],
  "document": {
    "file": {
      "mime": "@file/pdf",
      "data": "MTEK"
    }
  },
  "documentXml": "<groupId>2</groupId>"
}

• id - уникальный идентификатор подписанного блока данных;
• nameRu - имя подписанного документа на русском языке;
• nameKz - имя подписанного документа на казахском языке;
• nameEn - имя подписанного документа на английском языке;
• meta - массив объектов метаинформации, содержащих поля name и value;
• document - это поле будет заполнено только в том случае, если signMethod установлен в "CMS_WITH_DATA" или "CMS_SIGN_ONLY", объект с единственным полем file, содержащий объект с полями mime (в том случае, если передаваемые на подпись данные являются PDF файлом, рекомендуется установить в "@file/pdf") и data (CMS подпись закодированная в base64 строку);
• documentXml - это поле будет заполнено только в том случае, если signMethod установлен в "XML", строка XML подписи.

Известные строки