Перейти к основному содержимому

GET /api/v1/platform/wallet/accounts/{accountId}/ledger — Журнал проводок счёта

Назначение​

Отдаёт оператору ПИН постраничный журнал проводок произвольного счёта кошелька — холдерского (AgentCommission / ReferralCommission / AgencyCommission) или системного (PlatformSettlement / PlatformRevenue). В отличие от истории личного кошелька (../user/list-my-wallet-transactions.md), platform-журнал не ограничен холдером и раскрывает служебные атрибуты проводки: причину ручной операции (Adjustment) или отмены (Correction), актора ручной операции, направление и баланс-после. Рабочий инструмент финансового контроля: разбор инцидентов рассинхрона (ADR-0021), проверка счёта перед корректировкой (create-wallet-adjustment.md) и после неё, аудит движения средств по системным счетам.

Metadata​

ПолеЗначение
Сервис/контекстwallet
API areaplatform
Feature groupplatform-wallet
Статусdraft
Документdocs/06-services/wallet/api/platform/list-account-ledger.md

Актор и доступ​

ПроверкаЗначение
Actor typeOperator(Admin) (оператор ПИН)
Auth policy / Permissionswallet.accounts.view-all
Scope (RBAC)платформа
Record-levelнет — оператор видит журнал любого счёта, включая системные
Auditread-sensitive: обращения к журналу логируются (актор, AccountId, фильтры — без сумм)

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/v1/platform/wallet/accounts/{accountId}/ledger
Success status200
Correlationсквозной trace через заголовок traceparent

Входные данные / параметры запроса​

ПолеИсточникТипОбязательностьВалидация / Ограничения
AccountIdrouteGuidДасчёт журнала; несуществующий → WALLET_ACCOUNT_NOT_FOUND
OperationKindquerystring? (enum WalletOperationKind)Нетфильтр по виду операции (../../domain/ledger-transaction.md); не указан — все виды
FromqueryDateTimeOffset?Нетфильтр по OccurredAt >= From
ToqueryDateTimeOffset?Нетфильтр по OccurredAt < To; при обеих границах From < To
Page / PageSizequeryintНетpaging — ../README.md

Модель ответа WalletLedgerEntryModel (страница)​

Строка журнала — проводка данного счёта (LedgerEntryEntity) вместе с атрибутами её транзакции (LedgerTransactionEntity — дом полей: ../../domain/ledger-transaction.md). В отличие от WalletTransactionModel (../README.md), дебет и кредит разнесены по отдельным полям (бухгалтерский вид), а причина и актор раскрыты — только для platform-area.

ПолеТипОбязательностьИсточникОписание
EntryIdGuidДаLedgerEntryEntity.IdИдентификатор проводки.
TransactionIdGuidДаLedgerTransactionEntity.IdТранзакция журнала (одна транзакция может дать несколько проводок; в журнале счёта видна только его проводка).
OperationKindstring (enum WalletOperationKind)ДаOperationKindCommissionCredit / ReferralCredit / PayoutDebit / Adjustment / Correction.
SourceIdGuidДаSourceIdСсылка-основание («источник-сделка»): id начисления / реферального начисления / позиции поручения / исходной транзакции (Correction) / ключ корректировки (Adjustment) — карта по видам операций в ../../domain/ledger-transaction.md. Отдаётся как непрозрачная ссылка; расшифровка основания — в rewards по своим permissions.
Debitdecimal?Нет (null, если проводка — Credit)проводка счётаСумма списания со счёта (Direction = Debit); scale 2, всегда > 0.
Creditdecimal?Нет (null, если проводка — Debit)проводка счётаСумма зачисления на счёт (Direction = Credit); scale 2, всегда > 0. Ровно одно из Debit/Credit заполнено.
BalanceAfterdecimalДаLedgerEntryEntity.BalanceAfterСальдо счёта сразу после проводки (зафиксировано при проведении); scale 2.
CurrencyIdshortДасчётВалюта сумм строки (handbook/domain/snapshots.md); RUB-only (ADR-0048).
Commentstring?Нет (null, кроме Adjustment/Correction)LedgerTransactionEntity.CommentПричина ручной операции (Reason оператора у Adjustment) или отмены источника (CancelReason у Correction).
ActorUserIdGuid?Нет (null у системных операций)ActorUserIdПИН-оператор, выполнивший ручную операцию (Adjustment).
CorrectedTransactionIdGuid?Нет (null, кроме Correction)CorrectedTransactionIdКомпенсируемая исходная транзакция (у Correction).
OccurredAtDateTimeOffsetДаOccurredAtМомент бизнес-факта операции (получение денег / выплата / корректировка).
RecordedAtDateTimeOffsetДаRecordedAtМомент проведения в журнале.

Сортировка — RecordedAt по убыванию (свежие сверху); внутри одинакового момента — по EntryId (стабильный порядок страниц).

Алгоритм​

  1. Проверить permission и существование счёта: счёта нет → WALLET_ACCOUNT_NOT_FOUND (404).
  2. Проверить фильтры: OperationKind вне enum / From >= To / paging вне диапазонов → ValidationError.
  3. Выбрать проводки этого счёта из журнала по фильтру периода и вида операции, присоединить атрибуты их транзакций (OperationKind, SourceId, Comment, ActorUserId, CorrectedTransactionId, OccurredAt, RecordedAt), спроецировать в WalletLedgerEntryModel (Debit/Credit по Direction, BalanceAfter — зафиксированный при проведении) и вернуть страницу.
  4. Журнал append-only (../../domain/ledger-transaction.md, INV-WLT-6): история не меняется задним числом; исправления видны отдельными строками Correction/Adjustment, а не правкой прежних проводок.

Ошибки и failure modes​

КодHTTPУсловие
WALLET_ACCOUNT_NOT_FOUND404Счёта с указанным AccountId не существует.

Прочее — общие ошибки области (../README.md): ValidationError (400), UNAUTHORIZED (401), FORBIDDEN (403).

Совместимость и наблюдаемость​

  • Новые значения WalletOperationKind и optional-поля модели — additive: клиент показывает неизвестный вид операции как «прочее», не падая.
  • Logs: актор, AccountId, фильтры без сумм; metrics: латентность p95, частота обращений к журналу (wallet_platform_ledger_reads_total); traces — traceparent.

Обратные ссылки​

Автоссылки: где используется этот документ.

Связанные документы​