api/wallet/get-balance - Получение баланса Кошелька

HTTP‑метод: POST
URL: /api/wallet/get-balance
Форма взаимодействия: Сервер-сервер
Формат тела запроса: application/json
Назначение: получение актуального баланса Кошелька.

URL

URLPATH

https://gateway-docs.wallet.kvell.group/api/wallet/get-balance

/api/wallet/get-balance

Структура запроса

Поле	Тип	Обяз.	Описание
`terminal`	`str`	✔	Уникальный идентификатор учетной записи ТСП в ПЦ.
`wallet_public_id`	`str`	✔	Уникальный идентификатор Кошелька.
`signature`	`str`	✔	Цифровая подпись запроса. Алгоритм расчёта — см. Формирование подписи.

Структура ответа

Поле	Тип	Обяз.	Описание
`wallet_public_id`	`str`	✔	Уникальный идентификатор Кошелька. Пример: `zzz`
`balance`	`int`	✔	Значение основного баланса (в минимальных единицах валюты, "в копейках"). Пример: `124209703`
`currency`	`int`		Код валюты по ISO4217. Пример: `643`
`is_active`	`bool \\| str`	✔	Статус Кошелька. Возможные значения: `ACTIVE`, `BLOCKED`. Пример: `ACTIVE`
`available_balance`	`int`		Значение доступного баланса (в минимальных единицах валюты, "в копейках"). Пример: `124209703`

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

Успех (200)Пример ошибки (404)

{
    "wallet_public_id": "zzz",
    "balance": 124209703,
    "currency": 643,
    "is_active": "ACTIVE",
    "available_balance": 124209703
}

{
    "error_code": "TERMINAL_NOT_FOUND",
    "technical_message": "Terminal not found",
    "timestamp": 1751976000,
    "details": null,
    "request_id": "b3b3c1f0-4b3a-4f3a-9b1a-1234567890ab"
}

Примечания

При получении запроса ПЦ проверяет:
Правильность расчета подписи и корректность параметров запроса;
Наличие wallet_public_id в запросе и принадлежность к указанному терминалу;
Если заданный wallet_public_id не найден в системе, то создается Кошелёк с нулевым балансом.
Поле available_balance в ответе всегда равно balance.
Поле is_active в исходной модели — булево (bool), но сериализуется в строку: True → "ACTIVE", False → "BLOCKED".