Баланс счёта

Возвращает сводную выписку по счёту в Сбер за день: входящий и исходящий остаток, обороты и количество операций. Метод работает по авторизованной сессии пользователя и только читает данные из Сбера: он не создаёт операций.

Отдельного баланса у корпоративной карты Сбер нет: доступный по карте остаток равен остатку на счёте, к которому она выпущена. Исходящий остаток за текущий день — текущий баланс счёта.

Сценарий интеграции

Получите session_id авторизованной сессии Сбер — см. раздел «Общее».
Получите номер счёта карты в поле account_number метода списка корпоративных карт.
Сформируйте подпись от session_id и account_number и отправьте GET-запрос. Чтобы получить текущий баланс, не передавайте date.
Используйте closing_balance как остаток на счёте. Данные актуальны на момент запроса: при необходимости запросите их заново.

URL

ProductionStage

GET https://api.baas.kvell.group/v1/sber/accounts/{account_number}/balance

GET https://api.baas.stage.kvell.group/v1/sber/accounts/{account_number}/balance

Запрос

Path-параметры

Параметр	Тип	Обязательно	Описание
`account_number`	string	Да	Номер счёта — ровно 20 цифр. Возвращается в поле `account_number` метода списка корпоративных карт.

Query-параметры

Параметр	Тип	Обязательно	Описание
`session_id`	string	Да	Идентификатор авторизованной сессии Сбер в формате UUID. Сессия должна принадлежать Sber-профилю магазина, ключ которого передан в `X-Api-Key`.
`date`	string	Нет	Дата выписки в формате `YYYY-MM-DD`. По умолчанию — текущая дата по московскому времени. Дата в будущем не допускается. Сбер отдаёт выписку за текущий и пять предыдущих лет.

Заголовки

Название	Тип	Обязательно	Описание
`X-Api-Key`	string	Да	Идентификатор магазина в формате UUID.
`X-Signature`	string	Да	Подпись запроса.

Формирование подписи

Подпись — SHA-256 в шестнадцатеричном виде в нижнем регистре от строки, собранной без разделителей в таком порядке:

sha256({X-Api-Key}{session_id}{account_number}{secret_key})

X-Api-Key — идентификатор магазина;
session_id — значение query-параметра без изменений;
account_number — номер счёта из пути запроса без изменений;
secret_key — секретный ключ из настроек магазина мерчанта.

Строка кодируется в UTF-8. date в подписи не участвует. Подпись действует только для счёта, номер которого в неё включён: для каждого счёта подпись рассчитывается отдельно.

Пример

curl --request GET \
  --url 'https://api.baas.stage.kvell.group/v1/sber/accounts/40702810600000200000/balance?session_id=11111111-1111-4111-8111-111111111111' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>'

Ответ

Выберите HTTP-код, чтобы посмотреть пример, параметры ответа и рекомендуемые действия.

Если HTTP-ответ не получен

Метод только читает данные, поэтому после таймаута или разрыва соединения безопасно повторите тот же запрос с теми же параметрами и подписью.

2004004014034044225XX

Пример ответа 200 (OK)

{
  "opening_balance": {
    "amount": "301000.50",
    "currency_name": "RUB"
  },
  "opening_balance_rub": {
    "amount": "301000.50",
    "currency_name": "RUB"
  },
  "closing_balance": {
    "amount": "300000.00",
    "currency_name": "RUB"
  },
  "closing_balance_rub": {
    "amount": "300000.00",
    "currency_name": "RUB"
  },
  "debit_turnover": {
    "amount": "1500.50",
    "currency_name": "RUB"
  },
  "debit_turnover_rub": {
    "amount": "1500.50",
    "currency_name": "RUB"
  },
  "credit_turnover": {
    "amount": "500.00",
    "currency_name": "RUB"
  },
  "credit_turnover_rub": {
    "amount": "500.00",
    "currency_name": "RUB"
  },
  "debit_transactions_number": 2,
  "credit_transactions_number": 1,
  "composed_date_time": "2026-10-28T12:30:00",
  "last_movement_date": "2026-10-28",
  "prev_operation_date": "2026-10-27",
  "opening_rate": "1"
}

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

Любое поле может быть null, если Сбер его не вернул.

Параметр	Тип	Описание
`opening_balance`	object \| null	Входящий остаток на начало дня в валюте счёта. Структура описана в разделе «Объект суммы».
`opening_balance_rub`	object \| null	Входящий остаток в рублях.
`closing_balance`	object \| null	Исходящий остаток в валюте счёта. За текущий день — текущий баланс счёта.
`closing_balance_rub`	object \| null	Исходящий остаток в рублях.
`debit_turnover`	object \| null	Сумма списаний за день в валюте счёта.
`debit_turnover_rub`	object \| null	Сумма списаний за день в рублях.
`credit_turnover`	object \| null	Сумма зачислений за день в валюте счёта.
`credit_turnover_rub`	object \| null	Сумма зачислений за день в рублях.
`debit_transactions_number`	integer \| null	Количество списаний за день.
`credit_transactions_number`	integer \| null	Количество зачислений за день.
`composed_date_time`	string \| null	Дата и время составления сводки в формате Сбера, например `2026-10-28T12:30:00`.
`last_movement_date`	string \| null	Дата последней операции по счёту за запрошенный период в формате `YYYY-MM-DD`.
`prev_operation_date`	string \| null	Дата предыдущей операции по счёту за запрошенный период в формате `YYYY-MM-DD`.
`opening_rate`	string \| null	Курс ЦБ за единицу валюты счёта на начало периода.

Что означает ответ

Сбер вернул сводку по счёту за запрошенную дату. Ответ не резервирует сумму: остаток может измениться к моменту следующей операции.

Что делать дальше

Используйте closing_balance как остаток на счёте и на всех картах, выпущенных к нему.
Чтобы обновить данные, повторите запрос.

Пример ответа 400 (Bad Request)

{
  "errors": [
    {
      "code": 4,
      "message": "Ошибка получения баланса счета. Попробуйте позднее."
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки BAAS API».
`errors[].code`	integer	Код ошибки. В примере — `4`, ошибка зависимого сервиса.
`errors[].message`	string	Описание причины ошибки.

Что означает ответ

Баланс не получен. Возможные причины по message:

Ошибка получения баланса счета. Попробуйте позднее. — Сбер отклонил запрос или вернул ошибку;
Ошибка получения сессии: сессия не авторизована, требуется повторная авторизация — пользователь не завершил авторизацию в Сбер или сессия больше не действует;
другое сообщение, начинающееся с Ошибка получения сессии:, — не удалось обновить токен сессии.

Что делать дальше

Если сессия не авторизована или токен не удалось обновить, попросите пользователя повторно пройти авторизацию в Сбер и повторите запрос с новым session_id. Подпись пересчитайте.
Иначе проверьте, что account_number получен из списка карт этой же сессии, а date не в будущем и не старше пяти предыдущих лет. Повторите запрос позже.
Если ошибка повторяется для счёта из списка карт, попросите пользователя повторно пройти авторизацию в Сбер: при входе он должен открыть платформе доступ к этому счёту. Если и это не помогло, обратитесь в поддержку.

Пример ответа 401 (Unauthorized)

{
  "errors": [
    {
      "code": 4,
      "message": "Ошибка получения баланса счета: сессия не авторизована"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки BAAS API».
`errors[].code`	integer	Код ошибки: `4` — Сбер не принял авторизацию сессии, `11` — неверная подпись.
`errors[].message`	string	Описание причины ошибки.

Что означает ответ

При коде 4 Сбер отклонил токен сессии, и баланс не получен. При коде 11 запрос отклонён до обращения в Сбер: подпись не совпала.

Что делать дальше

При коде 4 попросите пользователя повторно пройти авторизацию в Сбер и повторите запрос с новым session_id. Подпись пересчитайте.
При коде 11 проверьте X-Api-Key, session_id, account_number, secret_key и порядок значений в подписи. Повторять запрос без исправления подписи не нужно.

Пример ответа 403 (Forbidden)

{
  "errors": [
    {
      "code": 42,
      "message": "Доступ запрещён"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки BAAS API».
`errors[].code`	integer	Код ошибки: `42` — сессия принадлежит другому Sber-профилю, `12` — магазину запрещён доступ к BAAS API.
`errors[].message`	string	Описание причины запрета доступа.

Что означает ответ

Запрос отклонён до обращения в Сбер, баланс не запрашивался.

Что делать дальше

При коде 42 проверьте, что session_id получен для этого магазина, и не используйте сессии другого магазина.
При коде 12 обратитесь к менеджеру KVELL, чтобы проверить статус магазина.

Пример ответа 404 (Not Found)

{
  "errors": [
    {
      "code": 4,
      "message": "Сессия не найдена"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки BAAS API».
`errors[].code`	integer	Код ошибки: `4` — сессия не найдена, `20` — магазин не найден, `43` — для магазина не настроен Sber-профиль.
`errors[].message`	string	Описание ресурса, который не найден.

Что означает ответ

Не найдена сессия, магазин или Sber-профиль. Баланс не запрашивался.

Что делать дальше

При коде 4 проверьте session_id. Если сессия не создавалась или утеряна, попросите пользователя пройти авторизацию в Сбер заново. Повтор с тем же session_id не поможет.
При коде 20 проверьте X-Api-Key и контур: Production или Stage.
При коде 43 обратитесь к менеджеру KVELL для настройки Sber-профиля.

Пример ответа 422 (Unprocessable Entity)

{
  "errors": [
    {
      "code": 0,
      "message": "String should match pattern '^[0-9]{20}$'",
      "field": "account_number"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок валидации. Коды и рекомендации приведены в разделе «Ошибки валидации».
`errors[].code`	integer	Код ошибки. Для ошибки поля — `0`. Для `session_id` не в формате UUID — `4`.
`errors[].message`	string	Причина ошибки валидации.
`errors[].field`	string	Параметр с некорректным значением: `account_number`, `date` или `session_id`. Возвращается для кода `0`.

Что означает ответ

Запрос не прошёл проверку формата или обязательных параметров. Баланс не запрашивался.

Что делать дальше

Исправьте параметр из field или message: номер счёта — 20 цифр, дата — в формате YYYY-MM-DD.
Если изменился session_id или account_number, пересчитайте подпись. Изменение date подпись не затрагивает.

Пример ответа 500 (Internal Server Error)

{
  "errors": [
    {
      "code": 1,
      "message": "Неизвестная ошибка"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Технические ошибки и отсутствие ответа».
`errors[].code`	integer	Код технической ошибки: `1` или `4`.
`errors[].message`	string	Описание технической ошибки.

Что означает ответ

Техническая ошибка на стороне KVELL. Метод только читает данные, поэтому ошибка не меняет остаток и не создаёт операций.

Что делать дальше

Безопасно повторите тот же запрос с теми же параметрами и подписью.
При повторяющейся ошибке обратитесь в поддержку и передайте URL, время запроса, X-Request-ID, HTTP-код, code и message.

Объект суммы

Все суммы в ответе передаются объектом:

Параметр	Тип	Описание
`amount`	string	Сумма в виде десятичного числа, например `"300000.00"`.
`currency_name`	string	Код валюты, например `RUB`.