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

GET /api/v1/my/wallet/statement-exports/{jobId} — Статус выписки и ссылка на скачивание

Опрос задачи XLSX-выписки, поставленной операцией create-wallet-statement-export.md: текущий статус жизненного цикла и — для завершённой задачи — короткоживущая подписанная ссылка на скачивание файла из приватного объектного хранилища (ADR-0041).

Назначение​

Пользователь-холдер после постановки выписки опрашивает её статус («готовится» → «готово») и получает ссылку на XLSX-файл. Ссылка живёт ограниченное время (1 час) — при истечении клиент повторяет запрос и получает новую, пока файл не удалён по retention. Feature group — my-wallet.

Metadata​

ПолеЗначение
Сервис/контекстwallet
API areauser
Feature groupmy-wallet
Статусdraft
Документdocs/06-services/wallet/api/user/get-wallet-statement-export-job.md

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

ПроверкаЗначение
Actor typeUser (агент / партнёр — холдер счёта)
Auth policy / Permissionswallet.transactions.view-own
Scope (RBAC)платформа (личные данные пользователя)
Record-levelзадача принадлежит текущему пользователю (UserId из claims); чужая задача невидима → 404
Auditвыдача ссылки на скачивание — audit-запись ExportSensitive (актор, JobId, время выдачи URL)

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/v1/my/wallet/statement-exports/{jobId}
Success status200
Idempotency headerне применяется (read; каждая выдача ссылки генерирует новый signed URL)
Correlationсквозной trace через заголовок traceparent

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

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
UserIdidentity claims (sub)GuidДаRequired — record-level границаrecord-level
JobIdroute {jobId}GuidДаRequired, непустой—

Модель ответа WalletStatementExportJobModel​

Дом модели — ../../reports/wallet-statement.md. Особенности ответа: DownloadUrl заполняется только при Status = Completed и непросроченном файле — подписанная ссылка с TTL 1 час; в остальных статусах DownloadUrl = null. FailureCode заполняется только при Status = Failed.

Алгоритм​

  1. Контекст и доступ. Операцию выполняет пользователь-холдер; scope — платформа; требуется право wallet.transactions.view-own.
  2. Проверка входа и существования. JobId непустой; задача существует и принадлежит текущему пользователю — иначе WALLET_STATEMENT_JOB_NOT_FOUND (чужая задача не раскрывается).
  3. Проекция статуса. Возвращается текущее состояние задачи (Queued/Running/Completed/Failed/ Expired). Для Completed: если retention файла (7 дней) не истёк — генерируется подписанная ссылка с TTL 1 час, DownloadUrl заполняется, пишется audit-запись выдачи; если файл удалён по retention — задача отдаётся как Expired, DownloadUrl = null.
  4. Результат. WalletStatementExportJobModel → 200. Клиент при Queued/Running повторяет опрос (рекомендованный интервал — 5–10 с); при Expired — ставит новую выписку; при Failed — читает FailureCode и сужает период.

Ошибки и failure modes​

Общие коды (ValidationError, FORBIDDEN, UNAUTHORIZED) — дом ../README.md «Общие ошибки». Дельта операции:

КодHTTP statusУсловиеСообщениеRetry
WALLET_STATEMENT_JOB_NOT_FOUND404Задача не существует или принадлежит другому пользователю«Выписка не найдена»no retry

Статус Failed самой задачи — не HTTP-ошибка: ответ 200 с Status = Failed и FailureCode (причины — create-wallet-statement-export.md, «Ошибки»).

Acceptance criteria​

  • AC-1 (готовый файл). Given задача в Completed, файл в хранилище (retention не истёк); When GET; Then 200, Status = Completed, DownloadUrl — подписанная ссылка с TTL 1 час; выдача зафиксирована audit-записью ExportSensitive.
  • AC-2 (повторная выдача ссылки). Given прежняя ссылка истекла (> 1 часа), файл ещё жив; When повторный GET; Then 200 с новой действующей ссылкой (каждая выдача — новый signed URL и новая audit-запись).
  • AC-3 (в процессе). Given задача Queued или Running; When GET; Then 200, соответствующий статус, DownloadUrl = null; клиент продолжает опрос.
  • AC-4 (retention истёк). Given с момента готовности файла прошло > 7 дней; When GET; Then 200, Status = Expired, DownloadUrl = null — клиент ставит новую выписку.
  • AC-5 (неуспех генерации). Given задача упала (превышен лимит 100 000 строк); When GET; Then 200, Status = Failed, FailureCode = WALLET_STATEMENT_ROW_LIMIT_EXCEEDED, DownloadUrl = null.
  • AC-6 (чужая задача). Given JobId задачи другого пользователя; When GET; Then WALLET_STATEMENT_JOB_NOT_FOUND (404) — без раскрытия существования.

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

  • Новые optional-поля модели задачи — additive; новые значения статуса — additive (unknown статус клиент трактует как «в процессе»).
  • Logs: JobId, UserId, Status, факт выдачи ссылки (сам URL не логируется); metrics: wallet_statement_download_url_issued_total; traces: OTel, correlation через traceparent.
  • Скачивание файла идёт напрямую из объектного хранилища по подписанной ссылке — минуя API wallet (SLA API не зависит от размера файла, ADR-0041).

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

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

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