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

GET /api/v1/referral-rewards-exports/{jobId} — Статус выгрузки и ссылка на скачивание

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

Назначение​

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

Metadata​

ПолеЗначение
Сервис/контекстrewards
API areapartner
Feature groupreferral-rewards-exports
Статусdraft
Документdocs/06-services/rewards/api/partner/get-referral-rewards-export-job.md

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

ПроверкаЗначение
Actor typeUser (реферальный партнёр — свои задачи; Менеджер ПИН — все)
Auth policy / Permissionsrewards.referral.view-own или rewards.commission.view-all
Scope (RBAC)партнёр — своя задача (OwnerUserId = ActorUserId); Менеджер ПИН — любая задача выгрузки
Record-levelпартнёр видит только задачи, поставленные им самим; чужая задача невидима → 404
Tenant isolationне применяется (платформенная сущность)
Auditвыдача ссылки на скачивание — audit-запись ExportSensitive (актор, JobId, время выдачи URL)

Партнёр (rewards.referral.view-own без view-all) видит только собственные задачи выгрузки. Менеджер ПИН (rewards.commission.view-all) — любую задачу реферальной выгрузки.

HTTP-контракт​

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

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

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

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

Дом модели — README.md («Общие контрактные модели»). Особенности этого ответа: DownloadUrl заполняется только при Status = Completed и непросроченном файле — подписанная ссылка на объектное хранилище с TTL 1 час; в остальных статусах DownloadUrl = null. FailureCode заполняется только при Status = Failed (например, REWARDS_EXPORT_ROW_LIMIT_EXCEEDED).

Алгоритм​

  1. Контекст и доступ. Требуется rewards.referral.view-own или rewards.commission.view-all.
  2. Проверка входа и существования. JobId непустой; задача существует и доступна актору (партнёр — только своя OwnerUserId = ActorUserId; Менеджер ПИН — любая) — иначе REWARDS_EXPORT_JOB_NOT_FOUND (чужая задача партнёру не раскрывается).
  3. Проекция статуса. Возвращается текущее состояние задачи (Queued/Running/Completed/Failed/ Expired). Для Completed: если retention файла (7 дней) ещё не истёк — генерируется подписанная ссылка с TTL 1 час, DownloadUrl заполняется, пишется audit-запись выдачи; если файл уже удалён по retention — задача отдаётся как Expired, DownloadUrl = null.
  4. Результат. ReferralRewardsExportJobModel → 200. Клиент при Queued/Running повторяет опрос (рекомендованный интервал — 5–10 с); при Expired — ставит новую выгрузку (create-referral-rewards-export.md); при Failed — читает FailureCode и сужает фильтры.

Ошибки и failure modes​

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

КодHTTP statusУсловиеСообщениеRetry
REWARDS_EXPORT_JOB_NOT_FOUND404Задача не существует или недоступна актору (партнёр — чужая задача)«Выгрузка не найдена»no retry

Статус Failed самой задачи — не HTTP-ошибка: ответ 200 с Status = Failed и FailureCode (причины — create-referral-rewards-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 = REWARDS_EXPORT_ROW_LIMIT_EXCEEDED, DownloadUrl = null.
  • AC-6 (чужая задача — партнёр). Given партнёр (view-own) и JobId задачи другого партнёра; When GET; Then REWARDS_EXPORT_JOB_NOT_FOUND (404) — без раскрытия существования.
  • AC-7 (Менеджер ПИН видит любую). Given актор с view-all и JobId задачи любого партнёра; When GET; Then 200 со статусом задачи.

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

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

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

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

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