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

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

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

Назначение​

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

Metadata​

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

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

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

HTTP-контракт​

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

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

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
AgencyCompanyIdidentity claims (tenant_id)GuidДаRequired — граница периметраtenant isolation
ActorUserIdidentity claims (sub)GuidДаRequired — audit выдачи ссылкиaudit
JobIdroute {jobId}GuidДаRequired, непустой—

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

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

Алгоритм​

  1. Контекст и доступ. Операцию выполняет руководитель агентства; scope — организация (AgencyCompanyId из claims); требуется право wallet.team.view.
  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.

Acceptance criteria​

  • AC-1 (готовый файл). Given задача в Completed, файл в хранилище; When GET; Then 200, Status = Completed, DownloadUrl — ссылка с TTL 1 час; выдача зафиксирована audit-записью.
  • AC-2 (повторная выдача ссылки). Given прежняя ссылка истекла, файл жив; 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 задача упала; 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 (unknown статус клиент трактует как «в процессе»).
  • Logs: JobId, AgencyCompanyId, Status, факт выдачи ссылки (URL не логируется); metrics: wallet_statement_download_url_issued_total; traces: OTel, correlation через traceparent.
  • Скачивание файла — напрямую из объектного хранилища по подписанной ссылке (SLA API не зависит от размера файла, ADR-0041).

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

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

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