Как это работает

Сервис Электронная подпись позволяет выпускать и управлять RSA-сертификатами, которые могут быть использованы для подписания документов НЭП и подписания запросов в Alfa API, а также подключать КЭП для подписания документов.

Возможности методов по работе с RSA-сертификатами

•
Выпуск RSA-сертификата для подписи запросов в Alfa API или подписания документов НЭП – в Alfa API и Альфа-Бизнес.
•
Активация способа подписи RSA-сертификатом.
•
Переключение на другой RSA-сертификат.
•
Перевыпуск RSA-сертификата.
•
Отзыв RSA-сертификата.

Возможности методов по работе с КЭП

•
Подключение КЭП для подписания документов в Alfa API и Альфа-Бизнес.
•
Регистрация МЧД в банке. Необходимо использовать, если вы хотите подписывать документы КЭП от лица, обладающего правом подписи по доверенности.

Методы сервиса также позволяют изменить текущий способ подписи документов в Alfa API – на КЭП или RSA-сертификат.

Сценарии работы с методами описаны в подразделах этой статьи.

Инструкция по тестированию в песочнице в статье Тестирование электронной подписи.

Выпуск RSA-сертификата

Выпущенный сертификат вы сможете использовать для подписи запросов в Alfa API и подписания документов НЭП – в Alfa API и Альфа-Бизнес.

Ограничения числа сертификатов

У одного пользователя одновременно может быть не более двух RSA-сертификатов для подписи независимо от того, используются они в Alfa API или в Альфа-Бизнес. Если у вас два сертификата, то для выпуска нового необходимо либо использовать метод для перевыпуска сертификата, либо сначала отозвать один из текущих сертификатов, а затем выпустить новый.

Получение DN

Получить DN пользователя можно двумя способами:

•
Вызвать метод API "Получение DN файлом", и тогда вы получите сразу готовый сгенерированный файл .cnf.
•
Вызвать метод API "Получение DN":
- •
  далее полученный ответ необходимо разэкранировать;
- •
  скачать файл example.cnf;
- •
  открыть файл example.cnf с помощью текстового редактора и поменять параметры DN на свои данные. Важно, что если в ответе от API "Получение DN" вы получили параметр S , то его необходимо подставить в поле MyOID_S . Если параметра S в ответе нет, то строка oid_section = OIDs , блок [OIDs] MyOID_S=2.5.4.8 и параметр MyOID_S не нужны.

Запрос на сертификат

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

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

Для получения сертификата необходимо создать запрос на сертификат:

1.
Создать закрытый ключ, введя в терминале команду: openssl genrsa -des3 -out private.key -passout pass:password 2048 . Вместо password необходимо ввести пароль от Вашего компьютера.
2.
Сформировать запрос на сертификат с помощью команды в терминале: openssl req -new -utf8 -nameopt multiline,utf8 -config example.cnf -key private.key -out example.csr
3.
После этого будет создан запрос на сертификат example.csr, который можно отрыть в текстовом редакторе.
4.
Далее заменить переносы строк на \n для получения следующей строки: -----BEGIN CERTIFICATE REQUEST-----\nMIIC/DCCAeQCAQAwgacxJTAjBgkqhkiG9w0BCQEWFlVzZXI1MDRAcG9jaHRvY2hr\nYS5jb20xOzA5BgNVBAMMMtCa0YPQtNGA0Y/QstGG0LXQsiDQldGA0LzQvtC70LDQ\nuSDQmNCz0L7RgNC10LLQuNGHMQswCQYDVQQGEwJSVTEbMBkGA1UEBAwS0JrRg9C0\n0YDRj9Cy0YbQtdCyMRcwFQYDVQQqDA7QldGA0LzQvtC70LDQuTCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBANGTN2bX/kaOHuuEfMiOKg1f8y3SY1AseVjQ\nceoHKdaSeLoUIscPgEsuDsbtF6ezsZqV7bwyRYuJK+kMprczDWKiQNxmZPOafiKG\n5MKOcxysgX9LV+R8JhVoycfQqmSqfImQBcPZ6s9bqq6J8cs04FCzy+nhPYoFUs2l\nX+ZrFfLF135fO4LlRxfj4dfIbHZ4NVogiezIteBE3SPTtEeXiYj2c7SyB0Z17gbQ\ndTmtWIolrb5GTZ6SyjjcMZY3U2ZR+4eyn2l1MFt5F/K9Ke47zu4DYTF7zkitST11\nnr5gR64zjVZRtmrVqMU9iB7NmQ8/gS8YEsC3PTSECvqioSDHwNcCAwEAAaAPMA0G\nCSqGSIb3DQEJDjEAMA0GCSqGSIb3DQEBCwUAA4IBAQBazGrfYMfeUdJ7ofbQ5lom\nEsHO/cA312QUpyzFEsHbjYhy9OZTjiVXLfVExf8QrcRchi4/6IECp01S2Ed+nfMm\nE/MtD3rtE2oBtH6FjA9APtZb9NZuiSYCzl7nL3rd0ui+F32Dy/JNkudktn64jsMH\nYVt5u8Ik0dtxl0axa3E5RUkpJTTl7iIOWD+P8UkOOpa9EMPA2hrtrZvPr8xr60IS\nd2t4vKFcHIdgdI2Qe5ATvaYfbccLGjxdWm05lXVuxRjpEOXjuhc5mRkEj06bPavD\n9k7h/Tsz4Jb9gNKDZ3TEzfynQkDFFse8in6IDDkwPO21J6onTMd7KOP1gqMSYjrh\n-----END CERTIFICATE REQUEST-----
5.
Полученную выше строку передать в pkcs10Content при вызове метода "Заявка на выпуск RSA-сертификата".

1.
Откройте файл .cnf с DN пользователя и удалите строки:
1oid_section = OIDs 2[OIDs] 3MyOID_S=2.5.4.8
2.
Замените MyOID_S на S или ST.
3.
Попробуйте выполнить команду ещё раз.

Создание заявки на выпуск RSA-сертификата

Метод "Заявка на выпуск RSA-сертификата".

Внимание! Полученную заявку необходимо подписать в течение 30 минут. Если прошло больше 30 минут, то она становится недействительной и необходимо создать новую заявку.

Отправка заявки на подпись

Метод "Отправка заявки на подпись". Входным параметром передаётся идентификатор заявки, полученный в ответе на шаге 3, а в теле запроса requestType = issueRsaCertificate . В рамках данного метода система отправляет OTP-код на телефон пользователя:

•
При использованииaccess_token в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который вошёл в Alfa ID на шаге получения кода авторизации.
•
При использовании API Key в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который выпустил ключ доступа на Портале разработчика.

Подписание заявки с помощью кода из СМС

Метод "Подписание заявки с помощью кода из СМС". На вход передаются идентификатор операции, полученный в ответе на шаге 4, и полученный по СМС OTP-код.

Получение данных заявки

Для этого нужно вызвать метод "Получение данных заявки", передав в него идентификатор заявки, полученный в ответе на шаге 3, и проверять статус заявки, пока он не перейдёт в статус FINISHED.

Получение сертификата

Метод "Получение RSA-сертификата".

Активация способа подписи RSA-сертификатом

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

Активация способа подписи RSA-сертификатом

Метод "Заявка на активацию способа подписи RSA-сертификатом". Необходимо передать в него идентификатор сертификата, полученный на шаге 7 Выпуска RSA-сертификата.

Отправка заявки на подпись

Метод "Отправка заявки на подпись". Входным параметром передаётся идентификатор заявки, полученный в ответе на шаге 1, а в теле запроса requestType = activationRsaCertificate . В рамках данного метода система отправляет OTP-код на телефон пользователя:

•
При использованииaccess_token в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который вошёл в Alfa ID на шаге получения кода авторизации.
•
При использовании API Key в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который выпустил ключ доступа на Портале разработчика.

Подписание заявки с помощью кода из СМС

Метод "Подписание заявки с помощью кода из СМС". На вход передаются идентификатор операции, полученный в ответе на шаге 2, и полученный по СМС OTP-код.

Получение данных заявки

Изменение текущего способа подписи

В результате выполнения описанных ниже шагов будет изменён способ подписания документов в Alfa API.

Создание заявки на изменение текущего способа подписи

Метод "Заявка на изменение текущего способа подписи". Необходимо передать currentSignType = rsa-certificates или currentSignType = qes в зависимости от того, какой способ подписи вам нужен.

Отправка заявки на подпись

Метод "Отправка заявки на подпись". Входным параметром передаётся идентификатор заявки, полученный в ответе на шаге 1, а в теле запроса requestType = currentSignTypeRsa или requestType = currentSignTypeQes . В рамках данного метода система отправляет OTP-код на телефон пользователя:

•
При использованииaccess_token в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который вошёл в Alfa ID на шаге получения кода авторизации.
•
При использовании API Key в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который выпустил ключ доступа на Портале разработчика.

Подписание заявки с помощью кода из СМС

Получение данных заявки

Для этого нужно вызвать метод "Получение данных заявки", передав в него идентификатор заявки, полученный в ответе на шаге 1, и проверять статус заявки, пока он не перейдёт в статус FINISHED. После получения успешного ответа можно подписывать документы выпущенным RSA-сертификатом или сертификатом квалифицированной электронной подписи.

Переключение на другой RSA-сертификат

В результате выполнения описанных ниже шагов в Alfa API и в Альфа-Бизнес для подписания документов будет использоваться другой RSA-сертификат.

Переключение на другой RSA-сертификат

Метод "Заявка на переключение на другой RSA-сертификат". Входным параметром передаётся идентификатор сертификата, на который нужно переключить основной способ подписания.

Отправка заявки на подпись

Метод "Отправка заявки на подпись". Входным параметром передаётся идентификатор заявки, полученный в ответе на шаге 1, а в теле запроса requestType = switchRsaCertificate . В рамках данного метода система отправляет OTP-код на телефон пользователя:

•
При использованииaccess_token в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который вошёл в Alfa ID на шаге получения кода авторизации.
•
При использовании API Key в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который выпустил ключ доступа на Портале разработчика.

Подписание заявки с помощью кода из СМС

Получение данных заявки

Перевыпуск RSA-сертификата

В результате выполнения описанных ниже шагов вместо старого сертификата будет выпущен новый сертификат и в Alfa API, и в Альфа-Бизнес. Это может быть полезно, если срок действия текущего сертификата подходит к концу или вам нужно выпустить новый сертификат, но вы достигли лимита общего числа RSA-сертификатов.

Получение DN

Получить DN пользователя можно двумя способами:

1.
Вызвать метод API "Получение DN файлом", и тогда вы получите сразу готовый сгенерированный файл .cnf.
2.
Вызвать метод API "Получение DN":
- •
  далее полученный ответ необходимо разэкранировать;
- •
  скачать файл example.cnf;
- •
  открыть файл example.cnf с помощью текстового редактора и поменять параметры DN на свои данные. Важно, что если в ответе от API "Получение DN" вы получили параметр S , то его необходимо подставить в поле MyOID_S . Если параметра S в ответе нет, то строка oid_section = OIDs , блок [OIDs] MyOID_S=2.5.4.8 и параметр MyOID_S не нужны.

Запрос на новый сертификат

Для получения сертификата необходимо создать запрос на сертификат:

1.
Создать закрытый ключ, введя в терминале команду: openssl genrsa -des3 -out private.key -passout pass:password 2048 . Вместо password необходимо ввести пароль от Вашего компьютера.
2.
Сформировать запрос на сертификат с помощью команды в терминале: openssl req -new -utf8 -nameopt multiline,utf8 -config example.cnf -key private.key -out example.csr
3.
После этого будет создан запрос на сертификат example.csr, который можно отрыть в текстовом редакторе.
4.
Далее заменить переносы строк на \n для получения следующей строки: -----BEGIN CERTIFICATE REQUEST-----\nMIIC/DCCAeQCAQAwgacxJTAjBgkqhkiG9w0BCQEWFlVzZXI1MDRAcG9jaHRvY2hr\nYS5jb20xOzA5BgNVBAMMMtCa0YPQtNGA0Y/QstGG0LXQsiDQldGA0LzQvtC70LDQ\nuSDQmNCz0L7RgNC10LLQuNGHMQswCQYDVQQGEwJSVTEbMBkGA1UEBAwS0JrRg9C0\n0YDRj9Cy0YbQtdCyMRcwFQYDVQQqDA7QldGA0LzQvtC70LDQuTCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBANGTN2bX/kaOHuuEfMiOKg1f8y3SY1AseVjQ\nceoHKdaSeLoUIscPgEsuDsbtF6ezsZqV7bwyRYuJK+kMprczDWKiQNxmZPOafiKG\n5MKOcxysgX9LV+R8JhVoycfQqmSqfImQBcPZ6s9bqq6J8cs04FCzy+nhPYoFUs2l\nX+ZrFfLF135fO4LlRxfj4dfIbHZ4NVogiezIteBE3SPTtEeXiYj2c7SyB0Z17gbQ\ndTmtWIolrb5GTZ6SyjjcMZY3U2ZR+4eyn2l1MFt5F/K9Ke47zu4DYTF7zkitST11\nnr5gR64zjVZRtmrVqMU9iB7NmQ8/gS8YEsC3PTSECvqioSDHwNcCAwEAAaAPMA0G\nCSqGSIb3DQEJDjEAMA0GCSqGSIb3DQEBCwUAA4IBAQBazGrfYMfeUdJ7ofbQ5lom\nEsHO/cA312QUpyzFEsHbjYhy9OZTjiVXLfVExf8QrcRchi4/6IECp01S2Ed+nfMm\nE/MtD3rtE2oBtH6FjA9APtZb9NZuiSYCzl7nL3rd0ui+F32Dy/JNkudktn64jsMH\nYVt5u8Ik0dtxl0axa3E5RUkpJTTl7iIOWD+P8UkOOpa9EMPA2hrtrZvPr8xr60IS\nd2t4vKFcHIdgdI2Qe5ATvaYfbccLGjxdWm05lXVuxRjpEOXjuhc5mRkEj06bPavD\n9k7h/Tsz4Jb9gNKDZ3TEzfynQkDFFse8in6IDDkwPO21J6onTMd7KOP1gqMSYjrh\n-----END CERTIFICATE REQUEST-----
5.
Полученную выше строку передать в pkcs10Content при вызове метода "Заявка на перевыпуск RSA-сертификата".

1.
Откройте файл .cnf с DN пользователя и удалите строки:
1oid_section = OIDs 2[OIDs] 3MyOID_S=2.5.4.8
2.
Замените MyOID_S на S или ST.
3.
Попробуйте выполнить команду ещё раз.

Перевыпуск RSA-сертификата

Метод "Заявка на перевыпуск RSA-сертификата".

Отправка заявки на подпись

Метод "Отправка заявки на подпись". Входным параметром передаётся идентификатор заявки, полученный в ответе на шаге 3, а в теле запроса requestType = reissueRsaCertificate . В рамках данного метода система отправляет OTP-код на телефон пользователя:

•
При использованииaccess_token в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который вошёл в Alfa ID на шаге получения кода авторизации.
•
При использовании API Key в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который выпустил ключ доступа на Портале разработчика.

Подписание заявки с помощью кода из СМС

Получение данных заявки

Получение сертификата

Метод "Получение RSA-сертификата". После успешного ответа на шаге 7 перевыпущенным RSA-сертификатом можно подписывать документы.

Отзыв RSA-сертификата

В результате выполнения описанных ниже шагов сертификат будет отозван и в Alfa API, и в Альфа-Бизнес. Это может быть полезно, если текущий сертификат был скомпрометирован, если вы больше не хотите его использовать или если хотите выпустить новый сертификат, но достигли лимита общего числа RSA-сертификатов.

Отзыв RSA-сертификата

Метод "Заявка на отзыв RSA-сертификата". Входным параметром передаётся идентификатор сертификата, который необходимо отозвать.

Отправка заявки на подпись

Метод "Отправка заявки на подпись". Входным параметром передаётся идентификатор заявки, полученный в ответе на шаге 1, а в теле запроса requestType = revocationRsaCertificate . В рамках данного метода система отправляет OTP-код на телефон пользователя:

•
При использованииaccess_token в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который вошёл в Alfa ID на шаге получения кода авторизации.
•
При использовании API Key в качестве заголовка авторизации OTP-код придёт на телефон пользователя, который выпустил ключ доступа на Портале разработчика.

Подписание заявки с помощью кода из СМС

Получение данных заявки

Подключение КЭП

В результате выполнения описанных ниже шагов вы подключите способ подписания документов КЭП – в Alfa API и Альфа-Бизнес.

Для подключения КЭП вам необходим сертификат КЭП, выпущенный в ФНС:

•
Если сертификат принадлежит лицу, обладающему правом подписи по уставу компании, то он самодостаточен и МЧД не требуется.
•
Если сертификат выпущен на уполномоченное лицо, обладающее правом подписи по доверенности, то, помимо сертификата, потребуется выпустить машиночитаемую доверенность (МЧД) в ФНС и зарегистрировать ее в банке по инструкции «Регистрация МЧД в банке» этой статьи.

Создание заявки на подключение КЭП

Метод "Заявка на подключение КЭП". В ответе возвращаются идентификатор заявки и статус CREATED.

Отправка на подпись заявки на подключение КЭП

Метод "Отправка на подпись заявки на подключение КЭП". В теле нужно указать requestType (по умолчанию — enableQesSignType). В ответе возвращается поле content — документ заявки (Base64) для подписи.

Подписание заявки на подключение КЭП

Метод "Подписание заявки на подключение КЭП". Заявка подписывается КЭП. В ответе возвращается isSigned = true, если всех подписей достаточно.

Перед началом подписания документов в Alfa API КЭП после успешного подписания заявки на подключение КЭП необходимо изменить текущий способ подписи на КЭП по инструкции «Изменение текущего способа подписи», описанной в этой статье.

Регистрация МЧД в банке

Регистрация МЧД в банке необходима, если вы хотите подписывать документы КЭП по доверенности. Это относится к ситуациям, когда сертификат КЭП выпущен на уполномоченное лицо, обладающее правом подписи по доверенности.

Для регистрации МЧД в банке у вас должна быть выпущена МЧД. Выпустить её можно в ФНС.

Создание запроса на регистрацию МЧД в Банке

Метод "Запрос на регистрацию МЧД в банке". В запросе необходимо передать данные для загрузки машиночитаемой доверенности с сайта ФНС. В ответе возвращается идентификатор запроса.

Получение статуса запроса на регистрацию МЧД в банке

Метод "Получение статуса запроса на регистрацию МЧД". В запросе необходимо передать идентификатор запроса на регистрацию МЧД, полученный на шаге 1. Метод необходимо вызывать до тех пор, пока статус запроса на регистрацию МЧД не перейдёт в COMPLETE.

Скачивание файла МЧД

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