Работа с ЭП в Sber API

Обновлено 10 сентября 2025

Общие сведения

Электронная подпись (далее - ЭП) — это цифровой аналог рукописной подписи на бумаге. ЭП состоит из сертификата (открытый ключ) и криптографической части (закрытый ключ, доступный только владельцу). Сертификат ЭП содержит всю необходимую информацию: данные о владельце, срок действия подписи и т. д. Криптографическая часть включает только механизмы шифрования.

Подписание документов с помощью ЭП

Для формирования электронной подписи документа применяются сертифицированные средства криптозащиты информации.

Документ может быть подписан двумя способами:

• после подписания создается один файл, содержащий исходные данные документа и данные подписи (прикрепленная подпись);
• после подписания создаются два файла: файл с документом и файл с подписью (открепленная подпись).

Банк поддерживает работу с открепленными подписями.

Терминология

• КУЦ - код удостоверяющего центра. Является уникальным идентификатором организации в УЦ СберБанка.
• Электронный ключ (токен) - программно-аппаратное устройство на базе «VPN-key-TLS» или «Рутокен TLS», используемое в СберБизнес для генерации ключей ЭП, ключей шифрования, формирования и проверки УНЭП/УКЭП, шифрования и подключения к защищенной корпоративной VPN–сети Банка. Электронный ключ реализует алгоритмы шифрования и электронной подписи, соответствующие российскому ГОСТ.
• Bicrypt ID - идентификатор сертификата, который состоит из (КУЦ) + (номер сертификата) + (тип сертификата: s-сертификат пользователя; t-сертификат TLS) + (ФИО пользователя клиента).
• ЭП - электронная цифровая подпись , которая формируется закрытым ключом.
• Сертификат ЭП - сертификат электронной подписи , используется для идентификации ЭП в полученном документе.

Использование ЭП в API

Sber API поддерживает только УНЭП, выпущенные УЦ Сбербанка. Сертификаты выпущенные другими УЦ не принимаются.

В API можно использовать два вида документов: те, которые подписаны ЭП, и те, которые не подписаны.

• Если документ подписан ЭП, то он сразу же отправляется на обработку, при условии, что под документом есть достаточное количество ЭП.
• Документ без ЭП создается в СберБизнес как черновик. Если клиент не подпишет этот черновик в СберБизнес, то документ не отправится на обработку. Использование ЭП в API помогает автоматизировать процесс подписания отправляемых документов.

Схема работы

№	Что делаем	Подробности
1	Создайте для подписанта профиль в СберБизнес	Чтобы автоматизировать процесс подписания документов, вам нужно создать профиль в СберБизнес для сотрудника (подписанта), чья подпись будет использоваться. Если у подписанта уже есть профиль в СберБизнес, создайте дублирующий профиль СберБизнес. Дублирующий профиль будет использоваться только при работе с банком через Sber API. Если компания использует систему двойного подписания документов (Первая и Вторая подписи), создайте дублирующий профиль СберБизнес для каждого подписанта.
2	Выпустите на подписанта сертификат ЭП	Выпуск сертификата ЭП происходит в УЦ СберБанка. Процесс выпуска сертификата необходимо реализовать с помощью ресурсов Sber API в рамках вашей Платформы. Подробнее о процессе оформления сертификата ЭП расскажем в соответствующем разделе.
3	Подпишите документ и отправьте в Банк	Для создания ЭП к документу потребуется инструмент для подписания - средство криптографической защиты информации (СКЗИ). СКЗИ вы выбираете самостоятельно исходя из ваших задач и потребностей. Ниже по странице в соответствующем разделе мы расскажем о следующих способах подписания: 1. Токен (Инфокрипт, Рутокен) с использованием программных средств (API токена); 2. Токен + СКЗИ Крипто Про Созданную открепленную подпись (detached) необходимо закодировать с помощью Base64 и полученный результат отправить в теле запроса.

Создайте для подписанта профиль в СберБизнес

У подписанта может быть только один активный сертификат ЭП. При наличии двух профилей в СберБизнес (основной и дублирующий) с типом защиты «электронный ключ» (токен), для каждого профиля активным будет только один сертификат ЭП.

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

• GET /v1/crypto/cert-requests/{externalId}/state
• GET /v1/crypto/cert-requests/eio/{externalId}/state (для ЕИО)

Статус PROCESSED означает, что сертификат активирован и готов к использованию.

При условии, что у сотрудника один профиль в СберБизнес с типом защиты «электронный ключ» (токен) и его токен будет установлен в сервер (или другое устройство, которое хранит данные Платформы), он лишится возможности входа в СберБизнес.

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

Если у сотрудника уже есть профиль в СберБизнес, создайте дублирующий профиль. Он будет использоваться только при работе с банком через Sber API.

Если компания использует систему двойного подписания документов (Первая и Вторая подписи), создайте дублирующий профиль СберБизнес для каждого подписанта.

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

Дублирующий профиль нужен для сохранения возможности входа в СберБизнес для сотрудника и одновременного использования его подписи в Sber API.

Если возможность входа в СберБизнес не нужна, дублирующий профиль можно не создавать.

Профиль подписанта должен иметь следующие характеристики:

• Право на подписание
• Вариант защиты Системы и подписания — «электронный ключ» (токен)

Вариант защиты Системы и подписания определяет метод подписания документов. При выборе «одноразовые SMS-пароли» используются одноразовые коды из сообщений для подписания документов, что соответствует подписи ПЭП. Для обеспечения безопасности обмена подписанными документами с банком через API требуется использование НЭП, поэтому нужен профиль СберБизнес с типом защиты «электронный ключ» (токен).

Обратите внимание, что даже при типе защиты «электронный ключ» (токен) сертификат ЭП может храниться на носителе, отличном от токена (например, на внутреннем хранилище вашего сервера). Приобретение токена является необязательным, но рекомендуется.

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

Выбор СКЗИ

Выбор СКЗИ может влиять на способ хранения сертификата и закрытого ключа ЭП. Например, если выбрано СКЗИ, которое поддерживает работу с HSM, то сертификат и ключ могут храниться на этом устройстве для обеспечения дополнительного уровня безопасности. Кроме того, выбор СКЗИ может определить возможности по интеграции с другими системами и платформами для хранения ключей ЭП.

Сертификат и закрытый ключ ЭП могут храниться не только на токене, но и на специальных устройствах для хранения ключей (HSM), в защищенном хранилище на сервере или других средствах, предоставляемых СКЗИ.

Выбор СКЗИ - рекомендации

№	Название	Описание	Стоимость	Где взять
1	КриптоПро CSP	Разработанная одноименной компанией линейка криптографических утилит. Они используются в других программах для генерации электронной подписи (ЭП), работы с сертификатами, организации структуры PKI и т.д. Плюсы: - подходит для всех, кто использует усиленную квалифицированную электронную подпись; - облегчает работу с государственными порталами и информационными системами; - поддерживает электронный документооборот с контрагентами; - помогает участвовать в электронных торгах, например, на Госуслугах; - упрощает удаленное трудоустройство и подписание машиночитаемых доверенностей.	CSP CryptoPro — платный продукт. Лицензию можно заказать на сайте разработчика или приобрести у официальных дилеров.	На сайте вендора
2	СКЗИ от Рутокен	Встроено в носитель Рутокен ЭЦП 3.0. Носитель выпускается компанией АО «Активсофт» и предназначен для хранения сертификатов ЭП, генерации ЭП, шифрования документов и защиты информации от доступа посторонних лиц. Плюсы: - дополнительный уровень безопасности благодаря двухфакторной аутентификации с использованием PIN-кода; - встроенная лицензия на криптопровайдер, что позволяет избежать установки СКЗИ на компьютер; - поддержка российских и международных стандартов информационной безопасности; - совместимость с операционными системами Windows, Linux и Mac.	С тарифами вы можете ознакомиться на сайте банка .	Как получить электронный ключ (токен)
3	СКЗИ от Инфокрипт	Встроено в носитель Инфокрипт-токен. Носитель выпускается компанией ООО Фирма «ИнфоКрипт» и предназначен для хранения сертификатов ЭП, генерации ЭП, шифрования документов и защиты информации от доступа посторонних лиц. Плюсы: - дополнительный уровень безопасности благодаря двухфакторной аутентификации с использованием PIN-кода; - встроенная лицензия на криптопровайдер, что позволяет избежать установки СКЗИ на компьютер; - поддержка российских и международных стандартов информационной безопасности; - совместимость с операционными системами Windows, Linux и Mac.	С тарифами вы можете ознакомиться на сайте банка .	Как получить электронный ключ (токен)

Инструкции для СКЗИ

• КриптоПро CSP
• API Инфокрипт
• API Рутокен

Приводим краткую информацию из инструкции Рутокена:

1. LOGIN (в user указывается номер контейнера на Рутокене, там где находится сертификат. В pin указывается ПИН код к контейнеру)
2. GET_OBJ_LIST_ID Получение списка объектов (сертификатов ЭП)
3. INIT_SIGN_ID Инициализация ЭП
4. SET_SIGN_DATA_ID Данные для ЭП
5. CALC_SIGN_ID Вычисление ЭП
6. GET_SIGN_D_ID Получение ЭП

После выполнения п.6 в поле data будут данные подписи в base64

Подпишите документ и отправьте в Банк

Для создания ЭП к документу потребуется инструмент для подписания - средство криптографической защиты информации (СКЗИ).

СКЗИ вы выбираете самостоятельно исходя из ваших задач и потребностей. Вероятнее всего вы его выбрали на предыдущем шаге. При этом бывает такое, что СКЗИ комбинируют - для формирования запроса используют один инструмент, а для создания ЭП (подписания) - другой.

Процесс подписания и отправки

Шаги

1. Получить access_token
2. Сформировать дайджест документа
3. Создать открепленную ЭП
4. Закодировать ЭП
5. Вызвать метод API

Usecase

Участники usecase

• Платформа - любой web-ресурс или АС, которую вы используете для организации процесса отправки запросов Sber API
• СКЗИ - используемое вашей компанией средство криптографической защиты информации
• Sber API - представляет из себя ресурсы Sber API, к которым обращается Платформа

Предусловия

• Платформа имеет сертификат ЭП на подписанта(-ов)
• Сработал триггер, запускающий процесс подписания и отправки запроса API
• Платформа получила/собрала все необходимые атрибуты для создания и оправки запроса API

Постусловия

• В Банк передан подписанный ЭП документ

Требования к дайджесту

Digest (дайджест) – набор значимых полей платежного документа, который подписывается электронной подписью (ЭП).

• Необходимо использовать кодировку UTF-8;
• Поля дайджеста должны быть отсортированы по алфавиту (от A до Z);
• Значения сумм и комиссий должны задаваться с точностью 2 знака после точки;
• Значения сумм и комиссий в дайджесте и в запросе должны быть идентичны;
• Если какое-то поле не заполняется, его не требуется добавлять в дайджест;
• Разделитель строк должен быть в формате unix (одиночный \n);
• Последняя строка дайджеста не должна содержать перевод строки;
• Перевод строк должен быть экранирован как \n;
• При заполнении полей с данными компании (название компании, например) используйте значения, полученные от Банка в рамках запросов API (в том числе с сохранением регистра).

Передача ЭП в запросе API

Передача электронной подписи (ЭП) осуществляется с использованием массива digestSignatures, где каждый элемент представляет собой подпись (Signature). Каждая подпись должна содержать следующие обязательные поля:

Наименование поля	Описание поля	Пример
base64Encoded (string)	Значение ЭП документа	HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==
certificateUuid (string)	Идентификатор сертификата, использованного при создании ЭП (можно узнать, обратившись к ресурсу /v1/crypto или /v1/crypto/eio)	22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

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

• Если подписи переданы через API, то они сохраняются вместе с документом, а сам документ продолжает свой жизненный цикл.
• Если подписи не были переданы, то документ сохраняется в начальном статусе и ожидает дальнейшей подписи в интерфейсе СберБизнес.

Документ может быть подписан следующими наборами подписей:

• одна (единственная) подпись;
• первая и вторая подписи.

Порядок наложения подписи не имеет значения при наложении первой и второй подписей. Состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля при создании пользователя в СберБизнес.

Требования к ЭП

Банк принимает и обрабатывает ЭП, которая соответствует требованиям:

• Подпись CaDES-BES в формате PEM;
• Подпись открепленная — detatched;
• Алгоритм цифровой подписи ГОСТ Р 34.10-2012 для ключей длины 256 бит;
• Блок с сертификатами (Certificates) обязателен — включает сертификат подписанта;
• Данные подписанта (Signer Info) — содержит информацию только по одному подписанту;
• Присутствует время формирования подписи (Signing Time).

Проверить сформированную подпись можно на странице Удостоверяющего центра :

1. Выберете раздел «Проверка электронной подписи»
2. Выберете тип электронной подписи - Отсоединенная (электронная подпись содержится в отдельном файле)