СберБизнес ID
Обновлено 7 ноября 2024
Для интеграции СберБизнес ID необходимо пройти с 1 по 4 пункт в Шаги подключения к Sber API.
Общая информация
Сервис авторизации СберБизнес ID построен на базе протокола OAuth 2.0, с использованием типа авторизации Authorization Code Flow и с дополнительными параметрами и значениями, определенными протоколом OpenID Connect. Авторизация с помощью СберБизнес ID позволяет платформе партнера получить информацию о клиенте банка и выполнять операции от имени клиента банка в системе СберБизнес. Доступ до информации клиента и возможность выполнения действий от его лица предоставляется только с согласия клиента.
Вход через СберБизнес ID позволяет клиентам:
- Без заполнения дополнительных форм регистрации создать учетную запись на платформе. Данные клиента подлинные и проверены банком.
- Осуществлять безопасный вход с использованием двухфакторной аутентификации.
- Использовать сервисы Sber API, позволяющие им выдавать партнерскому приложению право на работу со своими данными и отправку черновиков платежных и других типов документов в свой адрес.
Терминология
- Клиент / Пользователь – владелец учетной записи СберБизнес ID, представитель юридического лица/ИП, являющийся пользователем системы СберБизнес и выполняющий операции в системе СберБизнес от имени юридического лица/ИП.
- Партнер – организация, заключившая договор с банком на использование Sber API.
- Платформа – приложение партнера, осуществляющие взаимодействие с сервисами СберБизнес ID и Sber API.
- Ресурсная система – система СберБизнес, в которой работает клиент и доступ до ресурсов которой получает партнерское приложение от лица клиента.
- Код авторизации (authorization code) – код сессии клиента, полученный после аутентификации и подписания им согласия в СберБизнес ID, необходим для получения доступа к токену (Access token), его обновления (Refresh token) и ID token.
- Scope – набор атрибутов (claim) и операций, которые будут доступны партнерскому приложению после авторизации клиента.
- Атрибуты (claim) – атрибуты с информацией о клиенте, которые может запрашивать партнерское приложение из ресурсной системы.
- Операции – это ресурсы API, которые может вызывать партнерское приложение в ресурсной системе, сгруппированные по практическому назначению.
Согласие на передачу данных
Оферта
Согласие на передачу данных (оферта) - это документ, который Банк запрашивает у клиента и подтверждающий право Банка на передачу информации о клиенте третьему лицу (вам, как Партнеру Банка), выполнению операций третьим лицом (вами, как Партнером Банка) от лица Клиента. Согласие (оферта) содержит информацию о том к каким данным, операциям и на какой срок предоставлен доступ Партнеру. При предоставлении Партнеру доступа к данным своих счетов клиент в явном виде указывает каждый счет, к которому предоставляет доступ.
Согласие запрашивается при обращении к сервису авторизации СберБизнес ID:
- При первичном обращении пользователя к Платформе Партнера через сервис СберБизнес ID;
- При повторном обращении, в случае если:
- Истек срок действия предыдущего согласия;
- Предыдущее согласие было отозвано пользователем;
- Состав запрашиваемого согласия (scope) изменился относительно принятого ранее согласия.
Согласие на передачу данных не требуется, если Платформа использует получение и отправку документов только по своей организации.
Если пользователь отзывает согласие, то все выданные токены (Access Token, Refresh Token) деактивируются.
Если Приложение Партнера использует устаревшую версию авторизации /v1/oauth/authorize и состав запрашиваемых разрешений в составе scope изменился, то для получения согласия от Пользователя с новыми разрешениями необходимо перейти на вторую версию авторизации /v2/oauth/authorize.
Требования к платформе
Для обеспечения взаимодействия платформы с сервисом СберБизнес ID:
- Платформа должна выполнять проверки в соответствии с требованием спецификаций: OAuth 2.0, OpenIDConnect.
- Кнопка входа на платформе через СберБизнес ID должна отвечать требованиям дизайна пользовательского интерфейса.
- Платформа должна пройти проверку службы безопасности на устойчивость к уязвимостям из перечня OWASP Top 10.
- Конфигурация бэкенда Платформы должна предусматривать корректную обработку ошибок, возвращаемых в ответах на запросы Sber API,
- Интервал между запросами, направляемыми в Sber API, должен быть больше 2 секунд (2000 миллисекунд),
- В случае возникновения ошибок работы межсервисного взаимодействия для анализа вопроса банк запросит логи обмена со стороны партнера. Рекомендуем реализовать логирование всех взаимодействий с банком с фиксацией отправляемых и (или) получаемых пакетов.
Схема работы сервиса
Участники
- Клиент - представитель ЮЛ/ИП, который имеет пользовательский профиль в СберБизнес своей компании с правом подписи;
- Платформа (в схеме разделили на front и back) - любой web-ресурс (интернет-магазин, мобильное приложение и т.д.), который Вы используете в рамках клиентского пути Клиентов;
- СберБизнес ID - единая учетная запись пользователя ЮЛ/ИП, используемая для регистрации и входа пользователей в продукты и сервисы Банка и партнеров Sber API.
Предусловия
- Клиент находится на Платформе
Постусловия
- Клиент находится на Платформе как авторизованный пользователь
Аутентификация и авторизация глазами клиента
Клиентский путь
| Шаг | Описание | Скриншот |
|---|---|---|
| 1 | Нажать на кнопку «Войти по СберБизнес ID» на платформе |  |
| 2 | Окно ввода логина и пароля, и подтверждение входа |   |
| 3 | После входа отобразится окно согласия на передачу данных | |
| 4 | Подписание согласия с помощью СМС |  |
Получение кода авторизации
Работа с сервисами авторизации версии v1 описана в файле.
/ic/sso/api/v2/oauth/authorize
Запрос позволяет открыть страницу аутентификации в СберБизнес. Ваша Платформа формирует запрос в формате ссылки, устанавливая все параметры, и передает ее браузеру пользователя (Клиента) для прохождения аутентификации. При успешной аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с кодом авторизации (authorization code).
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443 - Промышленный контур
https://sbi.sberbank.ru:9443
Request
/ic/sso/api/v2/oauth/authorize
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| QUERRY PARAMETERS | |||||
| scope | string | string | ^[a-zA-Z0-9._ -]$ | required | Набор атрибутов (claim) и операций, которые будут доступны платформе после авторизации клиента. Должен содержать обязательный параметр openid |
| response_type | string | string | ^code$ | required | Всегда должен содержать значение code. Авторизация по СберБизнес ID поддерживает только authorization code flow протокола OAuth 2.0 |
| client_id | string | string | ^[a-zA-Z0-9]+$ | required | Уникальный идентификатор Платформы, полученный при подключении к Sber API |
| redirect_uri | string | URL | ^(https?:\/\/)?(www.)?([a-z0-9-.]+.[a-z]{2,3})(:[0-9]{1,5})?\/?.*$ | required | Ссылка на ресурс (конечную точку) Платформы, на которую будет передан код авторизации и перенаправлен браузер пользователя после успешной авторизации. Значение переданное в параметре redirect_uri сравнивается по маске со значением, полученным при подключении к Sber API Пример: При подключении вы указали маску для redirect_uri https://example.ru/auth/login Если при запросе кода авторизации будет указан адрес: - https://example.ru, то такое значение не пройдет проверку, т.к. отсутствует часть обязательных path-параметров указанных при регистрации; - https://example.ru/auth/login/register, то такое значение пройдет проверку, т.к. совпадает с зарегистрированным. При этом расширение path-параметров не влияет на проверку |
| state | string | string | ^[a-zA-Z0-9]{36,}$ | required | Параметр для предотвращения CSRF-атак. Значение State должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме платформы. Рекомендуется использовать идентификатор сессии клиента в платформе или один из его производных (например, хэш этого идентификатора), при этом может использоваться любой другой механизм генерации случайного значения достаточной длины для предотвращения подбора. В общем случае оптимально использовать строку длиной не менее 36 символов с проверкой регистра, без использования специальных символов. Полные требования к значению state см. в спецификации rfc6749. Для повторного запроса это значение должно заменяться новым. |
| nonce | string | string | ^[a-zA-Z0-9]{10,}$ | optional | Параметр служит для защиты от replay-атак, то есть для предотвращения обработки одного и того же запроса несколько раз. Значение Nonce должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме платформы. Рекомендуется использовать случайное значение, сохраняемое в сессии клиента в платформе. Для повторного запроса это значение должно заменяться новым. В общем случае оптимально использовать строку длиной не менее 10 символов с проверкой регистра, без использования специальных символов. Полные требования к значению nonce см. в спецификации Open ID Connect |
| code_challenge | string | string | ^[a-zA-Z0-9]$ | optional | Параметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Должен быть уникальным для каждого вызова /v2/oauth/authorize. См. правила формирования параметра в PKCE. Подключение настройки согласуется с менеджером при регистрации платформы. Рекомендуется к использованию, т.к увеличивает безопасность подключения |
| code_challenge_method | string | string | ^S256$ | optional | Связанный с code_challenge параметр. Заполняется в соответствии со спецификацией PKCE. Если указан, то всегда должен содержать значение S256. Параметр «plain» не поддерживается. Если передан параметр code_challenge, то параметр code_challenge_method должен обязательно присутствовать |
https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic/sso/api/v2/oauth/authorize?redirect_uri=https://www.sberbank.ru/ru/person&nonce=80012c9c-1b9a-449e-a8d5-75100ea698ac&state=296014df-dbc8-4559-ab32-041bf5064a40&scope=openid ACCEPTANCE_ADVANCE ACCEPTANCE_LETTER BANK_CONTROL_STATEMENT BANK_CONTROL_STATEMENT_CHANGE_APPLICATION BUSINESS_CARD_LIMIT BUSINESS_CARDS_TRANSFER CARD_ISSUE CERTIFICATE_REQUEST CLIENT_TARIFF COLLECTION_ORDERS CONFIRMATORY_DOCUMENTS_INQUIRY CONTRACT_CLOSE_APPLICATION CORPORATE_CARD_REQUEST CORPORATE_CARDS CREDIT_REQUEST CRYPTO_CERT_REQUEST_EIO CURR_BUY CURR_CONTROL_INFO_REQ CURR_CONTROL_MESSAGE_FROM_BANK CURR_CONTROL_MESSAGE_TO_BANK CURR_SELL CURRENCY_NOTICES CURRENCY_OPERATION_DETAILS DEBT_REGISTRY DICT ESTATE_FEED FILES GENERIC_LETTER_FROM_BANK GENERIC_LETTER_TO_BANK GET_ADVANCE_ACCEPTANCES GET_CLIENT_ACCOUNTS GET_CORRESPONDENTS GET_CREDIT_OFFERS GET_CRYPTO_INFO GET_CRYPTO_INFO_EIO GET_CUSTOMER_INFO GET_PARTNER_OFFERS GET_REQUEST_STATISTICS GET_STATEMENT_ACCOUNT GET_STATEMENT_TRANSACTION GET_TARIFF_PLANS GET_TARIFF_PLANS_LIST_AVAILABLE ORDER_MANDATORY_SALE PAY_DOC_CUR PAY_DOC_RU PAY_DOC_RU_INVOICE_ANY PAY_DOC_RU_INVOICE_BUDGET PAY_DOC_RU_INVOICE PAYMENT_REQUEST_IN PAYMENT_REQUEST_OUT PAYMENTS_REGISTRY PAYROLL SALARY_AGREEMENT SALARY_AGREEMENT_REQUEST TARIFF_PLAN_MANAGEMENT TARIFF_PLAN_MANAGEMENT_JWS TARIFF_PLAN_OVER_BILLING_JSON TARIFF_PLAN_OVER_BILLING_JWS inn orgActualAddress orgFullName orgJuridicalAddress orgKpp orgLawForm orgLawFormShort OrgName orgOgrn orgOktmo terBank email individualExecutiveAgency name offerExpirationDate phone_number userPosition accounts aud buyOnCreditMmb creditLineAvailableSum hasActiveCreditLine HashOrgId iss offerSmartCredit sub summOfferSmartCredit userCryptoType&response_type=code&client_id=92233764567396
Responses
При успешной аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с кодом авторизации (code) и значением параметра state, который был указан в ссылке аутентификации.
302 (OK)
- Модель
- Пример
| Параметр | Тип | Описание |
|---|---|---|
| code | Query | Значение кода авторизации. Формируется в произвольном формате из букв латинского алфавита и цифр длиной 38 символов Срок жизни кода авторизации составляет 120 секунд |
| state | Query | Значение параметра state, полученного при вызове ресурса /v2/oauth/authorize. Полученный параметр state должен быть проверен платформой на соответствие значению, указанному при вызове ресурса /v2/oauth/authorize. Если значения не совпадают, обработка должна быть немедленно прекращена |
https://www.sberbank.ru/ru/person?code=aBc123DEF456Ghi789jKl012Mno345Pqr678&state=296014df-dbc8-4559-ab32-041bf5064a40
При наличии ошибок в ссылке аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с параметрами ошибки.
302 (Error)
- Модель
- Пример
| Error | error_description | Описание |
|---|---|---|
| unsupported_response_type | Responsetype {значение responsetype} not supported | В параметрах запроса кода авторизации указан неправильный response_type. Должно быть указано code. |
| invalid_request | Missing parameters: {не указанные поля через пробел} | В параметрах запроса кода авторизации отсутствует хотя бы один из обязательных параметров: response_type, state, scope и др. Смотрите модель запроса /v2/oauth/authorize выше. |
| invalid_request | Invalid code challenge | В параметре code_challenge передано значение не отвечающее требованиям протокола PKCE |
| invalid_request | Transform algorithm required | Передан параметр code_challenge, но не указан code_challenge_method |
| invalid_request | Transform algorithm not supported | В параметр code_challenge_method указано значение отличное от S256 |
| invalid_request | Code challenge required | В параметрах запроса кода авторизации должны быть указаны параметры code_challenge и code_challenge_method |
| invalid_scope | Scope 'openid' is required | В параметре scope отсутствует обязательный параметр openid |
| invalid_scope | Too many scopes requested | Вызов осуществлен на ресурс предыдущей версии /v1/oauth/authorize и в параметре scope передано более одного дополнительного значения scope |
| invalid_scope | Invalid scope param value | Вызов осуществлен на ресурс предыдущей версии /v1/oauth/authorize и в параметре scope передано незарегистрированное значение scope |
| invalid_scope | Invalid scope | В параметре scope передано незарегистрированное значение scope |
| invalid_scope | Scope PAYMENT_SUBSCRIPTION is required | В параметре scope должен присутствовать параметр payment_subscription. |
| invalid_scope | Scope PAYMENT_SUBSCRIPTION is forbidden | Параметре scope не может содержать параметр payment_subscription. |
https://www.sberbank.ru/ru/person?error=invalid_request&error_description=Missing+parameters%3A+state
В ряде случаев СберБизнес ID не сможет вернуть пользователя на Redirect_uri. При переходе по некорректному URL аутентификации в адресной стороке пользователя будет информация, которая поможет диагностировать ошибку.
302 (Found)
- Модель
- Пример
| Error | Описание |
|---|---|
| invalid_params | В параметрах запроса присутствуют повторяющиеся query параметры |
| redirect_uri_is_absent | В параметрах запроса отсутствует обязательный параметр redirect_uri |
| client_id_is_absent | В параметрах запроса отсутствует обязательный параметр client_id |
| bad_client_id | В параметрах указан незарегистрированный client_id |
| client_blocked | В параметрах указан заблокированный client_id |
| invalid_redirect_uri | В параметрах запроса параметр redirect_uri не совпадает со значением указанным при регистрации платформы |
https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic/sso/#/exception?error=invalid_params&error_description=
Получение токена доступа (access_token)
/ic/sso/api/v2/oauth/token
Запрос /ic/sso/api/v2/oauth/token позволяет обменять код авторизации на токены доступов.
Будет получено три токена: access_token, refresh_token, id_token.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443 - Промышленный контур
https://fintech.sberbank.ru:9443
Request
/ic/sso/api/v2/oauth/token
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| HEADER | |||||
| Content-Type | string | string | ^(application/json|text/plain|application/xml|multipart/form-data|application/x-www-form-urlencoded)$ | required | Тип данных, которые передаются в теле запроса. Должен содержать значение application/x-www-form-urlencoded. |
| Accept | string | string | ^(application/json|application/jose) | optional | Указывает на формат данных, который вы готовы принять от Банка. Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose. |
| From URL Encoded | |||||
| grant_type | string | string | ^(authorization_code|refresh_token)$ | required | Указывает тип предоставления, который используется для запроса токена доступа Значение должно быть authorization_code |
| code | string | string | ^[a-zA-Z0-9]{38}$ | required | Код авторизации. В параметре необходимо использовать значение code, полученное на адрес redirect_uri при успешной аутентификации пользователя по URL аутентификации /v2/oauth/authorize.Каждый code может быть использован только один раз. Например, если при запросе access_token по коду авторизации была допущена ошибка в каком либо из параметров и передано значение code, то повторное использование данного значения code уже будет недопустимо. |
| client_id | string | string | ^[a-zA-Z0-9]+$ | required | Уникальный идентификатор вашей Платформы, полученный при подключении к Sber API |
| redirect_uri | string | string | ^(https?:\/\/)?(www.)?([a-z0-9-.]+.[a-z]{2,3})(:[0-9]{1,5})?\/?.*$ | required | Адрес вашей Платформы, на который СберБизнес ID возвращает пользователя при успешной аутентификации. Должен в точности совпадать со значением, переданным ранее при вызове ресурса /v2/oauth/authorizeПример: Если в redirect_uri было указано https://example.ru/auth/login/register, то точно такое же значение должно быть указано при запросе /v2/oauth/token, даже если зарегистрирован redirect_uri = https://example.ru/auth/login |
| client_secret | string | string | ^[a-zA-Z0-9]{8,256}$ | required | Пароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете. |
| code_verifier | string | string | ^[a-zA-Z0-9]+$ | optional | Параметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Раскодированное значение code_challenge переданное ранее при вызове ресурса /authorize. См. правила формирования параметра в PKCE. Становится обязательным, если при регистрации платформы настройка PKCE была подключена или при вызове ресурса /v2/oauth/authorize параметр code_challenge был передан. |
POST /ic/sso/api/v2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: */*
grant_type=authorization_code&code=abc123def456ghi7893Djkl012mno345pqr678&client_id=92233764567396&redirect_uri=https%3A%2F%2Fwww.sberbank.ru%2Fru%2Fperson&client_secret=vyYPXdBh
Responses
200 (OK)
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| HEADER | |||
| Content-Type | string | required | Если в запросе: - не был передан заголовок Accept или передан в значении application/json, то в ответе параметр будет содержать значение application/json - был передан заголовок Accept в значении application/jose, то в ответе будет указано application/jose и полученное тело ответа потребуется расшифровать. |
| BODY | |||
| { | |||
| access_token | string | required | Авторизационный токен доступа |
| token_type | string | required | Тип токена. Всегда возвращается значение Bearer |
| expires_in | string | required | Срок жизни токена в секундах. Срок жизни access_token составляет 60 минут. |
| refresh_token | string | required | Токен обновления. Используется для обновления Access Token. Подробнее про применение значения refresh_token см. в Обновление токена доступа (access_token) Срок жизни refresh_token составляет 180 дней. |
| scope | string | required | Набор атрибутов (claim) и операций, которые будут доступны Платформе после авторизации клиента. |
| id_token | string | required | Закодированный в Base64URL набор атрибутов клиента, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно. |
| } |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"scope": "openid ACCEPTANCE_ADVANCE ACCEPTANCE_LETTER BANK_CONTROL_STATEMENT BANK_CONTROL_STATEMENT_CHANGE_APPLICATION BUSINESS_CARDS_TRANSFER BUSINESS_CARD_LIMIT CARD_ISSUE CERTIFICATE_REQUEST CLIENT_TARIFF COLLECTION_ORDERS CONFIRMATORY_DOCUMENTS_INQUIRY CONTRACT_CLOSE_APPLICATION CORPORATE_CARDS CORPORATE_CARD_REQUEST CREDIT_REQUEST CRYPTO_CERT_REQUEST_EIO CURRENCY_NOTICES CURRENCY_OPERATION_DETAILS CURR_BUY CURR_CONTROL_INFO_REQ CURR_CONTROL_MESSAGE_FROM_BANK CURR_CONTROL_MESSAGE_TO_BANK CURR_SELL DEBT_REGISTRY DICT ESTATE_FEED FILES GENERIC_LETTER_FROM_BANK GENERIC_LETTER_TO_BANK GET_ADVANCE_ACCEPTANCES GET_CLIENT_ACCOUNTS GET_CORRESPONDENTS GET_CREDIT_OFFERS GET_CRYPTO_INFO GET_CRYPTO_INFO_EIO GET_CUSTOMER_INFO GET_PARTNER_OFFERS GET_REQUEST_STATISTICS GET_STATEMENT_ACCOUNT GET_STATEMENT_TRANSACTION GET_TARIFF_PLANS GET_TARIFF_PLANS_LIST_AVAILABLE ORDER_MANDATORY_SALE PAYMENTS_REGISTRY PAYMENT_REQUEST_IN PAYMENT_REQUEST_OUT PAYROLL PAY_DOC_CUR PAY_DOC_RU PAY_DOC_RU_INVOICE PAY_DOC_RU_INVOICE_ANY PAY_DOC_RU_INVOICE_BUDGET SALARY_AGREEMENT SALARY_AGREEMENT_REQUEST TARIFF_PLAN_MANAGEMENT TARIFF_PLAN_MANAGEMENT_JWS TARIFF_PLAN_OVER_BILLING_JSON TARIFF_PLAN_OVER_BILLING_JWS name inn email phone_number HashOrgId orgKpp orgFullName OrgName orgOgrn orgActualAddress orgJuridicalAddress accounts terBank offerExpirationDate userPosition userCryptoType individualExecutiveAgency orgOktmo offerSmartCredit summOfferSmartCredit buyOnCreditMmb orgLawForm orgLawFormShort hasActiveCreditLine creditLineAvailableSum",
"access_token": "abc123def456ghi789jkl6D012mno345pqr678",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "xbgDF3brf456ghi789jkl012fYmno345pqr678",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI2MjA2Mjg1NDA5ZmNjMjhjZDFmOTZhZjg4MGI1ZjkyNDJiYjZjZGU2NmU3ZGRkZmRmZDNjZGU0YzcyMzcyZWQxIiwiYXVkIjoiOTIyMzM3NjQ1NjczOTYiLCJhY3IiOiJsb2EtMyIsImF6cCI6IjkyMjMzNzY0NTY3Mzk2IiwiYXV0aF90aW1lIjoxNzA2MDE3MTMzLCJhbXIiOiJ7cHdkLCBtY2EsIG1mYSwgb3RwLCBzbXN9IiwiaXNzIjoiaHR0cHM6Ly9lZnMtc2Jib2wtaWZ0LXdlYi50ZXN0c2JpLnNiZXJiYW5rLnJ1Ojk0NDMvaWMiLCJleHAiOjE3MDYwMTc0NTQsImlhdCI6MTcwNjAxNzE1NCwibm9uY2UiOiI4MDAxMmM5Yy0xYjlhLTQ0OWUtYThkNS03NTEwMGVhNjk4YWMifQ.G5PoX66cDvkie6KqdRItbUmb_4QOHZl700gzXUMmldY7Po4Rk_Sw0jM3LNYN2s8NfDe6a1fTF70mR3zOpPFPiA"
}
400 (Bad request)
| error | error_description | Описание причины |
|---|---|---|
| invalid_client | Client authentication failed. Invalid credentials | В запросе передано неправильное значение client_secret |
| invalid_grant | Missing grant_type parameter value | Не заполнен обязательный параметр grant_type |
| invalid_grant | One of the params (code, refresh_token) is required at request | Не заполнен один из обязательных параметров code или refresh_token |
| invalid_grant | Failed to extract shoulder ID from {0} | В параметре code или refresh_token указано некорректное значение |
| invalid_grant | Unknown code = '{0}' | Не найдено переданное значение code. Например, потому что срок действия кода истек или по данному коду уже осуществлялся вызов. |
| invalid_grant | Unknown refresh token = '{0}' | Не найдено переданное значение refresh_token. Например, потому что срок действия токена истек или по данному токену уже был осуществлен обмен на access_token. |
| invalid_grant | Ext service for authz code '{0}' is blocked | Платформа зарегистрированное по указанному client_id - заблокировано. |
| invalid_grant | Invalid credentials for authz code '{0}' | При запросе access_token по коду авторизации указан неверный client_secret |
| invalid_grant | Invalid credentials for refresh_token '{0}' | При запросе access_token по refresh_token указан неверный client_secret |
| invalid_grant | Redirect uri '{0}' is invalid | Переданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации |
| invalid_grant | Failed to verify code verifier | Хешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением, полученным в параметре code_verifier |
| invalid_request | Missing parameters: code | В параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code |
| invalid_request | Missing parameters: refresh_token | В параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token |
| invalid_request | Missing parameters: {0} | Отсутствует параметр redirect_uri |
| invalid_request | client secret expired | Истек срок действия client_secret |
| invalid_request | Code verifier required | При запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier |
| invalid_request | Invalid code verifier | Значение code_verifier не отвечает параметрам протокола PKCE |
| unauthorized_client | Unknown client_id = '{0}' | Переданный client_id не зарегистрирован |
| unauthorized_client | Client '{0}' is blocked | Платформа зарегистрированное по указанному client_id - заблокировано. |
| unsupported_grant_type | Grant type '{0}' is not supported" | В параметре grant_type указано значение отличное от authorization_code или refresh_token |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error": "invalid_grant",
"error_description": "Unknown code = '4b133d0f-4ca8-4825-94cb-c687507605d8-2'"
}
403 (Forbidden)
| errorCode | errorMsg | Описание причины |
|---|---|---|
| requestForbidden | The server configuration prohibits executing a request to the endpoint {0} | На данном сервере запрещен вызов указанного ресурса. Например, вызов ресурса /v2/oauth/token осуществляется на домен https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443, а должен осуществляться на домен https://iftfintech.testsbi.sberbank.ru:9443 |
| certificateNotFound | The certificate was not whitelisted for client_id={0} | Не пройдена проверка сертификата по белому списку |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| errorCode | string | required | Ошибка запроса |
| errorMsg | string | required | Описание ошибки |
| } |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"errorCode": "requestForbidden",
"errorMsg": "The server configuration prohibits executing a request to the endpoint {0}"
}
406 (Not acceptable)
| error | error_description | Описание причины |
|---|---|---|
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | JSON | В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON |
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | JWE Compact Serialization | В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 406 Not acceptable
Content-Type: application/json;charset=UTF-8
{
"error": "SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION",
"error_description": "JSON"
}
500 (Internal Server Error)
| Cause | Message | Description |
|---|---|---|
| UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
access_token
Это уникальный идентификатор, который позволяет платформе подтвердить Банку, что клиент дал ему разрешение на доступ к его данным. Он необходим для использования других запросов Sber API.
С момента получения токен доступа (access_token) действителен 60 минут.
refresh_token
access_token имеет временный характер действия (60 минут с момента получения). Для обновления токена доступа необходимо использовать токен обновления (refresh_token).
С момента получения токен обновления (refresh token) действителен 180 дней.
Обязательно предусмотрите механизм обновления токена в пределах срока его действия, в ином случае платформа не сможет совершать операции с данными клиентами.
ID token (/token)
Этот токен используется для подтверждения того, что пользователь успешно прошел процесс авторизации и имеет доступ к запрашиваемым операциям.
ID token представлен в виде JSON Web Token (JWT) и структурой:
- Алгоритм подписи и тип токена (Header);
- Полезная нагрузка (Payload);
- Электронная подпись (Signature).
Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.
При необходимости вы можете настроить процесс проверки подлинности данных. Для этого необходимо вычислить подпись публичным ключом Банка, декодировав блок Header и Payload (содержимое между двумя точками). Далее сравнить полученное значение c блоком Электронная подпись (содержимое после второй точки).
Пример ID Token
- Модель
- ID token
- Структура
| Параметр | Описание |
|---|---|
| HEADER | |
| typ | Тип токена |
| alg | Алгоритм шифрования |
| PAYLOAD | |
| acr | Уровень аутентификации пользователя: - acr=loa-2 (пользователь аутентифицируется с помощью устройства защиты) - acr=loa-3 (пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации) |
| amr | Ресурсы аутентификации: - amr=pwd — пользователь аутентифицируется с помощью устройства защиты; - amr= {pwd, mca, mfa, otp, sms} — пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации |
| aud | Идентификатор платформы, для которого сформирован ID Token |
| auth_time | Время аутентификации пользователя в СберБизнес ID. Формат поля Unix time |
| azp | Идентификатор платформы, для которого сформирован ID Token |
| exp | Время, после которого ID Token не принимается для обработки. Формат поля Unix time |
| iat | Время формирования ID Token. Формат поля Unix time |
| iss | URL сервиса, сформировавшего ID Token |
| nonce | Значение параметра nonce, полученного при запросе авторизации /v2/oauth/authorize |
| sub | Уникальный идентификатор пользователя |
| SIGNATURE | |
| Массив байт электронной подписи | Проверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Платформе необходимо проверить подпись сертификатом Банка |
eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI2MjA2Mjg1NDA5ZmNjMjhjZDFmOTZhZjg4MGI1ZjkyNDJiYjZjZGU2NmU3ZGRkZmRmZDNjZGU0YzcyMzcyZWQxIiwiYXVkIjoiOTIyMzM3NjQ1NjczOTYiLCJhY3IiOiJsb2EtMyIsImF6cCI6IjkyMjMzNzY0NTY3Mzk2IiwiYXV0aF90aW1lIjoxNzA2MDE3MTMzLCJhbXIiOiJ7cHdkLCBtY2EsIG1mYSwgb3RwLCBzbXN9IiwiaXNzIjoiaHR0cHM6Ly9lZnMtc2Jib2wtaWZ0LXdlYi50ZXN0c2JpLnNiZXJiYW5rLnJ1Ojk0NDMvaWMiLCJleHAiOjE3MDYwMTc0NTQsImlhdCI6MTcwNjAxNzE1NCwibm9uY2UiOiI4MDAxMmM5Yy0xYjlhLTQ0OWUtYThkNS03NTEwMGVhNjk4YWMifQ.G5PoX66cDvkie6KqdRItbUmb_4QOHZl700gzXUMmldY7Po4Rk_Sw0jM3LNYN2s8NfDe6a1fTF70mR3zOpPFPiA
Заголовок. Алгоритм и тип токена:
{
"typ": "JWT",
"alg": "gost34.10-2012"
}
Полезная нагрузка:
{
"sub": "6206285409fcc28cd1f96af880b5f9242bb6cde66e7dddfdfd3cde4c72372ed1",
"aud": "92233764567396",
"acr": "loa-3",
"azp": "92233764567396",
"auth_time": 1706017133,
"amr": "{pwd, mca, mfa, otp, sms}",
"iss": "https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic",
"exp": 1706017454,
"iat": 1706017154,
"nonce": "80012c9c-1b9a-449e-a8d5-75100ea698ac",
"header": {
"typ": "JWT",
"alg": "gost34.10-2012"
}
}
Электронная подпись:
<Массив байт электронной подписи>
Получение информации (user-info)
/ic/sso/api/v2/oauth/user-info
Запрос /ic/sso/api/v2/oauth/user-info позволяет получить информацию о клиенте в ID token.
Для получения информации необходимо отправить GET-запрос /ic/sso/api/v2/oauth/user-infoс токеном доступа (access_token) пользователя в параметре Authorization заголовка.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443 - Промышленный контур
https://fintech.sberbank.ru:9443
Request
/ic/sso/api/v2/oauth/user-info
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| HEADER | |||||
| Authorization | string | string | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
GET /ic/sso/api/v2/oauth/user-info HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678fd
Responses
200 (OK)
- Модель
- ID token
- Структура
| Параметр | Описание |
|---|---|
| HEADER | |
| typ | Тип токена |
| alg | Алгоритм шифрования |
| PAYLOAD | |
| aud | Идентификатор платформы, для которого сформирован ID Token |
| iss | URL сервиса, сформировавшего ID Token |
| sub | Уникальный идентификатор пользователя |
| Значения атрибутов (claim) | которые указали в Scope в ссылке запроса /v2/oauth/token |
| SIGNATURE | |
| Массив байт электронной подписи | Проверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Платформе необходимо проверить подпись сертификатом Банка |
eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI2MjA2Mjg1NDA5ZmNjMjhjZDFmOTZhZjg4MGI1ZjkyNDJiYjZjZGU2NmU3ZGRkZmRmZDNjZGU0YzcyMzcyZWQxIiwib3JnS3BwIjoiNjgzODAxOTEwIiwiaXNzIjoiaHR0cHM6Ly9lZnMtc2Jib2wtaWZ0LXdlYi50ZXN0c2JpLnNiZXJiYW5rLnJ1Ojk0NDMvaWMiLCJpbm4iOiI3Mzc5MTkwNTIyIiwib3JnSnVyaWRpY2FsQWRkcmVzcyI6IjEyNzY0NCwg0LMu0JzQvtGB0LrQstCwLCDQsS3RgC4g0JrQsNGA0LXQu9GM0YHQutC40LksINC00L7QvCA1LCDQutC-0YDQvy4gMSwg0L7RhC4gMjQwIiwiT3JnTmFtZSI6ItCi0JXQodCiOTAzNiIsIm9yZ0Z1bGxOYW1lIjoi0KLQldCh0KI5MDM2IiwiYnV5T25DcmVkaXRNbWIiOnRydWUsImluZGl2aWR1YWxFeGVjdXRpdmVBZ2VuY3kiOjEsInRlckJhbmsiOiLQo9Cg0JDQm9Cs0KHQmtCY0Jkg0JHQkNCd0Jog0J_QkNCeINCh0LHQtdGA0LHQsNC90LoiLCJ1c2VyQ3J5cHRvVHlwZSI6IlNNUyIsImF1ZCI6IjkyMjMzNzY0NTY3Mzk2Iiwic3VtbU9mZmVyU21hcnRDcmVkaXQiOjAsIm9yZ0xhd0Zvcm1TaG9ydCI6ItCe0J7QniIsIm9yZ09ncm4iOiIxMjM4MjE1OTQ1NjM3Iiwib3JnQWN0dWFsQWRkcmVzcyI6IjEyNzY0NCwg0LMu0JzQvtGB0LrQstCwLCDQsS3RgC4g0JrQsNGA0LXQu9GM0YHQutC40LksINC00L7QvCA1LCDQutC-0YDQvy4gMSwg0L7RhC4gMjQwIiwiSGFzaE9yZ0lkIjoiNmU3Y2U2NTgyZDMwMTkwZmRmYzAxMTExMDY4ZWNjMjNlMmRkY2QzZWFkYTBhNjA3MzU3ZTEwNDg4NWZmYjI3ZCIsIm9mZmVyU21hcnRDcmVkaXQiOmZhbHNlLCJuYW1lIjoi0KTQsNC8MDQg0JjQvNGPMDQg0J7RgtGHMDQiLCJ1c2VyUG9zaXRpb24iOiLQlNC40YDQtdC60YLQvtGAIiwiaGFzQWN0aXZlQ3JlZGl0TGluZSI6ZmFsc2UsInBob25lX251bWJlciI6Ijc0NDIwMDI0ODk2Iiwib3JnTGF3Rm9ybSI6ItCe0LHRidC10YHRgtCy0L4g0YEg0L7Qs9GA0LDQvdC40YfQtdC90L3QvtC5INC-0YLQstC10YLRgdGC0LLQtdC90L3QvtGB0YLRjNGOIiwiZW1haWwiOiJoaHlhVUBDbmduRS5EQiJ9.IhE9hwMISp3vcxuW7lRctZC2vXLPfIUPIisYgrqoEiAEaKx0T7uFQk_W1jD1oJ1j_bDBWbvVYOF7nT8zMDX8yw
Заголовок. Алгоритм и тип токена:
{
"typ": "JWT",
"alg": "gost34.10-2012"
}
Полезная нагрузка:
{
"sub": "6206285409fcc28cd1f96af880b5f9242bb6cde66e7dddfdfd3cde4c72372ed1",
"orgKpp": "683801910",
"iss": "https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic",
"inn": "7379190522",
"orgJuridicalAddress": "127644, г.Москва, б-р. Карельский, дом 5, корп. 1, оф. 240",
"OrgName": "ТЕСТ9036",
"orgFullName": "ТЕСТ9036",
"buyOnCreditMmb": true,
"individualExecutiveAgency": 1,
"terBank": "УРАЛЬСКИЙ БАНК ПАО Сбербанк",
"userCryptoType": "SMS",
"aud": "92233764567396",
"summOfferSmartCredit": 0,
"orgLawFormShort": "ООО",
"orgOgrn": "1238215945637",
"orgActualAddress": "127644, г.Москва, б-р. Карельский, дом 5, корп. 1, оф. 240",
"HashOrgId": "6e7ce6582d30190fdfc01111068ecc23e2ddcd3eada0a607357e104885ffb27d",
"offerSmartCredit": false,
"name": "Фам04 Имя04 Отч04",
"userPosition": "Директор",
"hasActiveCreditLine": false,
"phone_number": "74420024896",
"orgLawForm": "Общество с ограниченной ответственностью",
"email": "hhyaU@CngnE.DB"
}
Электронная подпись:
<Массив байт электронной подписи>
400 (Bad request)
| error | error_description | Описание причины |
|---|---|---|
| invalid_request | Missing authorization header | Отсутствует обязательный параметр заголовка Authorization |
| invalid_request | Incorrect authorization method | В параметре заголовка Authorization указан некорректный тип (добавить Bearer) |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error": "invalid_request",
"error_description": "Missing authorization header."
}
401 (Unauthorized Error)
| error | error_description | Описание причины |
|---|---|---|
| invalid_token | Access Token <значение полученного токена> not found | Переданный токен не найден. Например, потому что истек срок его действия или пользователь отозвал согласие на передачу данных |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"error": "invalid_token",
"error_description": "Access Token 'xbgKDVrgf756ghi789jk452DmaNKFtEpdqr678' not found."
}
403 (Forbidden)
| errorCode | errorMsg | Описание причины |
|---|---|---|
| requestForbidden | The server configuration prohibits executing a request to the endpoint {0} | На данном сервере запрещен вызов указанного ресурса. Например, вызов ресурса /v2/oauth/token осуществляется на домен https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443, а должен осуществляться на домен https://iftfintech.testsbi.sberbank.ru:9443 |
| certificateNotFound | The certificate was not whitelisted for client_id={0} | Не пройдена проверка сертификата по белому списку |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| errorCode | string | required | Ошибка запроса |
| errorMsg | string | required | Описание ошибки |
| } |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"errorCode": "requestForbidden",
"errorMsg": "The server configuration prohibits executing a request to the endpoint {0}"
}
406 (Not acceptable)
| error | error_description | Описание причины |
|---|---|---|
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | JSON | В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON |
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | JWE Compact Serialization | В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 406 Not acceptable
Content-Type: application/json;charset=UTF-8
{
"error": "SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION",
"error_description": "JSON"
}
500 (Internal Server Error)
| Cause | Message | Description |
|---|---|---|
| UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
ID token (/user-info)
Этот токен содержит информацию о клиенте, представлен в виде JSON Web Token (JWT) и структурой:
- Алгоритм подписи и тип токена (Header);
- Полезная нагрузка (Payload);
- Электронная подпись (Signature).
Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.
При необходимости вы можете настроить процесс проверки подлинности данных. Для этого необходимо вычислить подпись публичным ключом Банка, декодировав блок Header и Payload (содержимое между двумя точками). Далее сравнить полученное значение c блоком Электронная подпись (содержимое после второй точки).
Обновление токена доступа (refresh_token)
Cрок действия токена доступа (access_token) 60 минут. Вам необходимо реализовать обновление токена доступа для последующих запросов в канале Sber API.
/ic/sso/api/v2/oauth/token
Запрос /v2/oauth/token позволяет получить новый токен доступа (access_token) и новый токен обновления (refresh_token).
Для использования запроса необходимо указать значение токена обновления (refresh_token), полученный при последней авторизации по СберБизнес ID или последнего обновления токена доступа.
Использованный токен обновления (refresh_token) переводится в статус резервного на 2 часа с момента выпуска новой пары ключей (access_token/refresh_token).
Если по каким-то причинам сформированная пара не была получена от Банка, то рекомендуется повторно отправить запрос на актуализацию ключей в течение 1 часа от момента отправки первой попытки, используя тот же refresh_token. Для последующих обновлений ключей доступа необходимо использовать refresh_token из новой пары ключей (access_token/refresh_token).
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443 - Промышленный контур
https://fintech.sberbank.ru:9443
Request
/ic/sso/api/v2/oauth/token
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| HEADER | |||||
| Content-Type | string | string | ^(application/json|text/plain|application/xml|multipart/form-data|application/x-www-form-urlencoded)$ | required | Тип данных, которые передаются в теле запроса. Должен содержать значение application/x-www-form-urlencoded. |
| Accept | string | string | ^(application/json|application/jose) | optional | Указывает на формат данных, который вы готовы принять от Банка. Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose. |
| BODY | |||||
| { | |||||
| grant_type | string | string | ^(authorization_code|refresh_token)$ | required | Указывает тип предоставления, который используется для запроса токена доступа Значение должно быть refresh_token |
| refresh_token | string | string | ^[a-zA-Z0-9]{38}$ | required | Значение refresh_token полученное при обмене кода авторизации на access_token |
| client_id | string | string | ^[a-zA-Z0-9]+$ | required | Уникальный идентификатор вашей Платформы, полученный при подключении к Sber API |
| client_secret | string | string | ^[a-zA-Z0-9]{8,256}$ | required | Пароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете. |
| } |
POST /ic/sso/api/v2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: */*
grant_type=refresh_token&client_id=92233767396&client_secret=vyYP1XdET3&refresh_token=xbgKDVrgf756ghi789djkl012mNKFt4Epqr678
Responses
200 (OK)
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| HEADER | |||
| Content-Type | string | required | Если в запросе: - не был передан заголовок Accept или передан в значении application/json, то в ответе параметр будет содержать значение application/json - был передан заголовок Accept в значении application/jose, то в ответе будет указано application/jose и полученное тело ответа потребуется расшифровать. |
| BODY | |||
| { | |||
| access_token | string | required | Авторизационный токен доступа |
| token_type | string | required | Тип токена. Всегда возвращается значение Bearer |
| expires_in | string | required | Срок жизни токена в секундах. Срок жизни access_token составляет 60 минут. |
| refresh_token | string | required | Токен обновления. Используется для обновления Access Token. Подробнее про применение значения refresh_token см. в Обновление токена доступа (access_token) Срок жизни refresh_token составляет 180 дней. |
| scope | string | required | Набор атрибутов (claim) и операций, которые будут доступны Платформе после авторизации клиента. |
| id_token | string | required | Закодированный в Base64URL набор атрибутов клиента, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно. Подробнее о декодировании и параметрах id_token см. в ID Token |
| } |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"scope": "openid ACCEPTANCE_ADVANCE ACCEPTANCE_LETTER BANK_CONTROL_STATEMENT BANK_CONTROL_STATEMENT_CHANGE_APPLICATION BUSINESS_CARDS_TRANSFER BUSINESS_CARD_LIMIT CARD_ISSUE CERTIFICATE_REQUEST CLIENT_TARIFF COLLECTION_ORDERS CONFIRMATORY_DOCUMENTS_INQUIRY CONTRACT_CLOSE_APPLICATION CORPORATE_CARDS CORPORATE_CARD_REQUEST CREDIT_REQUEST CRYPTO_CERT_REQUEST_EIO CURRENCY_NOTICES CURRENCY_OPERATION_DETAILS CURR_BUY CURR_CONTROL_INFO_REQ CURR_CONTROL_MESSAGE_FROM_BANK CURR_CONTROL_MESSAGE_TO_BANK CURR_SELL DEBT_REGISTRY DICT ESTATE_FEED FILES GENERIC_LETTER_FROM_BANK GENERIC_LETTER_TO_BANK GET_ADVANCE_ACCEPTANCES GET_CLIENT_ACCOUNTS GET_CORRESPONDENTS GET_CREDIT_OFFERS GET_CRYPTO_INFO GET_CRYPTO_INFO_EIO GET_CUSTOMER_INFO GET_PARTNER_OFFERS GET_REQUEST_STATISTICS GET_STATEMENT_ACCOUNT GET_STATEMENT_TRANSACTION GET_TARIFF_PLANS GET_TARIFF_PLANS_LIST_AVAILABLE ORDER_MANDATORY_SALE PAYMENTS_REGISTRY PAYMENT_REQUEST_IN PAYMENT_REQUEST_OUT PAYROLL PAY_DOC_CUR PAY_DOC_RU PAY_DOC_RU_INVOICE PAY_DOC_RU_INVOICE_ANY PAY_DOC_RU_INVOICE_BUDGET SALARY_AGREEMENT SALARY_AGREEMENT_REQUEST TARIFF_PLAN_MANAGEMENT TARIFF_PLAN_MANAGEMENT_JWS TARIFF_PLAN_OVER_BILLING_JSON TARIFF_PLAN_OVER_BILLING_JWS name inn email phone_number HashOrgId orgKpp orgFullName OrgName orgOgrn orgActualAddress orgJuridicalAddress accounts terBank offerExpirationDate userPosition userCryptoType individualExecutiveAgency orgOktmo offerSmartCredit summOfferSmartCredit buyOnCreditMmb orgLawForm orgLawFormShort hasActiveCreditLine creditLineAvailableSum",
"access_token": "xbgKDVrgf756ghi789jk452DmaNKFtEpdqr678",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "xbgKzDVrgf756ghi415Wdl012mNDKFtEpqr678"
}
400 (Bad request)
| error | error_description | Описание причины |
|---|---|---|
| invalid_client | Client authentication failed. Invalid credentials | В запросе передано неправильное значение client_secret |
| invalid_grant | Missing grant_type parameter value | Не заполнен обязательный параметр grant_type |
| invalid_grant | One of the params (code, refresh_token) is required at request | Не заполнен один из обязательных параметров code или refresh_token |
| invalid_grant | Failed to extract shoulder ID from {0} | В параметре code или refresh_token указано некорректное значение |
| invalid_grant | Unknown code = '{0}' | Не найдено переданное значение code. Например, потому что срок действия кода истек или по данному коду уже осуществлялся вызов. |
| invalid_grant | Unknown refresh token = '{0}' | Не найдено переданное значение refresh_token. Например, потому что срок действия токена истек или по данному токену уже был осуществлен обмен на access_token. |
| invalid_grant | Ext service for authz code '{0}' is blocked | Платформа зарегистрированное по указанному client_id - заблокировано. |
| invalid_grant | Invalid credentials for authz code '{0}' | При запросе access_token по коду авторизации указан неверный client_secret |
| invalid_grant | Invalid credentials for refresh_token '{0}' | При запросе access_token по refresh_token указан неверный client_secret |
| invalid_grant | Redirect uri '{0}' is invalid | Переданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации |
| invalid_grant | Failed to verify code verifier | Хешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением, полученным в параметре code_verifier |
| invalid_request | Missing parameters: code | В параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code |
| invalid_request | Missing parameters: refresh_token | В параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token |
| invalid_request | Missing parameters: {0} | Отсутствует параметр redirect_uri |
| invalid_request | client secret expired | Истек срок действия client_secret |
| invalid_request | Code verifier required | При запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier |
| invalid_request | Invalid code verifier | Значение code_verifier не отвечает параметрам протокола PKCE |
| unauthorized_client | Unknown client_id = '{0}' | Переданный client_id не зарегистрирован |
| unauthorized_client | Client '{0}' is blocked | Платформа зарегистрированное по указанному client_id - заблокировано. |
| unsupported_grant_type | Grant type '{0}' is not supported" | В параметре grant_type указано значение отличное от authorization_code или refresh_token |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error": "invalid_grant",
"error_description": "Unknown code = '4b133d0f-4ca8-4825-94cb-c687507605d8-2'"
}
403 (Forbidden)
| errorCode | errorMsg | Описание причины |
|---|---|---|
| requestForbidden | The server configuration prohibits executing a request to the endpoint {0} | На данном сервере запрещен вызов указанного ресурса. Например, вызов ресурса /v2/oauth/token осуществляется на домен https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443, а должен осуществляться на домен https://iftfintech.testsbi.sberbank.ru:9443 |
| certificateNotFound | The certificate was not whitelisted for client_id={0} | Не пройдена проверка сертификата по белому списку |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| errorCode | string | required | Ошибка запроса |
| errorMsg | string | required | Описание ошибки |
| } |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"errorCode": "requestForbidden",
"errorMsg": "The server configuration prohibits executing a request to the endpoint {0}"
}
406 (Not acceptable)
| error | error_description | Описание причины |
|---|---|---|
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | JSON | В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON |
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | JWE Compact Serialization | В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | required | Описание ошибки |
| } |
HTTP/1.1 406 Not acceptable
Content-Type: application/json;charset=UTF-8
{
"error": "SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION",
"error_description": "JSON"
}
500 (Internal Server Error)
| Cause | Message | Description |
|---|---|---|
| UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
Обновление Client Secret (каждые 40 дней)
client_secret – это пароль от вашей интеграции, который увеличивает безопасность передачи данных.
В процессе заключения договора на Sber API поддержка Банка свяжется с контактным лицом вашей компании по вопросу получения Client Secret.
Обновить client_secret можно вручную в Личном кабинете Sber API или с помощь ресурса /v1/change-client-secret
Срок действия client_secret составляет 40 дней с даты выпуска. Обновлять Client Secret рекомендуем заранее до истечения срока во избежание блокировки интеграции.
Банк также отправляет уведомления о скором окончании действия client_secret через E-mail контактного лица из Заявления на подключение к Sber API. Уведомление будет направлено за 5 дней до срока окончания действия client secret.
/ic/sso/api/v1/change-client-secret
Запрос позволяет обновить client _secret вашей интеграции. В запросе необходимо передавать токен доступа (access_token) Пользователя собственной организации.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443 - Промышленный контур
https://fintech.sberbank.ru:9443
Request
/ic/sso/api/v1/change-client-secret
- Модель
- Пример
| Наименование | Тип | Формат | Regexp | Обязательность | Описание |
|---|---|---|---|---|---|
| QUERRY PARAMETERS | |||||
| access_token | string | UUID | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
| client_id | string | string | ^[a-zA-Z0-9]+$ | optional | Указывается идентификатор Платформы (client_id), для которого необходимо изменить client_secret. Если client_id не указан, то будет изменен client_secret приложения, для которого выдан access_token. |
| client_secret | string | string | ^[a-zA-Z0-9]{8,256}$ | required | Пароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете. |
| new_client_secret | string | string | ^[a-zA-Z0-9]{8,256}$ | required | Новое значение client_secret Плафтормы, для которого необходимо изменить client_secret |
POST /ic/sso/api/v1/change-client-secret?access_token=xbgKDVrgf756ghi789jk452DmaNKFtEpdqr678&client_id=9223567396&client_secret=vyY12PXdET&new_client_secret=vyY13PX12d1
Responses
200 (ОК)
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| clientSecretExpiration | number | optional | Срок действия нового Client Secret (в днях) |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"clientSecretExpiration": 40
}
400 (Bad request)
| error | error_description | Описание причины |
|---|---|---|
| Передано некорректное значение нового client secret: '{0}' | Значение нового Client Secret совпадает с текущим или не прошло валидацию на допустимый размер значения | |
| Передано некорректное значение действующего client secret: '{0}' | Значение переданное в параметре client_secret не совпадает со значением указанным для client_id | |
| invalid_grant | Parameter 'access_token' is required at request | В запросе не был передан access_token пользователя вашей компании |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| error_description | string | optional | Описание ошибки |
| } |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error": "Передано некорректное значение нового client secret: 'vyYPX1dET'"
}
401 (Unauthorized Error)
| error | Описание причины |
|---|---|
| UNAUTHORIZED | Переданный токен не найден. Например, потому что пользователь отозвал согласие на передачу данных |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| } |
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"error": "UNAUTHORIZED"
}
403 (Forbidden)
| error | Описание причины |
|---|---|
| Изменение client secret недоступно | Для данного типа Платформы использование ресурса /change-client-secret недоступно |
| Client secret просрочен | Срок действия текущего Client Secret истек. Для обновления Client Secret обратитесь воспользуйтесь соответствующей функциональностью Личного кабинета (если есть доступ) или в техническую поддержку Банка. |
| Попытка изменения client secret при помощи access token, выданного пользователем, не принадлежащим организации, предоставляющей услуги внешнего сервиса | Access Token выдан пользователем, не принадлежащим организации владельцу Платформы |
| Попытка изменения client secret внешнему сервису, организация которого отличается от организации пользователя, выдавшего access token | Параметр client_id указан и организация владельца Access Token не совпадает с организацией владельца Платформы, чей client_id указан |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| } |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"error": "Попытка изменения client secret при помощи access token, выданного пользователем, не принадлежащим организации, предоставляющей услуги внешнего сервиса"
}
406 (Not acceptable)
| error | Описание причины |
|---|---|
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | Для Платформы установлен запрет на прием запросов с http-заголовком Accept со значением application/jose |
| SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION | Для Платформы установлен запрет на прием запросов с http-заголовком Accept со значением application/json |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| { | |||
| error | string | required | Ошибка запроса |
| } |
HTTP/1.1 406 Not acceptable
Content-Type: application/json;charset=UTF-8
{
"error": "SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION"
}
500 (Internal Server Error)
| Cause | Message | Description |
|---|---|---|
| UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
| Notice { | |||
| cause | string | optional | Причина или основание сообщения, |
| referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
| message | string | optional | Сообщение, |
| } |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
FAQ
Кто может подписывать согласие на передачу данных при авторизации по СберБизнес ID?
Учетная запись СберБизнес ID с правом подписи:
- Первая;
- Вторая;
- Единственная.
Где посмотреть право подписи и тип подписи?
- Необходимо зайти в СберБизнес
- В верхнем правом углу нажать на свой профиль
- Нажать на СберБизнес ID
- На новой странице внизу необходимо найти поле «Полномочия», здесь будет указан тип подписи.
Отсутствие поля "Полномочия" в разделе "Мой профиль" говорит об отсутствии права на подпись. Такой пользователь не сможет подписать Согласие на передачу данных от лица компании.
Как получить право подписи?
Вы можете предоставить право подписи путем подачи корректирующего заявление в офис банка или выпустить новую учетную запись с правом подписи по инструкции.
Как мне тестировать сервис на тестовом контуре?
После подписания документов на подключение к Sber API, вам направят комплект настроек и данные по организациям и учетными записями для тестирования.
Что делать если истек токен доступа (access_token)?
Необходимо получить новый токен доступа с помощью токена обновления (refresh_token) по инструкции.
Что будет с токеном обновления (refresh_token) после получения новой пары токена доступа (access_token) и обновления (refresh_token)?
Использованный токен обновления будет активным 2 часа с момента его использования для получения новой пары токена доступа (access_token) и токена обновления (refresh_token).
Что делать если истек срок действия токена обновления (refresh_token)?
Пользователю необходимо повторно пройти процесс авторизации для получения Платформой новой пары access_token и refresh_token.
Какую информацию по Клиенту я получу?
Вы получите информацию, которую запрашивали в виде атрибутов(claim) в ссылке аутентификации в параметрах scope.
Где я могу ознакомиться со всеми возможными атрибутами (claim)?
На странице Атрибуты (Claims)
Чем отличаются ID token при запросе `/v2/oauth/token` и `/v2/oauth/user-info`?
ID token при запросе /v2/oauth/token содержит информацию об авторизации Пользователя и используется для его валидации.
ID token при запросе /v2/oauth/user-info содержит информацию о Пользователе и организации.