Лимиты корпоративной карты

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

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

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

URL

ProductionStage

GET https://api.baas.kvell.group/v1/sber/corporate-cards/{business_card_id}/limits

GET https://api.baas.stage.kvell.group/v1/sber/corporate-cards/{business_card_id}/limits

Запрос

Path-параметры

Параметр	Тип	Обязательно	Описание
`business_card_id`	string	Да	Идентификатор корпоративной карты в формате UUID. Возвращается в поле `business_card_id` метода списка корпоративных карт.

Query-параметры

Параметр	Тип	Обязательно	Описание
`session_id`	string	Да	Идентификатор авторизованной сессии Сбер в формате UUID. Сессия должна принадлежать Sber-профилю магазина, ключ которого передан в `X-Api-Key`.

Заголовки

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

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

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

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

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

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

Пример

curl --request GET \
  --url 'https://api.baas.stage.kvell.group/v1/sber/corporate-cards/1d192d78-7877-412a-a17b-cceaf5de1803/limits?session_id=11111111-1111-4111-8111-111111111111' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>'

Ответ

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

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

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

2004004014034044225XX

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

{
  "business_card_id": "1d192d78-7877-412a-a17b-cceaf5de1803",
  "cash_limits": {
    "day": {
      "max_value": "300000.00",
      "value": "300000.00",
      "rest_volume": "300000.00"
    },
    "month": {
      "max_value": "10000000.00",
      "value": "10000000.00",
      "rest_volume": "10000000.00"
    }
  },
  "transfer_limits": {
    "day": {
      "max_value": "300000.00",
      "value": "300000.00",
      "rest_volume": "300000.00"
    },
    "month": {
      "max_value": "5000000.00",
      "value": "5000000.00",
      "rest_volume": "4999667.00"
    }
  },
  "non_cash_limit": {
    "day": {
      "value": null,
      "rest_volume": null,
      "is_active": false
    }
  },
  "total_limits": {
    "month": {
      "value": null,
      "rest_volume": null,
      "is_active": false
    },
    "period": {
      "value": "1000000.00",
      "rest_volume": "400000.00",
      "is_active": true,
      "start_date": "2026-10-01T00:00:00.000Z",
      "end_date": "2026-12-31T23:59:59.000Z",
      "block_operations_after_period": false
    }
  }
}

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

Суммы передаются строками в том виде, в котором их возвращает Сбер, например "300000.00".

Параметр	Тип	Описание
`business_card_id`	string	Идентификатор корпоративной карты из запроса.
`cash_limits`	object	Лимиты на снятие наличных. Структура описана в разделе «Объект лимита».
`transfer_limits`	object	Лимиты на переводы. Структура описана в разделе «Объект лимита».
`non_cash_limit`	object \| null	Лимит на безналичные операции. `null`, если Сбер не вернул лимит.
`non_cash_limit.day`	object	Дневной лимит. Структура описана в разделе «Объект включаемого лимита».
`total_limits`	object \| null	Общие лимиты на расходные операции. `null`, если Сбер не вернул лимиты.
`total_limits.month`	object \| null	Месячный лимит. Структура описана в разделе «Объект включаемого лимита».
`total_limits.period`	object \| null	Лимит на сумму расходных операций за период. Содержит поля «Объекта включаемого лимита» и поля из раздела «Период действия лимита».

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

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

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

Используйте rest_volume нужного лимита как доступный остаток.
Для non_cash_limit и total_limits учитывайте лимит, только если is_active равен true.

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

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

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

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

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

Лимиты не получены. Возможные причины по message:

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

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

Если сессия не авторизована или токен не удалось обновить, попросите пользователя повторно пройти авторизацию в Сбер и повторите запрос с новым session_id. Подпись пересчитайте.
Иначе проверьте, что business_card_id получен из списка карт этой же сессии, и повторите запрос позже.
Если ошибка повторяется, обратитесь в поддержку.

Пример ответа 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, business_card_id, 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": "Field required",
      "field": "session_id"
    }
  ]
}

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

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

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

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

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

Исправьте параметр из field или message.
Если изменился session_id или business_card_id, пересчитайте подпись.

Пример ответа 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.

Объект лимита

Объекты cash_limits и transfer_limits содержат дневной и месячный лимиты:

Параметр	Тип	Описание
`day`	object	Дневной лимит.
`month`	object	Месячный лимит.

Каждый из них содержит поля:

Параметр	Тип	Описание
`max_value`	string	Максимальное значение, до которого можно установить лимит.
`value`	string	Установленное значение лимита.
`rest_volume`	string	Остаток лимита.

Объект включаемого лимита

Объекты non_cash_limit.day, total_limits.month и total_limits.period содержат поля:

Параметр	Тип	Описание
`value`	string \| null	Установленное значение лимита. `null`, если лимит не задан.
`rest_volume`	string \| null	Остаток лимита. `null`, если лимит не задан.
`is_active`	boolean	`true`, если лимит включён.

Период действия лимита

Объект total_limits.period дополнительно содержит поля:

Параметр	Тип	Описание
`start_date`	string	Дата и время начала периода в UTC по ISO 8601.
`end_date`	string	Дата и время окончания периода в UTC по ISO 8601.
`block_operations_after_period`	boolean	`true`, если после окончания периода операции по карте блокируются.