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

GET /api/v1/platform/receipts — Реестр актов поступления средств

Постраничный реестр актов поступления средств для финансового оператора ПИН: номера, застройщики, суммы, сходимость и статусы (Draft / Registered / Cancelled) с фильтрами по застройщику, статусу и периоду (domain/platform-receipt.md).

Назначение​

Финансовый оператор ПИН просматривает все акты платформы: черновики в работе (сверка с платёжками), зарегистрированные (финансовые документы) и отменённые — чтобы контролировать, по каким поступлениям гейт получения денег ещё не пройден. Feature group — receipts.

Metadata​

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

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

ПроверкаЗначение
Actor typeUser (финансовый оператор ПИН)
Auth policy / Permissionsrewards.receipts.manage
Scope (RBAC)платформа
Tenant isolationвне tenant-модели — платформенный реестр (ADR-0052); агентства и застройщики акты не видят
Auditread-sensitive (суммы поступлений): в trace — actor + фильтры + TotalCount; суммы не логируются

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/v1/platform/receipts
Success status200
Correlationсквозной trace через заголовок traceparent

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

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
DeveloperCompanyIdqueryGuid?Нетнепустой Guid, если задан—
StatusqueryPlatformReceiptStatus?Нетenum Draft/Registered/Cancelled—
CreatedFromqueryDateTimeOffset?Нетнижняя граница CreatedAt (включительно)—
CreatedToqueryDateTimeOffset?Нетверхняя граница CreatedAt (исключительно); > CreatedFrom, если обе заданы—
Page / PageSizequeryintНетpaging-конвенция — README.md (Page >= 1, PageSize 1..100)—

Модель ответа — постраничный список PlatformReceiptModel​

Постраничный ответ: Items (список PlatformReceiptModel), Page, PageSize, TotalCount (paging-конвенция — README.md). Проекция — дом create-platform-receipt.md («PlatformReceiptModel»).

Дельта проекции для списка: Items (позиции PlatformReceiptItemModel) отдаётся пустой коллекцией — дочерние platform_receipt_items в реестр не джойнятся; детализация состава — отдельным запросом одного акта (см. «Смежные операции»). ItemsTotal в списке вычисляется агрегатом по позициям (предпросмотр сходимости для Draft-строк реестра).

Алгоритм​

Тривиальное постраничное чтение: проверить право rewards.receipts.manage (иначе FORBIDDEN) и параметры фильтра (enum Status, CreatedTo > CreatedFrom, paging — иначе ValidationError); прочитать страницу актов по фильтрам DeveloperCompanyId / Status / границы CreatedAt с сортировкой CreatedAt DESC (свежие сверху; опорные индексы — ix_platform_receipts_developer, ix_platform_receipts_created_at); спроецировать в PlatformReceiptModel (Items = []) и вернуть 200. Чтение строго согласовано с записью: только что зарегистрированный акт сразу виден со статусом Registered.

Ошибки и failure modes​

Специфичных REWARDS_*-кодов у read-операции нет; общие коды (ValidationError 400 — Status вне enum, CreatedTo <= CreatedFrom, PageSize вне 1..100; FORBIDDEN 403; UNAUTHORIZED 401) — дом README.md «Общие ошибки».

Acceptance criteria​

  • AC-1 (реестр). Given есть акты в разных статусах по нескольким застройщикам; When оператор запрашивает список без фильтров; Then 200, акты по CreatedAt DESC, у каждого — Number, DeveloperCompanyId, Amount, ItemsTotal, ItemsCount, Status, даты переходов; Items = [].
  • AC-2 (фильтры). Given те же данные; When заданы DeveloperCompanyId и/или Status = Draft и/или границы CreatedFrom/CreatedTo; Then в выдаче только строки под все заданные условия (логическое И); CreatedFrom включителен, CreatedTo исключителен.
  • AC-3 (пустой результат). Given нет актов под фильтр или Page за последней страницей; Then 200, Items = [], корректный TotalCount (не 404).
  • AC-4 (детализация — отдельным запросом). Given строка реестра с ItemsCount = 12; When оператор открывает акт; Then позиции загружаются запросом одного акта (getPlatformReceipt, см. «Смежные операции»), в списке они не передаются.
  • AC-5 (валидация фильтра). Given Status вне enum или CreatedTo <= CreatedFrom; Then ValidationError (400).
  • AC-6 (доступ). Given актор без rewards.receipts.manage (в т.ч. руководитель агентства, менеджер застройщика); When запрос; Then FORBIDDEN (403) — акты видит только финансовый оператор ПИН; агентству/застройщику виден лишь эффект по своим начислениям (MoneyReceived, PlatformReceiptId).
  • AC-7 (свежесть). Given акт только что зарегистрирован; When сразу запрошен реестр; Then строка уже в статусе Registered (строгая согласованность чтения внутри rewards).

Смежные операции (тонкая дельта)​

  • getPlatformReceipt — GET /api/v1/platform/receipts/{receiptId} (rewards.receipts.manage): полная проекция одного акта с позициями (PlatformReceiptModel, Items заполнены — дом create-platform-receipt.md) и актуальным предпросмотром ItemsTotal; не найден → REWARDS_RECEIPT_NOT_FOUND (404). Используется для сверки состава перед регистрацией (register-platform-receipt.md).

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

  • PlatformReceiptModel — общая проекция области (дом create-platform-receipt.md): новые optional-поля — additive; удаление/ переименование/смена типа — breaking. Новые значения PlatformReceiptStatus — по unknown-enum-правилу.
  • Logs: фильтры (DeveloperCompanyId, Status, границы дат), TotalCount (суммы не логируются); metrics: rewards_api_request_duration_seconds{route}; traces: OTel, correlation через traceparent; dashboard rewards-overview.
  • НФТ (ADR-0056): актов — единицы в неделю на застройщика, реестр измеряется сотнями строк в год; выборка без джойна позиций; целевая латентность p95 < 250 мс; частота обращений низкая (back-office оператора).

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

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

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