API: базовый eGov m/b


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

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": "https://...",
  "eGovBusinessLaunchLink": "https://...",
  "dataURL": "some-url",
  "dataURLmTLS": "some-url",
  "dataURLAuto": "some-url",
  "signURL": "some-url",
  "signURLmTLS": "some-url",
  "signURLAuto": "some-url"
}
  • expireAt - момент истечения срока действия процедуры подписания ЭЦП через QR в миллисекундах с UNIX Epoch;
  • qrCode - строка, закодированное в base64 изображение в формате PNG с закодированным QR кодом для приложения eGov mobile;
  • eGovMobileLaunchLink - диплинк для запуска eGov mobile на том же устройстве;
  • eGovBusinessLaunchLink - диплинк для запуска eGov Business на том же устройстве;
  • dataURL - ссылка для отправки данных на подписание, это полная ссылка (без mTLS), ее следует использовать “как есть” для POST /api/egovQr/{qrId} - отправка данных на подписание;
  • dataURLmTLS - аналог dataURL для mTLS соединений;
  • dataURLAuto - вернет dataURL если запрос был отправлен без mTLS и dataURLmTLS если через mTLS;
  • signURL - ссылка для получения сформированных подписей, это полная ссылка (без mTLS), ее следует использовать “как есть” для GET /api/egovQr/{qrId} - получение подписей;
  • signURLmTLS - аналог dataURL для mTLS соединений;
  • signURLAuto - вернет dataURL если запрос был отправлен без mTLS и dataURLmTLS если через mTLS.

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", "SIGN_BYTES_ARRAY" и "MIX_SIGN";
  • 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 строку);
    • если signMethod установлен в "SIGN_BYTES_ARRAY", в качестве значения следует использовать объект с единственным полем file, содержащий объект с полями mime (значение всегда должно быть "") и data (строка текста для которой будет вычислена подпись);
  • documentXml - это поле должно присутствовать только в том случае, если signMethod установлен в "XML", в качестве значения следует использовать строку XML данных на подписание.

Ответ:

{
  "expireAt": 1668758024082,
  "signURL": "some-url",
  "signURLmTLS": "some-url",
  "signURLAuto": "some-url"
}
  • expireAt - момент истечения срока действия процедуры подписания ЭЦП через QR в миллисекундах с UNIX Epoch;
  • signURL - ссылка для получения сформированных подписей, это полная ссылка (без mTLS), ее следует использовать “как есть” для GET /api/egovQr/{qrId} - получение подписей;
  • signURLmTLS - аналог dataURL для mTLS соединений;
  • signURLAuto - вернет dataURL если запрос был отправлен без mTLS и dataURLmTLS если через mTLS.

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 и data (CMS подпись закодированная в base64 строку);
    • если signMethod установлен в "SIGN_BYTES_ARRAY", объект с единственным полем file, содержащий объект с полями mime и data (JSON строка с закодированным объектом содержащим поля signature и certificate с сырой подписью и сертификатом);
  • documentXml - это поле будет заполнено только в том случае, если signMethod установлен в "XML", строка XML подписи.

Разработано в ТОО "Множество" в 2026 году