API: работа с документами

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

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

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

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

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

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

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;
либо установить для publicWhileLessThanSignatures значение больше нуля, это работает и в случае регистрации и в случае пердрегистрации.

Важно: Нужно иметь в виду что отправка документа в системы СпецЦОН осуществляется асинхронно и поэтому для тех документов, для которых она запрошена, необходимо чтобы подлинник документа был сохранен на сервисе SIGEX:

либо в архиве;
либо во временном хранилище.

Попробовать этот 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,
    "language": "ru"
  },
  "settings": {
    "private": false,
    "signaturesLimit": 2,
    "switchToPrivateAfterLimitReached": true,
    "unique": ["iin"],
    "strictSignersRequirements": false,
    "signersRequirements": [
      {
        "iin": "IIN112233445566"
      }
    ],
    "publicDuringPreregistration": false,
    "publicWhileLessThanSignatures": 0,
    "documentAccess": [],
    "forceArchive": false,
    "tempStorageAfterRegistration": 86400000
  },
  "integrationRegisterAuto": {
    "documentTypeCode": "SalesContract",
    "signers": [
      "SELLER",
      "BUYER"
    ]
  }
}

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

Ответ:

{
  "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,
  "tempStorage": true
}

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

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

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

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

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

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

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

Ответ:

{
  "title": "document title",
  "description": "document description",
  "signedDataSize": 0,
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocument": false,
    "language": "ru"
  },
  "signatureEmailNotifications": [
    {
      "signId": 1,
      "doNotAttachDocument": false,
      "to": ["user@example.com","otherUser@example.com"],
      "language": "ru"
    },
    {
      "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,
    "publicWhileLessThanSignatures": 0,
    "documentAccess": [],
    "forceArchive": false,
    "tempStorageAfterRegistration": 86400000
  },
  "signaturesTotal": 2,
  "signatures": [
  ],
  "dataArchived": false,
  "tempStorage": true,
  "canBeArchived": true,
  "registrator": {
    "businessId":"BIN012345678901",
    "certificate":"base64_encoded_mtls_certificate"
  }
}

title - заголовок документа;
description - описание документа;
signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0);
emailNotifications - информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации документа;
signatureEmailNotifications - массив объектов, информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации подписей;
settings - объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа;
signaturesTotal - общее количество подписей документа;
signatures - массив объектов с данными о подписях документа;
dataArchived - информирует о том, находятся ли подписанные данные в архиве;
tempStorage - информирует о том, находятся ли подписанные данные во временном хранилище;
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;
XML - можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics с некоторыми оговорками (см. ниже).

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

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

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

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

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

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

Ответ:

{
  "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.

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

Ответ:

{
  "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,
    "language": "ru"
  }
}

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

Ответ:

{
  "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&withLabelVerified=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;
withLabelVerified=false - печатать альтернативную подпись "проверено на sigex.kz"/"тексерілді sigex.kz" под QR кодом с логотипом;
language=ru - опционально, язык формирования, поддерживаются "ru", "kk" и "kk/ru", по умолчанию "ru".

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

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

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

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

Ответ:

{
  "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.

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

Ответ:

{
  "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,
  "publicWhileLessThanSignatures": 0,
  "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 - опциональное поле, флаг активации специального режима контроля доступа к документу и подписываемым данным (в этом режиме до регистрации первой подписи под документом информация о документе и подписываемые данные доступны всем без ограничений), флаг возможно устанавливать только при предрегистрации документа, менять его значение нельзя;
publicWhileLessThanSignatures - опциональное поле, позволяет активировать специальный режим контроля доступа к документу и подписываемым данным (в этом режиме до того момента, как будет набрано указанное количество подписей, информация о документе и подписываемые данные доступны всем без ограничений), возможно устанавливать только при регистрации или предрегистрации документа, менять его значение нельзя;
documentAccess - опциональное поле, позволяет задавать дополнительные правила предоставления доступа к информации о документе и данным в архиве, то есть дополняет существующие правила контроля доступа основанные на наличии подписей под документом и регистраторе документа, а не заменяет и не ужесточает их, подробности про контроль доступа тут;
forceArchive - опциональное поле, позволяет принудительно заархивировать документ даже в том случае, если архивирование не активировано в настройках подписантов, его возможно задавать только в момент первоначальной регистрации документа, по умолчанию false;
tempStorageAfterRegistration - опциональное поле, позволяет запросить размещение документа во временном хранилище на указанное в миллисекундах время (то есть документ будет доступен во временном хранилище в течении указанного промежутка времени с момента его регистрации), его возможно задавать только в момент первоначальной регистрации документа, по умолчанию 0.

Требования 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 уже зарегистрированного документа, а так же выполнить регистрацию полученной подписи под данным документом. То есть заменяет следующие четыре вызова:

Важно: Поддерживается только для документов находящихся в архиве или во временном хранилище, тело подписываемого документа будет отправлено в 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,
    "language": "ru"
  }
}

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

Ответ:

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

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,
    "language": "ru"
  },
  "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;
- language - опциональное поле, позволяет задать язык уведомления, поддерживаются строки "ru", "kk", "en" и их комбинации через "/", к примеру "kk/en";
errors - опциональный объект, содержащий информацию об ошибках, возникших при выполнении процедуры:
- egov - информация об ошибке полученной в процессе взаимодействия с eGov mobile/business;
- sigex - информация об ошибке полученной при обработке подписи.

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

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

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

Ответ:

{
  "operationId": "12345"
}

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

`POST` `/api/{id}/integrationRegisterAuto` - отправка документа в системы СпецЦОН для регистрации автотранспорта

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

Позволяет задать параметры отправки документа в системы СпецЦОН для регистрации автотранспорта для уже зарегистрированного документа. После успешной установки параметров сервис приступит к отправке документа, отслеживать статус отправки можно с помощью GET /api/{id}/integrationRegisterAuto - получение статуса отправки документа в системы СпецЦОН для регистрации автотранспорта.

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

Важно: Так как отправка документа в системы СпецЦОН будет осуществляться асинхронно, то необходимо чтобы подлинник документа был сохранен на сервисе SIGEX:

либо в архиве;
либо во временном хранилище.

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

{
  "documentTypeCode": "SalesContract",
  "signers": [
    "SELLER",
    "BUYER"
  ]
}

documentTypeCode - строка, тип документа, поддерживаемые значения перечислены на странице Известные строки;
signers - массив задающий последовательность типов подписантов, то есть то, как нужно интерпретировать зарегистрированные подписи, поддерживаемые значения перечислены на странице Известные строки.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "storedAt": 1764508775027,
  "source": "register",
  "deliveryStartedAt": 1764509253788,
  "attempts": 1,
  "lastRetriedAt": 1764509265593,
  "status": "accepted",
  "settings": {
    "documentTypeCode": "SalesContract",
    "signers": [
      "SELLER",
      "BUYER"
    ]
  },
  "errors": {
    "integration": "BAD_REQUEST",
    "sigex": "Failed to deliver document to auto PSC server"
  }
}

documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
storedAt - время сохранения параметров отправки в системе (миллисекунд с UNIX Epoch);
source - источник настроек, поддерживаемые значения перечислены на странице Известные строки;
deliveryStartedAt - опциональное поле, время инициализации процесса отправки документа (миллисекунд с UNIX Epoch);
attempts - количество выполненных попыток отправки;
lastRetriedAt - опциональное поле, время последней попытки отправки (миллисекунд с UNIX Epoch);
status - статус отправки, поддерживаемые значения перечислены на странице Известные строки;
settings - заданные параметры отправки документа;
errors - опциональное поле, присутствует в случае возникновения ошибок отправки документа в сервисы СпецЦОН:
- integration - опциональное поле, ошибка полученная со стороны систем СпецЦОН, поддерживаемые значения перечислены на странице Известные строки;
- sigex - опциональное поле, ошибка SIGEX, поддерживаемые значения перечислены на странице Перечень возможных сообщений об ошибках.

`GET` `/api/{id}/integrationRegisterAuto` - получение статуса отправки документа в системы СпецЦОН для регистрации автотранспорта

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

Позволяет отслеживать статус отправки документа в системы СпецЦОН для регистрации автотранспорта.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "storedAt": 1764508775027,
  "source": "register",
  "deliveryStartedAt": 1764509253788,
  "attempts": 1,
  "lastRetriedAt": 1764509265593,
  "status": "accepted",
  "settings": {
    "documentTypeCode": "SalesContract",
    "signers": [
      "SELLER",
      "BUYER"
    ]
  },
  "errors": {
    "integration": "BAD_REQUEST",
    "sigex": "Failed to deliver document to auto PSC server"
  }
}

documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
storedAt - время сохранения параметров отправки в системе (миллисекунд с UNIX Epoch);
source - источник настроек, поддерживаемые значения перечислены на странице Известные строки;
deliveryStartedAt - опциональное поле, время инициализации процесса отправки документа (миллисекунд с UNIX Epoch);
attempts - количество выполненных попыток отправки;
lastRetriedAt - опциональное поле, время последней попытки отправки (миллисекунд с UNIX Epoch);
status - статус отправки, поддерживаемые значения перечислены на странице Известные строки;
settings - заданные параметры отправки документа;
errors - опциональное поле, присутствует в случае возникновения ошибок отправки документа в сервисы СпецЦОН:
- integration - опциональное поле, ошибка полученная со стороны систем СпецЦОН, поддерживаемые значения перечислены на странице Известные строки;
- sigex - опциональное поле, ошибка SIGEX, поддерживаемые значения перечислены на странице Перечень возможных сообщений об ошибках.

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

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

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

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

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

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

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

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

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

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

Ответ:

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

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

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

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "storedAt": 11111111111,
  "title": "document title",
  "description": "document description",
  "dataArchived": false,
  "signedDataSize": 123,
  "registrator": {
    "businessId":"BIN012345678901",
    "certificate":"base64_encoded_mtls_certificate"
  },
  "signaturesTotal": 2,
  "signatures": [
  ]
}

documentId - идентификатор документа;
storedAt - момент регистрации документа в системе (миллисекунд с UNIX Epoch);
title - заголовок документа;
description - описание документа;
dataArchived - информирует о том, находятся ли подписанные данные в архиве;
signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0);
registrator - опциональное поле, информация об информационной системе, зарегистрировавшей документ (БИН и mTLS сертификат в base64), присутствует только в том случае, если регистрация (либо предрегистрация) документа была выполнена аутентифицированной информационной системой;
signaturesTotal - общее количество подписей зарегистрированных под документом;
signatures - опциональное поле, массив объектов с данными о подписях документа (описание приведено в GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе), присутствует только в том случае, если includeSignatures=true.

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

Мы проводим вебинары про электронные документы, ЭЦП и юридическую значимость.

Хочу прослушать бесплатный вебинар!

API: работа с документами

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

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}/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/{id}/integrationRegisterAuto - отправка документа в системы СпецЦОН для регистрации автотранспорта

GET /api/{id}/integrationRegisterAuto - получение статуса отправки документа в системы СпецЦОН для регистрации автотранспорта

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

`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}/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/{id}/integrationRegisterAuto` - отправка документа в системы СпецЦОН для регистрации автотранспорта

`GET` `/api/{id}/integrationRegisterAuto` - получение статуса отправки документа в системы СпецЦОН для регистрации автотранспорта

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