ym88659208ym87991671
BACKEND | Документация для разработчиков
Развернуть

BACKEND

Обновлено 3 марта 2026

Шаг 1. Обработка токенов

На стороне бэкэнда обеспечьте надежную обработку токенов авторизации, включая своевременное обновление access-токена и refresh-токена. Токены периодически истекают, и важно поддерживать актуальность сеанса пользователя.

Подробнее о работе access-токена и refresh-токена

Важно если данные для бейджика собираются на стороне Партнера необходимо обеспечить обработку OAuth_token'a см. ниже

Обработка OAuth_token'a

Сервер партнера запрашивает для себя авторизационный токен со скопом "api/v1/badgeinfo"

Описание атрибутов запроса

#ИмяЗаголовок/полеОбязательныйОписание
1RqUIDЗаголовокДаУникальный идентификатор сообщения, «maxLength=32 и pattern=([0-9][a-f][A-F])32)», переданный во входящем сообщении. Необходим для журналирования входящих вызовов и удобства разбора инцидентов. Чтобы обеспечить уникальность, можно использовать стандартные библиотеки и классы для генерации UUID/GUID (https://ru.wikipedia.org/wiki/UUID ), убрав из результата разделители «-».
2Content-TypeЗаголовокНетТип передаваемых данных.
3acceptЗаголовокНетМожет принимать значения application/json.
4AuthorizationЗаголовокДаАвторизационные данные. Необходимо в поле указать слово "Basic" и через пробел передать закодированные в BASE64 значения client id и client secret разделенные двоеточием (Basic client id:client secret)
5grant_typeПолеДаУказывается равным client_credentials
6scopeПолеДаОбласть видимости (scope), которая предоставляется Клиенту: список URL API, для которых партнер проходит авторизацию. Если URL API несколько, указывается через пробел. Указывается равным api/v1/badgeinfo.

Пример запроса

POST 'https://oauth-ift.sber.ru/ru/prod/tokens/v2/oauth' \
--header 'accept: application/json' \
--header 'rquid: 012345678901234567890123456789FF' \
--header 'content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic NDBjMWQ1ZGEtMTUzMi0xMWViLWFkYzEtMDI0MmFjMTIwMDAyOjJiYWViODMwLTQyODgtNGY1Yy1iZmZmLWEwMjBkOGFmYWI5Yw=='\
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=api/v1/badgeinfo'

Описание атрибутов ответа

#Название параметраОписаниеПример
1access_tokenСгенерированный Access-токен.f213a511-58d7-4e7c-88b3-a6de380c81da
2token_typeТип запрашиваемого токена. Всегда передается значение «Bearer».Bearer
3expires_inВремя в секундах, в течение которого действует Access Token.60

Пример ответа

HTTP/1.1 200 OK rquid: 012345678901234567890123456789FF
{
  "access_token": "71aab398-acab-4eeb-84bd-99e546751d66",
  "token_type": "bearer",
  "expires_in": 1234
}

Шаг 2. Генерация и передача идентификатора пользователя

Организуйте генерацию уникального идентификатора пользователя (userID), необходимого для идентификации запросов на сервер ЕЛК. Этот идентификатор создается вами и используется в коммуникациях с нашим API.

Правила формирования userID:

  • Уникален для каждого пользователя;
  • Генерируется и хранится на стороне партнера.

Шаг 3. Прокси-обработка запросов

Настройте обработку запросов, поступающих от SDK, как прокси-сервер.

Последовательность действий:

  1. Получение запроса от SDK. Примите HTTP-запросы от фронтальной стороны.

  2. Передача запроса на сервер ЕЛК. Преобразуйте полученный запрос в нужный формат и отправьте его на сервер ЕЛК.

  3. Обработка ответа от ЕЛК. Получите ответ от нашего сервера и верните его обратно в SDK

Если ответ требует дополнительной обработки (например, изменение имени или аватара пользователя), воспользуйтесь рекомендациями из специального раздела (Изменение аватара и имени пользователя)

Рассмотрим простые примеры того, как обрабатывать запросы от SDK и передавать их далее на сервер ЕЛК, а затем возвращать обработанные ответы в SDK.

Пример обработки запроса и ответа по виджетам ЕЛК

1. Запрос от SDK на сервер партнера

SDK отправляет на ваш сервер (url переданный в partnerProfileUrl при инициализации SDK) следующий запрос:

#ИмяТипОбязательныйОписаниеПример
1AuthorizationЗаголовокДаТокен сессии. К значению userID/sessionId (полученному при инициализации SDK) в начале добавляется «Bearer ».Bearer DC3641EC-A0C1-F61A-B2DE-A331C0B2E20F
2[Ключ от партнера]ЗаголовокНетОдин или несколько ключей и их значения, полученные от партнера при инициализации в параметре headersELK.first: one
User-Agent: Ktor client
3AcceptЗаголовокДаОжидаемый тип ответа.application/json
4Content-TypeЗаголовокДаТип передаваемых данных.application/json
2. Запрос на сервер ЕЛК от сервера Партнера

Процесс инициализации вызова ЕЛК

  1. Предварительная проверка сервером партнера

    • Перед инициализацией вызова сервера ЕЛК, сервер партнера проверяет активность access-токена пользователя.
    • При необходимости сервер партнера осуществляет его обновление ("подогрев").

  2. Условие: Отсутствие токенов

    • Если сервер партнера не находит у себя ни активного access-токена, ни refresh-токена пользователя,
    • То сервер партнера должен вернуть в SDK ошибку 401 Unauthorized.

Формат ответа об ошибке:

   HTTP/1.1 401 Unauthorized
   {
       "error": "unauthorized_client"
   }
  1. Запрос данных для виджетов ЕЛК
    • При успешной проверке токенов сервер партнера направляет запрос на сервер ЕЛК.
    • Адрес запроса получен в запросе от SDK
    • Тип запроса GET

Параметры запроса

№Имя (Name)Расположение (In)ОписаниеОбязательный
1infoSourcequeryСписок источников данных. Получен от SDK.Да
2widgetNamequeryНаименование шаблона. Получен от SDK.Да
3x-introspect-rquidheaderУникальный идентификатор сообщения (maxLength=32, pattern=([0-9][a-f][A-F]){32}). Необходим для журналирования. Для генерации можно использовать UUID/GUID, удалив разделители «-».Да
4AuthorizationheaderПолученный ранее access-токен. Должен иметь префикс Bearer. Пример: Bearer DC3641EC-A0C1-F61A-B2DE-A331C0B2E20F. `Да

Пример запроса (cURL):

   curl --request GET \
     'https://oauth-ift.sber.ru/api/v1/userdata?infoSource=[Тип источника данных]&widgetName=[Название шаблона]' \
     --header 'x-Introspect-RqUID: 55286baf3d4548da8d2252b2a8337f20' \
     --header 'Authorization: Bearer 4cf09bfb-ce00-4847-9f24-28377692baf7'
3. Обработка ответа сервером Партнера

Сервер партнера без дополнительной обработки на своей стороне возвращает ответ в SDK.

Пример ответов

 {
   "title": "Иван К",
   "icon": "https://stat.online.sberbank.ru/SBERBANKID/icons/CODE16206.png",
   "iconSize": "40",
   "badge": "https://id.sber.ru/profile/external_partners/elk_assets/badge-gradient.png",
   "initials": "ИК",
   "value": "+7 900 000 00 00",
   "click": {
      "browserUrl": "https://id.sber.ru/profile/?utm_source=partner_profile&utm_medium=app_samokat&utm_campaign=button_nmt"
   }
 }
Наименование параметраЗаголовок/КлючОписаниеОбязательность поля
titlebodyИмя пользователяДа
iconbodyСсылка на аватарку (пока не передаем)Нет
iconSizebodyРазмер аватаркиНет
badgebodyСсылка на иконку SberIDДа
initialsbodyИнициалы пользователяНет
valuebodyНМТНет
clickbodyИнформация о переходе при нажатии на виджетНет
.browserUrlbodyОткрывается ссылка в браузере устройства по urlНет
.deepLinkUrlbodyОткрывается ссылка в браузере устройства по диплинкуНет
.nativeUrlbodyОткрывается нативная шторкаНет
.ssobodyОткрыть с помощью 'app_token' бесшовные переходДа
..webLinkbodyСсылка на поверхность партнераДа
..openInbodyВозможные значения:
- browser
- webview		Нет
..clientIdbodyID партнера на которого осуществляется переходНет

Пример обработки запроса и ответа по бейджу

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

1. Запрос от SDK на сервер партнера

SDK отправляет на ваш сервер (url переданный в partnerProfileUrl при инициализации SDK) следующий запрос:

URL: https://zvuk.com/
HTTP Headers: ["Accept": "application/json", "Authorization": "Bearer 2ffuy3vv7sk11ddfsxn6", "Content-Type": "application/json"]
HTTP Method: POST
HTTP Body: {
  "url" : "https://oauth-ift.sber.ru/api/v1/badgeinfo?widgetName=[Название шаблона]"
}

Описание атрибутов запроса

#ИмяТипОбязательныйОписаниеПример
1AuthorizationЗаголовокДаТокен сессии. К значению userID/sessionId (полученному при инициализации SDK) в начале добавляется «Bearer ».Bearer DC3641EC-A0C1-F61A-B2DE-A331C0B2E20F
2[Ключ от партнера]ЗаголовокНетОдин или несколько ключей и их значения, полученные от партнера при инициализации в параметре headersELK.first: one
User-Agent: Ktor client
3urlStringДаАдрес запроса передаваемый партнеру для запроса данных.https://oauth.sber.ru/api/v1/badgeinfo?widgetName=listDataDefault
2. Запрос на сервер ЕЛК от сервера Партнера

Описание атрибутов запроса api/v1/badgeinfo

  • Адрес запроса получен в запросе от SDK
  • Тип запроса POST
#ИмяЗаголовок/полеОбязательностьОписание
1widgetNamequeryДаНаименование виджета. Получен от SDK
2x-introspect-rquidheaderДаУникальный идентификатор сообщения, «maxLength=32 и pattern=([0-9][a-f][A-F])32)», переданный во входящем сообщении. Необходим для журналирования входящих вызовов и удобства разбора инцидентов. Чтобы обеспечить уникальность, можно использовать стандартные библиотеки и классы для генерации UUID/GUID(https://ru.wikipedia.org/wiki/UUID ), убрав из результата разделители «-».
3AuthorizationheaderДаПолученный ранее OAuth_token. В начало необходимо добавить «Bearer», например: Bearer DC3641EC-A0C1-F61A-B2DE-A331C0B2E20F
4bonusBalance.isActivebodyНетПризнак наличия подключенной программы СберСпасибо
5subscription.isActivebodyНетПризнак наличия активной подписки Прайм

Пример запроса api/v1/badgeinfo

curl --request POST 'https://oauth-ift.sber.ru/api/v1/badgeinfo?widgetName=[Название виджета]' \
--header 'x-Introspect-RqUID: 55286baf3d4548da8d2252b2a8337f20' \
--header 'Authorization: Bearer 4cf09bfb-ce00-4847-9f24-28377692baf7'
--data   '{
  "bonusBalance": {
    "isActive": true
  },
  "subscription": {
    "isActive": true
  }
}'
3. Обработка ответа сервером Партнера

Cервер Партнера получив ответ от сервера ЕЛК дополняет ответ своими данными и перенаправляет его в SDK

HTTP/1.1 200 ОК {
  "widgets": [
    {
      "type": "subscriptions",
      "title": "За выгодой",
      "icon": "${FRONT_STATIC_HOST}${FRONT_STATIC_ASSETS_PATH}/prime.png",
      "click": {
        "browserUrl": "https://-----"
      }
    },
    {
      "type": "bonusBalance",
      "title": "",
      "icon": "${FRONT_STATIC_HOST}${FRONT_STATIC_ASSETS_PATH}/prime.png",
      "click": {
        "browserUrl": "https://-----"
      }
    }
  ]
}
Наименование параметраЗаголовок/ПолеОписаниеОбязательность поля
widgetsbodyМассив бейджиковДа
.typebodyТип бейджикаДа
.titlebodyЗаголовок бейджикаДа
.iconbodyСсылка на иконку бейджикаНет
.clickbodyИнформация о переходе при нажатии на бейджикНет
..browserUrlbodyОткрывается ссылка в браузере устройства по urlНет
..ssobodyАтрибуты для бесшовного переходаНет
...webLinkbodyСсылка для переходаДа
...openInbodyВозможные значения:
- browser
- webview		Да
...clientIdbodyID партнера на которого осуществляется переходДа

Пример для партнера получающего данные для бейджика от сервера ЕЛК

1. Запрос от SDK на сервер партнера

SDK отправляет на ваш сервер (url переданный в partnerProfileUrl при инициализации SDK) следующий запрос:

URL: https://zvuk.com/
HTTP Headers: ["Accept": "application/json", "Authorization": "Bearer 2ffuy3vv7sk11ddfsxn6", "Content-Type": "application/json"]
HTTP Method: POST
HTTP Body: {
  "url" : "https://oauth-ift.sber.ru/api/v1/badgeinfo-provider?infoSource=primeSubscription&widgetName=[Название шаблона]"
}

Описание атрибутов запроса

#ИмяТипОбязательныйОписаниеПример
1AuthorizationЗаголовокДаТокен сессии. К значению userID/sessionId (полученному при инициализации SDK) в начале добавляется «Bearer ».Bearer DC3641EC-A0C1-F61A-B2DE-A331C0B2E20F
2[Ключ от партнера]ЗаголовокНетОдин или несколько ключей и их значения, полученные от партнера при инициализации в параметре headersELK.first: one
User-Agent: Ktor client
3urlStringДаАдрес запроса передаваемый партнеру для запроса данных.https://oauth-ift.sber.ru/api/v1/badgeinfo-provider?infoSource=primeSubscription&widgetName=listDataDefault
2. Запрос на сервер ЕЛК от сервера Партнера

Описание атрибутов запроса api/v1/badgeinfo-provider

  • Адрес запроса получен в запросе от SDK
  • Тип запроса POST
#ИмяЗаголовок/полеОбязательностьОписание
1widgetNamequeryДаНаименование виджета. Получен от SDK
2x-introspect-rquidheaderДаУникальный идентификатор сообщения, «maxLength=32 и pattern=([0-9][a-f][A-F])32)», переданный во входящем сообщении. Необходим для журналирования входящих вызовов и удобства разбора инцидентов. Чтобы обеспечить уникальность, можно использовать стандартные библиотеки и классы для генерации UUID/GUID(https://ru.wikipedia.org/wiki/UUID ), убрав из результата разделители «-».
3AuthorizationheaderДаПолученный ранее access-токен. В начало необходимо добавить «Bearer», например: Bearer DC3641EC-A0C1-F61A-B2DE-A331C0B2E20F
4bonusBalance.isActivebodyНетПризнак наличия подключенной программы СберСпасибо
5subscription.isActivebodyНетПризнак наличия активной подписки Прайм

Пример запроса api/v1/badgeinfo-provider

curl --request POST 'https://oauth-ift.sber.ru/api/v1/badgeinfo-provider?infoSource=primeSubscription&widgetName=[Название виджета]' \
--header 'x-Introspect-RqUID: 55286baf3d4548da8d2252b2a8337f20' \
--header 'Authorization: Bearer 4cf09bfb-ce00-4847-9f24-28377692baf7'
--data   '{
  "bonusBalance": {
    "isActive": true
  },
  "subscription": {
    "isActive": true
  }
}'
3. Обработка ответа сервером Партнера

Cервер Партнера получив ответ от сервера ЕЛК перенаправляет его в SDK (выступает в роли прокси-сервера)

HTTP/1.1 200 ОК {
  "widgets": [
    {
      "type": "subscriptions",
      "title": "За выгодой",
      "icon": "${FRONT_STATIC_HOST}${FRONT_STATIC_ASSETS_PATH}/prime.png",
      "click": {
        "browserUrl": "https://-----"
      }
    },
    {
      "type": "bonusBalance",
      "title": "6 234",
      "icon": "${FRONT_STATIC_HOST}${FRONT_STATIC_ASSETS_PATH}/prime.png",
      "click": {
        "browserUrl": "https://-----"
      }
    }
  ]
}
Наименование параметраЗаголовок/ПолеОписаниеОбязательность поля
widgetsbodyМассив бейджиковДа
.typebodyТип бейджикаДа
.titlebodyЗаголовок бейджикаДа
.iconbodyСсылка на иконку бейджикаНет
.clickbodyИнформация о переходе при нажатии на бейджикНет
..browserUrlbodyОткрывается ссылка в браузере устройства по urlНет
..ssobodyАтрибуты для бесшовного переходаНет
...webLinkbodyСсылка для переходаДа
...openInbodyВозможные значения:
- browser
- webview		Да
...clientIdbodyID партнера на которого осуществляется переходДа

Таким образом, выполнение перечисленных шагов позволит эффективно организовать back-end взаимодействие с сервисом ЕЛК и минимизировать возможные проблемы интеграции.

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Это полезный материал?
Развернуть
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.