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

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

Для разработчиков

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

Введение
Сообщения об ошибках
- Перечень возможных сообщений об ошибках
Методы API

# Введение

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

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

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

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

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

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

“Unexpected error” - “непредвиденная ошибка”, подобное сообщение сигнализирует о неизвестной нам проблеме на сервере;
“Failed to parse JSON” - “не удалось разобрать JSON запрос”, JSON запрос был закодирован не корректно, проверьте код формирования запроса;
“Invalid JSON request structure” - “не корректная структура JSON запроса”, в запросе отсутствуют какие-то необходимые поля, либо присутствуют лишние;
“This signature has already been submitted” - “данная подпись уже была зарегистрирована”, сервис не поддерживает регистрацию одной и той же подписи несколько раз, в том случае, если необходимо повторно подписать документ, подпись можно вычислить повторно с помощью метода createCMSSignatureFromBase64 NCALayer, бинарно это будет другая подпись;
“Document not found” - “документ не найден”, идентификатор документа указан не верно;
“Invalid document identifier” - “не корректный идентификатор документа”, формат идентификатора документа не корректен (не соответствуют длина, либо содержимое);
“Invalid signature identifier” - “не корректный идентификатор подписи”, формат идентификатора подписи не корректен (не соответствуют длина, либо содержимое);
“Invalid signature export format” - “не корректный формат экспорта”, запрошенный формат экспорта не поддерживается сервисом;
“Failed to parse signature” - “не удалось разобрать подпись”, данные подписи были повреждены, либо не правильно закодированы;
“Invalid signature” - “не корректная подпись”, подпись разобрать удалось, но ее состав не соответствует ожидаемому, вероятно подпись была получена не поддерживаемым способом;
“Bad signer certificate” - “плохой сертификат подписавшего”, для подписания был использован плохой сертификат (просрочен, либо выпущен по не поддерживаемому шаблону, либо это сертификат для аутентификации);
“Request body too large” - “размер запроса слишком велик”, сервис накладывает ограничения на размер определенных запросов;
“Invalid URL query parameter” - “не корректный URL параметр запроса”, передан непредусмотренный URL параметр, либо не передан необходимый;
“Invalid HTTP request headers” - “не корректный заголовок запроса”, передан некорректный заголовок;
“Invalid API route” - “не корректный маршрут”, запрос отправлен на не поддерживаемый маршрут;
“Invalid HTTP request method” - “не корректный HTTP метод”, запрос отправлен с использованием не поддерживаемого HTTP метода;
“Document digests are not known” - “хеши документа не известны”, свидетельствует о не завершенной регистрации документа в системе;
“Invalid document” - “не корректный документ”, свидетельствует о том, что переданный на проверку документ не является тем, который был подписан (произошла либо подмена, либо модификация документа);
“Document digests are already known” - “хеши документа уже известны”, свидетельствует о повторной попытке закончить регистрацию документа;
“Signature does not correspond to the document” - “подпись не соответствует документу”, свидетельствует о попытке зарегистрировать подпись к документу к которому она не относится (то есть был зарегистрирован некий документ с первой подписью, вторая регистрируемая подпись была вычислена не от оригинального документа);
“OCSP server problem” - “проблема с OCSP сервером”, произошла какая-то проблема связанная с получением статуса сертификата по протоколу OCSP от сервера НУЦ;
“Failed to build certificate chain” - “не удалось построить цепочку сертификатов”, свидетельствует о проблеме с сертификатом, использованном для подписания документа, вероятно он не был выпущен НУЦ;
“Invalid certificate status” - “не корректный статус сертификата”, сертификат, использованный для подписания, отозван, либо OCSP сервер НУЦ вернул не корректный статус сертификата;
“TSP server problem” - “проблема с TSP сервером”, произошла какая-то проблема связанная с получением метки времени (TSP) от сервера НУЦ.
“Signature contains invalid TSP time stamp” - “подпись содержит поврежденную или не корректную метку времени TSP”, метка времени в проверяемой подписе отличается от метки, хранимой в базе данных сервиса. Также данная ошибка может возвращаться в том случае когда проверяемая подпись не содержит метку времени, но включает в себя OCSP квитанцию.
“Signature contains invalid OCSP data” - “подпись содержит поврежденные или не корректные данные OCSP”, проверяемая подпись содержит квитанцию OCSP отличающуюся от хранимой в базе данных сервиса. Также данная ошибка может возвращаться в случаях, когда либо формат данных о статусе отзыва сертификата (значение атрибута CMS revocation-values) отличается от принятого в системе, либо проверяемая подпись не содержит квитанцию OCSP, но включает в себя TSP метку времени.
“Invalid authentication nonce” - “не верный nonce аутентификации”, свидетельствует о том что nonce, использованный при попытке аутентификации, либо не был получен от сервиса, либо просрочен, либо уже был использован.
“Authentication required” - “требуется аутентификация”, эту ошибку сервис вернет при попытке обратиться к требующим аутентификации API не пройдя аутентификацию.
“User does not represent an organization” - “пользователь не является представителем организации”, эту ошибку сервис вернет при попытке поиска документов организации пользователем без достаточных прав, в частности в том случае когда его сертификат не содержит БИН в имени владельца или в сертификате не указаны необходимые полномочия.
“One of the provided notification email addresses is in invalid format” - “не корректный формат одрого из адресов электронной почты для отправки уведомлений”, при регистрации нового документа был указан адрес электронной почты не корректного формата.
“Too many notification email addresses provided” - “указано слишком много адресов электронной почты для рассылки уведомлений”, при регистрации нового документа было указано слишком много адресов электронной почты.
“Signature type is not supported” - “не поддердживаемый тип подписи”, указанный тип подписи не поддерживается сервисом.
“QR code versions lower than 11 are not allowed” - “версии QR кодов ниже 11 не поддерживаются”, эту ошибку сервис вернет при попытке формирования QR кодов версии ниже 11.
“Signer certificate expired or not yet valid” - “срок действия сертификата уже истек, либо еще не наступил”, уведомляет о проблеме со сроком действия сертификата субъекта подписавшего документ.

# Методы API

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

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

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

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

CMS - можно получить у NCALayer методом createCMSSignatureFromBase64;
XML - можно получить у NCALayer методом signXml, но с некоторыми оговорками (см. ниже).

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

Сервис допускает наличие данных 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.

Запрос:

{
  "title": "document title",
  "description": "document description",
  "signType": "cms",
  "signature": "base64_encoded_cms",
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
  },
}

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

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}

documentId - уникальный идентификатор зарегистрированного документа.

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

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

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

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

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

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

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

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

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

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "digests": {
    "oid": "base64_encoded_digest_value",
    "otherOid": "base64_encoded_digest_value",
  },
  "emailNotifications": {
    "attached": true,
    "message": "Failed to send  notification"
  },
  "automaticallyCreatedUserSettings":
  {
    "userId": "IIN123456789012",
    "emailNotificationsEnabled": true,
    "email": "email@GMAIL.COM",
    "modifiedAt": 1586167317737
  }
}

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

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

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

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

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

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

Ответ:

{
  "title": "document title",
  "description": "document description",
  "signaturesTotal": 2,
  "signatures": [
  ],
}

title - заголовок документа;
description - описание документа;
signaturesTotal - общее количество подписей документа;
signatures - массив объектов с данными о подписях документа.

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

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "subject": "SERIALINUMBER=IIN1234567890AB, CN=User",
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "policyIds": ["OID.0","OID.1"],
  "extKeyUsages": ["OID.0","OID.1"],
  "storedAt": 1568809427182,
  "signId": 1,
  "signType": "cms"
}

userId - ИИН подписавшего;
businessId - БИН подписавшего, доступен только в случае использования сертификата юридического лица;
subject - имя владельца (Subject) сертификата;
signAlgorithm - OID алгоритма подписи;
policyIds - массив OID-ов политик использования сертификата подписавшего;
extKeyUsages - массив OID-ов расширенного использования ключа;
storedAt - время сохранения подписи в системе (миллисекунд с UNIX Epoch);
signId - уникальный идентификатор подписи в системе;
signType - тип подписи, поддерживается два строковых значения "cms" и "xml".

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

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

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

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

CMS - можно получить у NCALayer методом createCMSSignatureFromBase64;
XML - можно получить у NCALayer методом signXml, но с некоторыми оговорками (см. ниже).

Запрос:

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

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

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "automaticallyCreatedUserSettings":
  {
    "userId": "IIN123456789012",
    "emailNotificationsEnabled": true,
    "email": "email@GMAIL.COM",
    "modifiedAt": 1586167317737
  }
}

documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings.

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

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

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

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

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

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

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}

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

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

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

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

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": "base64_encoded_cms"
}

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/exported` - получение идентификаторов документа и подписи по ранее экспортированной подписи документа

В передаваемой подписи допускается наличие метки времени TSP (signature-time-stamp) и квитанции OCSP (revocation-values).

В частности поддерживаются подписи полученные следующими способами:

через API SIGEX с помощью запроса GET /api/{id}/signature/{signId};
методом createCMSSignatureFromBase64 NCALayer - такая подпись содержит метку времени, но не содержит квитанцию OCSP;
методом createCAdESFromBase64 NCALayer - такая подпись не содержит ни метки времени, ни квитанции OCSP.

Запрос:

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

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

Ответ:

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

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

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

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

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

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

Запрос:

{
}

Ответ:

{
  "nonce": "base64_encoded_nonce"
}

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

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

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

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

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

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

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

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

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

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

Запрос:

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

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

Ответ:

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "subject": "SERIALINUMBER=IIN1234567890AB, CN=User",
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "policyIds": ["OID.0","OID.1"],
  "extKeyUsages": ["OID.0","OID.1"]
}

userId - ИИН пользователя прошедшего аутентификацию;
businessId - БИН пользователя прошедшего аутентификацию, доступен только в случае использования сертификата юридического лица;
subject - имя владельца (Subject) сертификата;
signAlgorithm - OID алгоритма подписи;
policyIds - массив OID-ов политик использования сертификата;
extKeyUsages - массив OID-ов расширенного использования ключа.

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

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

Запрос:

{
  "logout": true
}

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

Ответ:

{
}

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

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

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

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

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

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

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

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

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

Ответ:

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

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

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

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "storedAt": 11111111111,
  "title": "document title",
  "description": "document description"
}

documentId - уникальный идентификатор документа;
storedAt - момент регистрации документа в системе (миллисекунд с UNIX Epoch).;
title - заголовок документа;
description - описание документа.

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

Ответ:

{
  "userId": "IIN123456789012",
  "emailNotificationsEnabled": true,
  "email": "user@example.com",
  "modifiedAt": 1585827107000
}

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

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

Запрос:

{
  "emailNotificationsEnabled": false,
  "email": "otheruser@example.com"
}

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

Ответ:

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

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

Для разработчиков

# Введение

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

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

# Методы API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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