# API: базовый eGov m/b
## Коллекции для Postman {#postman-collections}
- [ЭЦП через QR на базе eGov mobile](../%D0%AD%D0%A6%D0%9F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20QR%20%D0%BD%D0%B0%20%D0%B1%D0%B0%D0%B7%D0%B5%20eGov%20mobile.postman_collection.json)
***
## `POST` `/api/egovQr` - зарегистрировать новую процедуру подписания ЭЦП через QR {#egov-qr}
Поддержка [подписания ЭЦП через QR (так же известного как QR подписание)](https://sb.egov.kz/services/passport/NITEC-S-5096) реализована с помощью трех обращений к сервису:
- регистрация новой процедуры подписания, в результате клиент получает 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 или диплинки](/kk/support/developers/api-documents/index.md#document-sign-via-egov-qr).
[Попробовать этот API в Postman](#postman-collections)
Запрос (`Content-Type` необходимо установить в `application/json`):
```json
{
"description": "Пакет документов на подписание",
"whenDone": {
"backUrl": "https://some-site.kz/view/docid"
}
}
```
- `description` - описание подписываемых данных, эта строка будет отображена в приложении eGov mobile после считывания QR кода;
- `whenDone` - опциональное поле, объект позволяющий передать в eGov mobile/business настройки поведения после завершения подписания:
- `backUrl` - опциональное поле, URL для возврата в вызывающее приложение или на веб сайт, может быть как в обычном формате `"https://some-site.kz/something"`, так и в формате зарегистрированных префиксов приложений, к примеру для Telegram может быть `"tg://path?query"` https://core.telegram.org/api/links.
Ответ:
```json
{
"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}` - отправка данных на подписание](/kk/support/developers/api-egov-basic/index.md#egov-qr-send-data);
- `dataURLmTLS` - аналог `dataURL` для mTLS соединений;
- `dataURLAuto` - вернет `dataURL` если запрос был отправлен без mTLS и `dataURLmTLS` если через mTLS;
- `signURL` - ссылка для получения сформированных подписей, это полная ссылка (без mTLS), ее следует использовать "как есть" для [`GET` `/api/egovQr/{qrId}` - получение подписей](/kk/support/developers/api-egov-basic/index.md#egov-qr-get-signatures);
- `signURLmTLS` - аналог `signURL` для mTLS соединений;
- `signURLAuto` - вернет `signURL` если запрос был отправлен без mTLS и `signURLmTLS` если через mTLS.
***
## `POST` `/api/egovQr/{qrId}` - отправка данных на подписание {#egov-qr-send-data}
Ссылку на этот API не следует формировать самостоятельно, ее следует получать из поля `dataURL` ответа [`POST` `/api/egovQr` - зарегистрировать новую процедуру подписания ЭЦП через QR](/kk/support/developers/api-egov-basic/index.md#egov-qr).
В рамках обработки этого запроса сервис откроет соединение, но не будет принимать данные запроса до тех пор, пока к нему не подключится приложение eGov mobile и не начнет скачивать данные, то есть:
- этот запрос может обрабатываться довольно долго, фактически сервис вернет ответ примерно в то же время, когда приложение eGov mobile на мобильном телефоне пользователя закончит выкачивать данные и отобразит их пользователю;
- так как сервис откроет соединение, но не будет принимать данные продолжительное время, соединение может разорваться по таймауту (установленном в клиентской библиотеке, либо на промежуточном сетевом оборудовании);
- до тех пор, пока клиент не получил `HTTP` ответа от сервиса (то есть в случае разрыва соединения по таймауту, либо других ошибок уровня `TCP`) он может повторно пытаться отправлять этот запрос, сервис будет обрабатывать только последний поступивший запрос.
Тело запроса должно представлять из себя тот блок данных, который ожидает получить приложение eGov mobile (`GET` запрос на `API N2` в документации по подписанию ЭЦП через QR), сервис не будет его анализировать, дополнять или изменять.
Структура запроса здесь приведена для ознакомительных целей, актуальная структура доступна в документации по подписанию ЭЦП через QR eGov mobile.
[Попробовать этот API в Postman](#postman-collections)
Запрос (`Content-Type` необходимо установить в `application/json`):
```json
{
"signMethod": "CMS_SIGN_ONLY",
"documentsToSign": []
}
```
- `signMethod` - метод подписания, поддерживатся `"CMS_WITH_DATA"`, `"CMS_SIGN_ONLY"`, `"XML"`, `"SIGN_BYTES_ARRAY"` и `"MIX_SIGN"`;
- `documentsToSign` - массив объектов данных для подписания.
Формат объекта данных для подписания:
```json
{
"id": 1,
"nameRu": "Договор поставки",
"nameKz": "Жеткізу шарты",
"nameEn": "Supply contract",
"meta": [
{
"name": "Номер договора",
"value": "1234"
},
{
"name": "Контрагент",
"value": "ТОО Контрагент"
}
],
"document": {
"file": {
"mime": "@file/pdf",
"data": "MTEK"
}
},
"documentXml": "2"
}
```
- `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` данных на подписание.
Ответ:
```json
{
"expireAt": 1668758024082,
"signURL": "some-url",
"signURLmTLS": "some-url",
"signURLAuto": "some-url"
}
```
- `expireAt` - момент истечения срока действия процедуры подписания ЭЦП через QR в миллисекундах с UNIX Epoch;
- `signURL` - ссылка для получения сформированных подписей, это полная ссылка (без mTLS), ее следует использовать "как есть" для [`GET` `/api/egovQr/{qrId}` - получение подписей](/kk/support/developers/api-egov-basic/index.md#egov-qr-get-signatures);
- `signURLmTLS` - аналог `signURL` для mTLS соединений;
- `signURLAuto` - вернет `signURL` если запрос был отправлен без mTLS и `signURLmTLS` если через mTLS.
***
## `GET` `/api/egovQr/{qrId}` - получение подписей {#egov-qr-get-signatures}
Ссылку на этот API не следует формировать самостоятельно, ее следует получать из поля `signURL` ответа [`POST` `/api/egovQr` - зарегистрировать новую процедуру подписания ЭЦП через QR](/kk/support/developers/api-egov-basic/index.md#egov-qr).
В рамках обработки этого запроса сервис откроет соединение, но не будет возвращать ответ до тех пор, пока к нему не подключится приложение eGov mobile и не начнет возвращать ответ, то есть:
- этот запрос может обрабатываться довольно долго, фактически сервис вернет ответ только после того, как пользователь подпишет данные в мобильном приложении eGov mobile;
- так как сервис откроет соединение, но не будет возвращать ответ продолжительное время, соединение может разорваться по таймауту (установленном в клиентской библиотеке, либо на промежуточном сетевом оборудовании);
- до тех пор, пока клиент не получил `HTTP` ответа от сервиса (то есть в случае разрыва соединения по таймауту, либо других ошибок уровня `TCP`) он может повторно пытаться отправлять этот запрос, сервис будет обрабатывать только последний поступивший запрос.
Тело ответа будет представлять из себя тот блок данных, который возвращает приложение eGov mobile (`PUT` запрос на `API N2` в документации по подписанию ЭЦП через QR), сервис не будет его анализировать, дополнять или изменять.
Структура ответа здесь приведена для ознакомительных целей, актуальная структура доступна в документации по подписанию ЭЦП через QR eGov mobile.
[Попробовать этот API в Postman](#postman-collections)
Ответ:
```json
{
"signMethod": "CMS_SIGN_ONLY",
"documentsToSign": []
}
```
- `signMethod` - метод подписания;
- `documentsToSign` - массив объектов данных с подписями.
Формат объекта данных с подписью:
```json
{
"id": 1,
"nameRu": "Договор поставки",
"nameKz": "Жеткізу шарты",
"nameEn": "Supply contract",
"meta": [
{
"name": "Номер договора",
"value": "1234"
},
{
"name": "Контрагент",
"value": "ТОО Контрагент"
}
],
"document": {
"file": {
"mime": "@file/pdf",
"data": "MTEK"
}
},
"documentXml": "2"
}
```
- `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` подписи.