> For the complete documentation index, see [llms.txt](https://docs.aitu.io/aituapps/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aitu.io/aituapps/aitu-passport/integraciya-s-aitu-passport/podpisanie-dokumentov-ecp.md).
# Подписание документов ЭЦП
{% hint style="info" %}
Для того, чтобы воспользоваться услугами подписания документов ЭЦП системы Aitu Passport необходимо чтобы Партнер:
* был зарегистрирован в соответствующем окружении Aitu Passport (на тестовой площадке, на продакшн площадке)
* создал свой сервис в соответствующем окружении Aitu Passport
* подключил к своему сервису сервис/сервисы (scope) подписания документов (подробнее о scope см., [тут](/aituapps/aitu-passport/integraciya-s-aitu-passport/spisok-servisov-aitu-passport-scope.md)):
* "**sign**" - подписание резидентом документов ОЭЦП физического лица (ФЛ)
* "**non\_resident\_sign**" - подписание не резидентов документов ОЭЦП ФЛ
* "**ul\_sign**" - подписание документов ОЭЦП юридического лица
{% endhint %}
{% hint style="warning" %}
Услуги по подписанию документов резидентами РК (**sign**) и нерезидентами РК (**non\_resident\_sign**) являются несовместимыми в рамках одного сервиса. В случае если в проекте Партнера предусмотрено подписание документов как резидентами, так и нерезидентами необходимо создать 2 сервиса (один для подписания документов резидентами РК, второй для подписания документов нерезидентами РК). Информацию о создании сервиса см. [тут](/aituapps/aitu-passport/integraciya-s-aitu-passport/sozdanie-servisa.md)
{% endhint %}
В Aitu Passport реализовано несколько вариантов работы с облачной ЭЦП:
1. Подписание любых файлов и получение результата в формате PKCS7.
2. Подписание PDF файлов (встраивание подписи прямо в PDF файл).
3. Подписание XML файлов, получение результата в формате XMLDSIG (встраивание подписи и сертификата пользователя прямо в XML файл).
{% hint style="warning" %}
Объем одного файла, передаваемого на подпись, не должен превышать 40 MB
{% endhint %}
## Выбор варианта подписания
{% hint style="info" %}
Отличаются только методы по загрузке документов для подписания и получения/проверки. Процесс для пользователя одинаков вне зависимости от формата.
{% endhint %}
### PKCS7
В большинстве случаев, если необходимо просто подписать документ и провалидировать подпись нужно использовать вариант с PKCS7.
Вы можете подписывать любой массив байт: любые документы, hash документов, произвольные наборы байт и т.д., в том числе pdf и xml файлы. Массив байт должен быть передан в кодировке base64.
Результирующая подпись будет в формате PKCS7. Контейнер PKCS7 содержит в себе всю цепочку сертификатов от пользовательского до КУЦ, TSP метку, OCSP метку, подпись документа.
{% hint style="info" %}
Контейнер PKCS7, полученный от Aitu Passport, не содержит исходный подписываемый документ.
{% endhint %}
### PDF
Вы сможете подписывать pdf документы и получать результат в специально предназначенном для этого формате, просматривать подпись в PDF-ридерах (подпись будет вставлена непосредственно в исходный файл).
{% hint style="info" %}
Так как в облачной ЭЦП Aitu Passport используются ГОСТ алгоритмы подписи, то стандартные PDF-ридеры не смогут корректно отобразить подпись. Для корректного отображения подписи в варианте PDF Партнеру необходимо самостоятельно написать плагин к нужному PDF-ридеру.
{% endhint %}
{% hint style="info" %}
Если у вас нет необходимости встраивать подпись непосредственно в исходный файл, то проще использовать PKCS7 формат вместо PDF, даже для PDF файлов.
{% endhint %}
### XMLDSIG
Данный вариант можно использовать только для подписания xml файлов. В случае, если необходимо подписывать xml файлы и валидировать результаты, например, в НУЦ РК - используйте XMLDSIG вариант.
Вы можете подписывать xml документы и получать результат в специально предназначенном для этого формате (результат будет в формате xmldsig). Результат подписи и сертификат пользователя вставляются непосредственно в исходный файл.
{% hint style="info" %}
Если у вас нет необходимости встраивать подпись непосредственно в исходный файл, то проще использовать PKCS7 формат вместо XMLDSIG, даже для xml файлов.
{% endhint %}
{% hint style="info" %}
Проверка документов, подписанных через XMLDSIGN, на стороне Aitu Passport не производится, и должна быть реализована Партнером самостоятельно.
{% endhint %}
## Схема процесса подписания документа ЭЦП
## Описание процесса подписания документа ЭЦП
Aitu Passport позволяет осуществлять подписание документов ЭЦП для физических лиц (ЭЦП ФЛ) и ЭЦП для юридических лиц (ЭЦП ЮЛ). Так же доступно множественное подписание документов ЭЦП различными лицами.
### Подготовительный этап для подписания документов ЭЦП ЮЛ
Прежде чем инициировать процесс подписания документов ЭЦП ЮЛ информационная система партнера должна передать в Aitu Passport следующие данные:
1. Список сотрудников юридического лица, имеющих право подписи документов от имени данного юридического лица. Данные передаются в методе [/api/v1/uls](https://docs.passport.aitu.io/#operation/saveUls)
{% hint style="warning" %}
Правом и обязанностью Партнера является своевременная передача в Aitu Passport актуального списка сотрудников, имеющих право подписи документов от имени юридического лица. В случае, если список сотрудников, имеющих право подписи, меняется (добавление/удаление сотрудника) информационная система Партнера должна передать новый список всех сотрудников, имеющих право подписи в Aitu Passport.
{% endhint %}
### Подписание документа ЭЦП (ЮЛ или ФЛ)
1. При переходе Пользователя в приложении Партнера к этапу подписания документов ЭЦП, приложение Партнера, до того как начнется процесс подписания, должно загрузить в Aitu Passport документ или документы которые должен подписать Пользователь. Предварительная загрузка применяется для того, чтобы приложение Партнера могло получить signableId. signableId - это уникальный идентификатор документа, присвоенный Aitu Passport, используется в ссылке-запросе авторизации (см. п.2 настоящего раздела) и в методах получения данных о подписании документа (-ов). В зависимости от выбранного варианта подписания (информацию о вариантах подписания см., в разделе "[Выбор варианта подписания](#vybor-varianta-podpisaniya)") используется один из следующих методов загрузки документов.
{% hint style="warning" %}
В запросе загрузки документов можно передать до 20 документов
{% endhint %}
Для ФЛ :
* Если выбран вариант PKCS7, то для загрузки документа используется метод [api/v2/oauth/signable](https://docs.passport.aitu.io/#operation/uploadSignable)
* Если выбран вариант PDF, то для загрузки документа используется метод [api/v2/oauth/signable/pdf](https://docs.passport.aitu.io/#operation/uploadSignablePdf)
* Если выбран вариант XMLDSIG, то для загрузки документа используется метод [api/v2/oauth/signable/xml](https://docs.passport.aitu.io/#operation/uploadSignableXml)
Для ЮЛ :
* Если выбран вариант PKCS7, то для загрузки документа используется метод [api/v3/oauth/signable](https://docs.passport.aitu.io/#operation/uploadSignable)
* Если выбран вариант PDF, то для загрузки документа используется метод [api/v3/oauth/signable/pdf](https://docs.passport.aitu.io/#operation/uploadSignablePdf)
* Если выбран вариант XMLDSIG, то для загрузки документа используется метод [api/v3/oauth/signable/xml](https://docs.passport.aitu.io/#operation/uploadSignableXml)
{% hint style="success" %}
В методе загрузки документа, приложение Партнера может передать ссылку на страницу с текстом документа, который должен подписать Пользователь в параметре link. Если ссылка передана (параметр link), то в процессе подписания, на платформе Aitu Passport, Пользователь сможет ознакомиться с текстом документа.
{% endhint %}
Процесс загрузки документов обозначен стрелками 3 и 4 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)
2. После того, как Пользователь в приложении Партнера нажмет на кнопку или ссылку подписи документа (стрелка 5 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)), Приложение партнера формирует ссылку-запрос авторизации (с методом генерации ссылки-запроса авторизации oauth2/auth можно ознакомиться [здесь](https://docs.passport.aitu.io/#operation/oauthAuth), процесс авторизации детально описан в статье "Авторизация" -> глава "[Авторизация в Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport)").
Важные моменты при формировании параметров для ссылки-запроса авторизации в процессе подписания документов ЭЦП:
* В случае, если по условиям договора на оказание услуг Aitu Passport, номер мобильного телефона Пользователя:
* **Партнер** верифицирует самостоятельно, то приложение Партнера должно в ссылке-запросе авторизации ([oauth2/auth](https://docs.passport.aitu.io/#operation/oauthAuth)) передать параметр `otp_confirmation`. Чтобы получить значение для параметра `otp_confirmation`**,** приложение Партнера должно вызвать метод [api/v1/trusted-phone](https://docs.passport.aitu.io/#operation/createTrustedPhone). Значение для параметра `otp_confirmation` передается в параметре `secret` ответа метода [api/v1/trusted-phone](https://docs.passport.aitu.io/#operation/createTrustedPhone). **Внимание!** `secret`, а соответственно и значение в параметре `otp_confirmation` является одноразовым, его необходимо получать для каждого запроса авторизации заново!
* верифицирует **Aitu Passport**, то параметр `otp_confirmation` в ссылке-запросе на авторизацию ([oauth2/auth](https://docs.passport.aitu.io/#operation/oauthAuth)) не передается, метод [api/v1/trusted-phone](https://docs.passport.aitu.io/#operation/createTrustedPhone) вызывать не нужно.
Процесс получения значения для параметра `otp_confirmation` обозначен стрелками 6 и 7 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)
* В параметре `scope` обязательно указывается параметр услуги подписания документа: **sign** или **non\_resident\_sign** или **ul\_sign** . Параметр услуги подписания документа должен передаваться следующим образом: `sign.1,2,3,` где 1, 2 и 3 это signableId, полученные от метода загрузки документа (описание методов загрузки см., п.1 настоящего раздела)
3\. После того, как приложением Партнера была сгенерирована ссылка-запрос на авторизацию (стрелка 8 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)), происходит редирект Пользователя на принимающую страницу Aitu Passport, где Пользователь проходит процессы авторизации, идентификации в Aitu Passport. Путь пользователя в Aitu Passport определяется параметрами, переданными в ссылке-запросе авторизации. Стрелки 9 - 16 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)
{% hint style="warning" %}
Для успешного прохождения этапа биометрической идентификации скорость подключения устройства Пользователя к сети интернет должна быть не менее 100кб/сек
{% endhint %}
4\. Aitu Passport предлагает Пользователю подписать документ, Пользователь подписывает документ ЭЦП (стрелки 17 - 22 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp))
5\. Aitu Passport генерирует код авторизации и передает его приложению Партнера. Описание данного процесса см. в статье "Авторизация" -> глава "[Авторизация в Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport). Стрелки 23 и 24 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)
6\. Приложение Партнера (серверная часть приложения) обменивает полученный код авторизации на токены (access\_token, id\_token). Описание данного процесса см. в статье "Авторизация" -> глава "[Авторизация в Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport). Стрелки 25 и 26 на [схеме](#skhema-processa-podpisaniya-dokumenta-ecp)
#### Получение документов, подписанных ЭЦП
В зависимости от того, какой вариант подписания документа был выбран, для того чтобы получить подписанный документ, приложение Партнера должно вызвать один из следующих методов:
* Если выбран PKCS7, то вызывается метод [api/v2/oauth/signatures](https://docs.passport.aitu.io/#operation/getSignatures) (в сервисе Партнера который используется для подписи документов резидентами) или метод [api/v2/oauth/non-residents/signatures](https://docs.passport.aitu.io/#operation/getSignaturesNonResident) (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:
* signableId - идентификатор документа, присвоенный системой Aitu Passport;
* signature - контейнер PKCS7 с данными подписи,
* registrationCertificate - регистрационное свидетельство в виде строки base64.
* Если выбран PDF, то вызывается метод [api/v2/oauth/signatures/pdf ](https://docs.passport.aitu.io/#operation/getSignedPdf)(в сервисе Партнера для подписи документов резидентами) или метод [api/v2/oauth/non-residents/signatures/pdf](https://docs.passport.aitu.io/#operation/getSignedPdfNonResident) (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:
* signableId - идентификатор документа, присвоенный системой Aitu Passport;
* name - имя документа, переданного сервисом Партнера в систему Aitu Passport;
* signedPdf - подписанный документ, в формате pdf. Передача документа в данном параметре говорит о том, что по данным AituPassport документ подписан. Если вы хотите валидировать подпись документа ОЭЦП, то воспользуйтесь одним из сервисов валидации подписи см. раздел [Проверка валидности подписи](#proverka-validnosti-podpisi) данной статьи;
* registrationCertificate - регистрационное свидетельство в виде строки base64. Для метода [api/v2/oauth/non-residents/signatures/pdf](https://docs.passport.aitu.io/#operation/getSignedPdfNonResident) не передается;
* documentCopy - оригинал документа, который был отправлен на подпись в формате pdf, с интегрированным QR-кодом для проверки ЭЦП (для метода [api/v2/oauth/non-residents/signatures/pdf](https://docs.passport.aitu.io/#operation/getSignedPdfNonResident) не передается). QR-код размешается в нижнем колонтитуле на каждой странице документа.
QR-код для проверки ЭЦП и данные лиц, подписавших документ
* Если выбран XMLDSIG, то вызывается метод [api/v2/oauth/signatures/xml ](https://docs.passport.aitu.io/#operation/getSignedXml)(в сервисе Партнера для подписи документов резидентами) или метод [api/v2/oauth/non-residents/signatures/xml](https://docs.passport.aitu.io/#operation/getSignedXmlNonResident) (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:
* signableId - идентификатор документа, присвоенный системой Aitu Passport;
* name - имя документа, переданного сервисом Партнера в систему Aitu Passport;
* signedXml - подписанный документ, в формате xml
### Множественное подписание документа ЭЦП
#### Множественное подписание документа ЭЦП в формате PKCS7
Процесс подписания ЭЦП документа несколькими лицами в формате PKCS7 выглядит следующим образом:
1. ИС Партнера загружает не подписанный документ используя метод [api/v2/oauth/signable](https://docs.passport.aitu.io/#operation/uploadSignable) и получает signableId (старт процесса первого подписания)
2. После получения signableId от метода [api/v2/oauth/signable](https://docs.passport.aitu.io/#operation/uploadSignable), ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе [Подписание документа ЭЦП (ЮЛ или ФЛ)](#podpisanie-dokumenta-ecp-yul-ili-fl)
3. После первого подписания документа, ИС Партнера вызывает метод [api/v2/oauth/signatures](https://docs.passport.aitu.io/#operation/getSignatures) для получения данных подписанного документа и сохраняет эти данные.
4. В случае если документ должен быть подписан вторым лицом, то ИС партнера должно загрузить уже подписанный ранее документ в Aitu Passport, чтобы получить signableId, для старта процесса подписания. Для получения signableId для второго и последующего подписания документа должен использоваться метод [/api/v2/oauth/signable-with-signature](https://docs.passport.aitu.io/#operation/uploadSignableWithSignature). В запросе данного метода передаются следующие параметры:
* bytes - оригинальный документ (документ без подписей)
* name - имя документа. Данное имя будет отображаться пользователю в процессе подписания
* link - ссылка на документ (текст документа)
* signature - документ подписанный ЭЦП первым (предыдущим) лицом
5. После получения signableId от метода [/api/v2/oauth/signable-with-signature](https://docs.passport.aitu.io/#operation/uploadSignableWithSignature), ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе [Подписание документа ЭЦП (ЮЛ или ФЛ)](#podpisanie-dokumenta-ecp-yul-ili-fl)
6. После подписания документа, ИС Партнера вызывает метод [api/v2/oauth/signatures](https://docs.passport.aitu.io/#operation/getSignatures) для получения данных подписанного документа и сохраняет эти данные.
7. В случае если необходимо подписать документ третьим и последующими лицами ИС партнера запускает процесс описанный в п.п. 4 - 6 настоящего раздела
#### Множественное подписание документа ЭЦП в формате PDF
Процесс подписания ЭЦП документа несколькими лицами в формате PDF выглядит следующим образом:
1. ИС Партнера загружает не подписанный документ используя метод [api/v2/oauth/signable/pdf](https://docs.passport.aitu.io/#operation/uploadSignablePdf) и получает signableId (старт процесса первого подписания)
2. После получения signableId от метода [api/v2/oauth/signable/pdf](https://docs.passport.aitu.io/#operation/uploadSignablePdf) , ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе [Подписание документа ЭЦП (ЮЛ или ФЛ)](#podpisanie-dokumenta-ecp-yul-ili-fl)
3. После подписания документа, ИС Партнера вызывает метод [api/v2/oauth/signatures/pdf ](https://docs.passport.aitu.io/#operation/getSignedPdf)для получения данных подписанного документа и сохраняет эти данные.
4. В случае если документ должен быть подписан вторым и последующим лицом, то ИС партнера должно загрузить уже подписанный ранее документ в Aitu Passport, чтобы получить signableId. Для получения signableId для второго и последующего подписания документа должен вызываться тот же метод - [api/v2/oauth/signatures/pdf ](https://docs.passport.aitu.io/#operation/getSignedPdf)со следующими параметрами:
* bytes - документ, подписанный ЭЦП первым (предыдущим) лицом.
* name - имя документа. Данное имя будет отображаться пользователю в процессе подписания
* link - ссылка на документ (текст документа)
5. Дальнейшие действия идентичны описанным в п.п 2-4 настоящего раздела
Нижний колонтитул документа pdf, подписанного несколькими лицами, выглядит следующим образом:
* Если документ подписан ЭЦП физического лица, то рядом с QR-кодом отображаются:
* для резидентов: ИИН и дата подписания;
* для нерезидентов: номер документа, страна выдавшая документ и дата подписания.
Документ подписан ЭЦП физического лица - резидентами
Документ подписан ЭЦП физического лица - нерезидентами
* Если документ подписан ЭЦП юридического лица, то рядом с QR-кодом отображаются:
* для резидентов: ИИН физического лица, подписавшего документ от имени организации, БИН и наименование организации, дата подписания;
* для нерезидентов: номер документа и страна выдавшая документ физическому лицу, подписавшего документ от имени организации, БИН и наименование организации, дата подписания.
Документ подписан ЭЦП юридического лица - резидентами и нерезидентами
### Сроки действия объектов
{% hint style="warning" %}
**Внимание:**
* Период хранения не подписанных документов, переданных на подписание (signableId) **24 часа** с момента генерации signableId;
* Параметр `otp_confirmation` действителен в течение **60 минут** с момента генерации;
* Код авторизации (code) действителен в течение **5 минут** с момента генерации;
* Токен авторизации (access\_token ) действителен в течение **30 дней** с момента генерации;
* Токен пользователя на устройстве действителен **1 год** с момента генерации.
{% endhint %}
## Проверка валидности подписи
Проверка валидности ЭЦП осуществляться разными методами Aitu Passport. Метод проверки валидности ЭЦП зависит от того, какой вариант подписания документа был выбран (PKCS7, PDF или XMLDSIGN)
#### Проверка валидности ЭЦП, полученной от Aitu Passport в формате PKCS7
Проверку ЭЦП, полученной от AituPassport, в формате PKCS7 можно выполнить следующими способами:
* через API Aitu Passport вызвав метод:
* [api/v2/oauth/signatures/verify](https://docs.passport.aitu.io/#operation/verifySignature) - для сервиса через который подписывают документы резиденты,
* [api/v2/oauth/non-residents/signatures/verify](https://docs.passport.aitu.io/#operation/verifySignatureNonResident) - для сервиса через который подписывают документы не резиденты,
* самостоятельно. Вы можете обратиться к представителям сервиса Aitu Passport за примерами кода на языке Java/Kotlin,
* при помощи метода сервиса проверки ЭЦП, развернутого на стороне Партнера - см. статью [Сервис проверки ЭЦП](/aituapps/aitu-passport/integraciya-s-aitu-passport/podpisanie-dokumentov-ecp/servis-proverki-ecp.md).
* через ШЭП -
#### Проверка валидности ЭЦП, полученной от Aitu Passport в формате PDF
Проверку ЭЦП, полученной от Aitu Passport, в формате PDF можно выполнить следующими способами:
* через API Aitu Passport вызвав метод:
* [api/v2/oauth/signatures/pdf/verify](https://docs.passport.aitu.io/#operation/verifySignedPdf) - для сервиса через который подписывают документы резиденты,
* [api/v2/oauth/non-residents/signatures/pdf/verify](https://docs.passport.aitu.io/#operation/verifySignedPdfNonResident) - для сервиса через который подписывают документы не резиденты,
* при помощи метода сервиса проверки ЭЦП, развернутого на стороне Партнера - см. статью [Сервис проверки ЭЦП](/aituapps/aitu-passport/integraciya-s-aitu-passport/podpisanie-dokumentov-ecp/servis-proverki-ecp.md).
* через ШЭП -
#### Проверка валидности ЭЦП, полученной от Aitu Passport в формате XMLDSIGN
* через API Aitu Passport вызвав метод [api/v2/oauth/signatures/xml/verify](https://docs.passport.aitu.io/#operation/verifySignedXml)
* через ШЭП -