Wallet API — реестр операций и общие контрактные модели
Индекс всех HTTP-операций контекста wallet и единственный дом общих контрактных моделей API
(балансы, транзакции, paging). Файлы операций описывают только свою дельту и ссылаются сюда. Дом полей
сущностей — ../domain/wallet-account.md и
../domain/ledger-transaction.md.
Все операции — read-only поверх счетов и журнала, кроме ручной корректировки (Adjustment) и
постановки асинхронных выгрузок-выписок (statement-exports — создают внутреннюю задачу выгрузки, не
меняют финансовое состояние; конвейер — ADR-0041).
wallet не порождает денежных обязательств: источник сумм — события rewards
(ADR-0065); API лишь
показывает проведённое состояние и допускает корректировку ПИН-админом.
Реестр операций (12)
User — мой кошелёк (my-wallet)
Agency — балансы команды (agency-wallet)
Общие контрактные модели
WalletBalanceModel (баланс счёта; проекция WalletAccountEntity — дом: ../domain/wallet-account.md)
| Поле | Тип | Обязательность | Источник | Описание |
|---|
AccountId | Guid | Да | WalletAccountEntity.Id | Идентификатор счёта. |
AccountKind | string (enum WalletAccountKind) | Да | AccountKind | Вид счёта: AgentCommission / ReferralCommission / AgencyCommission / PlatformSettlement / PlatformRevenue. |
Balance | decimal | Да | Balance (хранимый, сверяемый с журналом) | Текущий баланс; scale 2. У холдерских счетов >= 0; системные могут быть отрицательными (контрсчёт). |
CurrencyId | short | Да | CurrencyId | Валюта счёта — ссылка на справочник (handbook/domain/snapshots.md); RUB-only (ADR-0048). |
Счета создаются lazy — при первой кредитующей проводке; отсутствие счёта в ответе означает нулевой
баланс (проводок не было).
Подписи холдеров (HolderDisplayName). ФИО холдера-пользователя и название холдера-агентства в
ответах (my/wallet, agency/agent-balances, platform/accounts) резолвятся из локальной display-реплики
холдеров (../domain/user-display-replica.md, консюмер
../consumers/identity-users.md) — без синхронного вызова identity.
Реплика eventual: отсутствие строки → подпись null (клиент показывает id / имя из своего профиля), это не
ошибка. Ростер агентов агентства (agency/agent-balances) резолвится по той же реплике (CompanyId).
WalletTransactionModel (строка истории транзакций счёта; проекция журнала — дом: ../domain/ledger-transaction.md)
Строка истории — транзакция журнала в разрезе одного счёта (проекция проводки этого счёта).
| Поле | Тип | Обязательность | Источник | Описание |
|---|
TransactionId | Guid | Да | LedgerTransactionEntity.Id | Транзакция журнала. |
AccountId | Guid | Да | проводка (LedgerEntryEntity.AccountId) | Счёт, к которому относится строка. |
AccountKind | string (enum WalletAccountKind) | Да | счёт проводки | Вид счёта строки (различает историю при выборке по нескольким счетам). |
OperationKind | string (enum WalletOperationKind) | Да | OperationKind | CommissionCredit / ReferralCredit / PayoutDebit / Adjustment / Correction. |
Amount | decimal | Да | проводка счёта (Direction + Amount) | Сумма со знаком относительно счёта: положительная — Credit (баланс вырос), отрицательная — Debit; scale 2. |
BalanceAfter | decimal | Да | проводка счёта | Баланс счёта после применения транзакции (BalanceAfter проводки, фиксируется при проведении). |
CurrencyId | short | Да | счёт | Валюта сумм строки (handbook/domain/snapshots.md); RUB-only. |
SourceId | Guid | Да | SourceId | Ссылка-основание: id начисления / реферального начисления / позиции поручения / исходной транзакции (Correction) / ключ корректировки (Adjustment) — карта по видам операций в ../domain/ledger-transaction.md. |
OccurredAt | DateTimeOffset | Да | OccurredAt | Момент бизнес-факта операции (получение денег / выплата / корректировка). |
Paging (все list-операции)
| Поле | Источник | Тип | Ограничения |
|---|
Page | query | int | >= 1, default 1 |
PageSize | query | int | 1..100, default 20 |
Ответ — страница: Items : IReadOnlyList<TItem>, Page : int, PageSize : int, TotalCount : long.
Masking и безопасность (все операции)
| Правило | Значение |
|---|
| Балансы и суммы | Sensitive: в логи не пишутся (в logs — только AccountId/OperationKind/counts); доступ строго по permissions |
| Record-level | user-area — только счета с HolderUserId = текущий пользователь; agency-area — только AgentCommission-счета агентов своего агентства |
SourceId | Отдаётся как непрозрачная ссылка; расшифровка (начисление/поручение) — в rewards по своим permissions |
| Реквизиты | Банковские реквизиты в wallet отсутствуют (ADR-0065 п.5) |
Общие ошибки (все операции; коды не дублируются в файлах операций)
| Код | HTTP status | Условие |
|---|
ValidationError | 400 | Вход отклонён (формат/диапазоны/enum/paging) |
UNAUTHORIZED | 401 | Нет/просрочен JWT |
FORBIDDEN | 403 | Нет permission / чужой holder / чужой tenant |
Свежесть данных (общее для read-операций)
Балансы и история обновляются асинхронно consumer-ами событий rewards
(../consumers/rewards-commission-money-received.md,
../consumers/rewards-referral-accrual-status-changed.md,
../consumers/rewards-payout-order-status-changed.md):
после смены статуса в rewards баланс догоняет за секунды (окно eventual-consistency). В этом окне
пользователь может видеть статус «деньги получены» в rewards при ещё не пополненном балансе — это
штатно и не является рассинхроном (детекторы рассинхрона — ADR-0021).
Связанные документы