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

Rewards API — реестр операций и общие контрактные модели

Индекс всех HTTP-операций контекста rewards и единственный дом общих контрактных моделей API (деньги, условия правил, проекции начислений/поручений, сводки, paging). Файлы операций описывают только свою дельту и ссылаются сюда. Дом полей сущностей — ../domain/*.md.

Metadata​

ПолеЗначение
Сервис/контекстrewards (greenfield)
Статусdraft
Owning teamPIN Platform (backend)
Область действияAPI areas: developer-admin (правила, подтверждение начислений), agency (политика, поручения, сводки, per-deal корректировки, Excel-выгрузки), agent (мои комиссии + личная user-centric статистика, ADR-0061 п.5), partner (мои реферальные начисления, Excel-выгрузки реферальных вознаграждений — свои/все по permission), platform (условия платформы, реферальные ставки, акты поступления, корректировки, реферальные поручения — Менеджер/оператор ПИН), internal (расчёт комиссии для catalog)
AssumptionsКонверт ответа/ошибок — общий для платформы, дом — identity/api/README.md «Общий конверт ответа»; permissions — каталог ../../identity/domain/permission.md
Зависимости../README.md, ../domain/reward-rule.md, ../domain/commission-accrual.md, ../domain/agency-commission-policy.md, ../domain/payout-order.md, ../domain/platform-commission-terms.md, ../domain/referral-rate-rule.md, ../domain/referral-accrual.md, ../domain/platform-receipt.md

Реестр операций (64)​

Developer-admin — правила вознаграждений (rules)​

#ОперацияHTTPRoutePermissionДокумент
1listRewardRulesGET/api/v1/reward-rulesrewards.rules.viewlist-reward-rules.md
2getRewardRuleGET/api/v1/reward-rules/{ruleId}rewards.rules.viewget-reward-rule.md
3createRewardRulePOST/api/v1/reward-rulesrewards.rules.managecreate-reward-rule.md
4updateRewardRulePUT/api/v1/reward-rules/{ruleId}rewards.rules.manageupdate-reward-rule.md
5activateRewardRulePOST/api/v1/reward-rules/{ruleId}/activaterewards.rules.manageactivate-reward-rule.md
6deactivateRewardRulePOST/api/v1/reward-rules/{ruleId}/deactivaterewards.rules.managedeactivate-reward-rule.md
7archiveRewardRulePOST/api/v1/reward-rules/{ruleId}/archiverewards.rules.managearchive-reward-rule.md
8testRewardRuleCalculationPOST/api/v1/reward-rules/test-calculationrewards.rules.viewtest-reward-rule-calculation.md

Developer-admin — начисления (developer-accruals)​

#ОперацияHTTPRoutePermissionДокумент
9listDeveloperAccrualsGET/api/v1/developer/commission-accrualsrewards.accruals.confirmlist-developer-accruals.md
10confirmCommissionAccrualPOST/api/v1/developer/commission-accruals/{accrualId}/confirmrewards.accruals.confirmconfirm-commission-accrual.md
11rejectCommissionAccrualPOST/api/v1/developer/commission-accruals/{accrualId}/rejectrewards.accruals.confirmreject-commission-accrual.md
12createManualAccrualPOST/api/v1/developer/commission-accrualsrewards.accruals.managecreate-manual-accrual.md

Agency — комиссионная политика (agency-policy)​

#ОперацияHTTPRoutePermissionДокумент
13listAgencyPoliciesGET/api/v1/agency/commission-policiesrewards.commission-policy.viewlist-agency-policies.md
14createAgencyPolicyPOST/api/v1/agency/commission-policiesrewards.commission-policy.managecreate-agency-policy.md
15updateAgencyPolicyPUT/api/v1/agency/commission-policies/{policyId}rewards.commission-policy.manageupdate-agency-policy.md
16activateAgencyPolicyPOST/api/v1/agency/commission-policies/{policyId}/activaterewards.commission-policy.manageactivate-agency-policy.md
17archiveAgencyPolicyPOST/api/v1/agency/commission-policies/{policyId}/archiverewards.commission-policy.managearchive-agency-policy.md

Agency — boost-кампании агентов (agent-boost)​

#ОперацияHTTPRoutePermissionДокумент
57listAgentBoostCampaignsGET/api/v1/agency/agent-boost-campaignsrewards.commission-policy.viewlist-agent-boost-campaigns.md
58createAgentBoostCampaignPOST/api/v1/agency/agent-boost-campaignsrewards.commission-policy.managecreate-agent-boost-campaign.md
59activateAgentBoostCampaignPOST/api/v1/agency/agent-boost-campaigns/{campaignId}/activaterewards.commission-policy.manageactivate-agent-boost-campaign.md
60archiveAgentBoostCampaignPOST/api/v1/agency/agent-boost-campaigns/{campaignId}/archiverewards.commission-policy.managearchive-agent-boost-campaign.md

Agency — начисления и сводки (agency-commission)​

#ОперацияHTTPRoutePermissionДокумент
18listAgencyAccrualsGET/api/v1/agency/commission-accrualsrewards.commission.view-alllist-agency-accruals.md
19getAgencyCommissionSummaryGET/api/v1/agency/commission-summaryrewards.commission.view-allget-agency-commission-summary.md
20getAgentCommissionSummaryGET/api/v1/agency/agents/{agentUserId}/commission-summaryrewards.commission.view-allget-agent-commission-summary.md
33adjustAccrualDistributionPOST/api/v1/agency/commission-accruals/{accrualId}/adjust-distributionrewards.commission-policy.manageadjust-accrual-distribution.md
64resolveDistributionAdjustmentRequestPOST/api/v1/agency/commission-adjustment-requests/{requestId}/resolverewards.commission.adjust-approveapprove-distribution-adjustment.md

Agency — Excel-выгрузки (rewards-exports)​

#ОперацияHTTPRoutePermissionДокумент
34createRewardsExportPOST/api/v1/agency/rewards-exportsrewards.commission.view-allcreate-rewards-export.md
35getRewardsExportJobGET/api/v1/agency/rewards-exports/{jobId}rewards.commission.view-allget-rewards-export-job.md

Agency — платёжные поручения и история выплат (payouts)​

#ОперацияHTTPRoutePermissionДокумент
21createPayoutOrderPOST/api/v1/agency/payout-ordersrewards.payouts.managecreate-payout-order.md
22listPayoutOrdersGET/api/v1/agency/payout-ordersrewards.payouts.managelist-payout-orders.md
23updatePayoutOrderItemsPUT/api/v1/agency/payout-orders/{orderId}/itemsrewards.payouts.manageupdate-payout-order-items.md
24approvePayoutOrderPOST/api/v1/agency/payout-orders/{orderId}/approverewards.payouts.approveapprove-payout-order.md
25markPayoutOrderPaidPOST/api/v1/agency/payout-orders/{orderId}/mark-paidrewards.payouts.approvemark-payout-order-paid.md
26rejectPayoutOrderPOST/api/v1/agency/payout-orders/{orderId}/rejectrewards.payouts.approvereject-payout-order.md
27cancelPayoutOrderPOST/api/v1/agency/payout-orders/{orderId}/cancelrewards.payouts.managecancel-payout-order.md

Agent — мои комиссии (my-commission)​

#ОперацияHTTPRoutePermissionДокумент
28listMyAccrualsGET/api/v1/my/commission-accrualsrewards.commission.view-ownlist-my-accruals.md
29getMyCommissionSummaryGET/api/v1/my/commission-summaryrewards.commission.view-ownget-my-commission-summary.md
30listMyPayoutsGET/api/v1/my/payoutsrewards.payouts.view-ownlist-my-payouts.md
32getMyAgentPerformanceGET/api/v1/my/agent-performancerewards.performance.view-ownget-my-agent-performance.md
63requestDistributionAdjustmentPOST/api/v1/my/commission-accruals/{accrualId}/adjustment-requestsrewards.commission.adjust-requestrequest-distribution-adjustment.md

Partner — мои реферальные начисления (my-referral)​

#ОперацияHTTPRoutePermissionДокумент
36listMyReferralAccrualsGET/api/v1/my/referral-accrualsrewards.referral.view-ownlist-my-referral-accruals.md

Partner — реферальные выгрузки (referral-rewards-exports)​

Область выборки (own/all) разрешается по permission актора: партнёр (rewards.referral.view-own) — только свои начисления; Менеджер ПИН (rewards.commission.view-all) — все.

#ОперацияHTTPRoutePermissionДокумент
61createReferralRewardsExportPOST/api/v1/referral-rewards-exportsrewards.referral.view-own / rewards.commission.view-allcreate-referral-rewards-export.md
62getReferralRewardsExportJobGET/api/v1/referral-rewards-exports/{jobId}rewards.referral.view-own / rewards.commission.view-allget-referral-rewards-export-job.md

Platform — условия платформенной комиссии (platform-terms, Менеджер ПИН)​

#ОперацияHTTPRoutePermissionДокумент
37listPlatformTermsGET/api/v1/platform/commission-termsrewards.platform-terms.viewplatform/list-platform-terms.md
38createPlatformTermsPOST/api/v1/platform/commission-termsrewards.platform-terms.manageplatform/create-platform-terms.md
39updatePlatformTermsPUT/api/v1/platform/commission-terms/{termsId}rewards.platform-terms.manageplatform/update-platform-terms.md
40activatePlatformTermsPOST/api/v1/platform/commission-terms/{termsId}/activaterewards.platform-terms.manageplatform/activate-platform-terms.md
41archivePlatformTermsPOST/api/v1/platform/commission-terms/{termsId}/archiverewards.platform-terms.manageplatform/archive-platform-terms.md

Platform — реферальные ставки (referral-rates, Менеджер ПИН)​

#ОперацияHTTPRoutePermissionДокумент
42listReferralRateRulesGET/api/v1/platform/referral-rate-rulesrewards.referral-rates.manageplatform/list-referral-rate-rules.md
43createReferralRateRulePOST/api/v1/platform/referral-rate-rulesrewards.referral-rates.manageplatform/create-referral-rate-rule.md
44updateReferralRateRulePUT/api/v1/platform/referral-rate-rules/{ruleId}rewards.referral-rates.manageplatform/update-referral-rate-rule.md
45activateReferralRateRulePOST/api/v1/platform/referral-rate-rules/{ruleId}/activaterewards.referral-rates.manageplatform/activate-referral-rate-rule.md
46archiveReferralRateRulePOST/api/v1/platform/referral-rate-rules/{ruleId}/archiverewards.referral-rates.manageplatform/archive-referral-rate-rule.md

Platform — акты поступления средств (platform-receipts, финансовый оператор ПИН)​

#ОперацияHTTPRoutePermissionДокумент
47createPlatformReceiptPOST/api/v1/platform/receiptsrewards.receipts.manageplatform/create-platform-receipt.md
48registerPlatformReceiptPOST/api/v1/platform/receipts/{receiptId}/registerrewards.receipts.manageplatform/register-platform-receipt.md
49listPlatformReceiptsGET/api/v1/platform/receiptsrewards.receipts.manageplatform/list-platform-receipts.md

Platform — корректировки и реферальные начисления (platform-accruals)​

#ОперацияHTTPRoutePermissionДокумент
50adjustCommissionAccrualPOST/api/v1/platform/commission-accruals/{accrualId}/adjustrewards.accruals.adjustplatform/adjust-commission-accrual.md
51listReferralAccrualsGET/api/v1/platform/referral-accrualsrewards.accruals.manageplatform/list-referral-accruals.md
52cancelReferralAccrualPOST/api/v1/platform/referral-accruals/{accrualId}/cancelrewards.accruals.manageplatform/cancel-referral-accrual.md
57adjustReferralAccrualPOST/api/v1/platform/referral-accruals/{accrualId}/adjustrewards.referral-rates.manage / rewards.accruals.adjustplatform/adjust-referral-accrual.md

Platform — реферальные платёжные поручения (referral-payouts, tenant — ПИН)​

#ОперацияHTTPRoutePermissionДокумент
53createReferralPayoutOrderPOST/api/v1/platform/referral-payout-ordersrewards.payouts.manageplatform/create-referral-payout-order.md
54listReferralPayoutOrdersGET/api/v1/platform/referral-payout-ordersrewards.payouts.manageplatform/list-referral-payout-orders.md
55approveReferralPayoutOrderPOST/api/v1/platform/referral-payout-orders/{orderId}/approverewards.payouts.approveplatform/approve-referral-payout-order.md
56markReferralPayoutOrderPaidPOST/api/v1/platform/referral-payout-orders/{orderId}/mark-paidrewards.payouts.approveplatform/mark-referral-payout-order-paid.md

Internal — s2s для catalog (internal-commission)​

#ОперацияHTTPRouteAuthДокумент
31calculatePropertyObjectCommissionPOST/internal/v1/commission/calculate-property-objectm2m audience pin.rewards.internalcalculate-property-object-commission.md

Общие контрактные модели​

MoneyModel (проекция VO Money — дом: ../domain/commission-accrual.md)​

ПолеТипОбязательностьОграниченияОписание
ValuedecimalДа>= 0, scale 2 (numeric(18,2))Сумма.
CurrencyIdshortДассылка на валюту справочника; допустимость валют — RUB-only (ADR-0048)Типизированная ссылка на валюту. Display-код/знак клиент берёт из справочника (../../handbook/api/public/lookup-references.md); в payload событий деньги идут как Value + CurrencyId + CurrencySnapshot (../../handbook/domain/snapshots.md).

RewardRuleConditionsModel (проекция RewardRuleConditionsDocument — дом: ../domain/reward-rule.md)​

Семантика «null/пусто = любое значение», логическое И между измерениями — как в доме. ContractVersion jsonb-документа наружу не отдаётся (внутренняя версия хранения).

Ось каталога (специфичность по убыванию): ProjectIds (ЖК, наименее специфично) → LayoutGroupIds (группа планировок) → LayoutIds (планировка, наиболее специфично). Предикаты PropertyTypes/ RoomsRange/AreaRangeM2 — дополнительные фильтры совпадения (на уровень специфичности не влияют).

ПолеТипОбязательностьОграничения
PropertyTypesIReadOnlyList<PropertyType>Нет (пусто = any)значения Apartment/Parking/Commercial, уникальны, ≤ 3
ProjectIdsIReadOnlyList<Guid>Нет (пусто = any)уникальны, ≤ 200; ось каталога — ЖК (наименее специфичное измерение)
LayoutGroupIdsIReadOnlyList<Guid>Нет (пусто = any)уникальны, ≤ 200; ось каталога — группа планировок (средняя специфичность)
LayoutIdsIReadOnlyList<Guid>Нет (пусто = any)уникальны, ≤ 500; ось каталога — планировка (наиболее специфичное измерение)
RoomsRangeNullableRange<int>Нетграницы Min/Max в 0..20, Min <= Max
AreaRangeM2NullableRange<decimal>Нетграницы Min/Max в (0; 10000], scale 2, Min <= Max

RewardRuleModel (полная проекция RewardRuleEntity)​

ПолеТипОбязательностьИсточник
IdGuidДаRewardRuleEntity.Id
NamestringДаName
Descriptionstring?НетDescription
Statusstring (enum RewardRuleStatus)ДаStatus: Draft/Active/Archived
CalculationBasestring (enum CommissionCalculationBase)ДаCalculationBase: BasePrice/FinalPrice
CommissionPercentdecimalДаCommissionPercent (0 < x <= 100, scale 2)
PriorityintДаPriority (0..100000)
EffectiveFromDateTimeOffset?НетEffectiveFrom
EffectiveToDateTimeOffset?НетEffectiveTo
ConditionsRewardRuleConditionsModelДаConditions (jsonb)
CreatedAtDateTimeOffsetДаCreatedAt
UpdatedAtDateTimeOffsetДаUpdatedAt
VersionlongДаVersion — используется как ExpectedVersion в мутациях (optimistic concurrency)

CommissionDistributionModel (проекция CommissionDistributionEntity; отдаётся только agency-area)​

ПолеТипОбязательностьИсточник
IdGuidДаCommissionDistributionEntity.Id
RecipientTypestring (enum CommissionRecipientType)ДаRecipientType: Platform/Agent/Agency (три строки — INV-9, ADR-0066)
RecipientUserIdGuid?Да для Agent, null для Platform/AgencyRecipientUserId
AmountMoneyModelДаAmount
AppliedRetentionKindstring? (enum AgencyRetentionKind)Только у строки AgencyAppliedRetentionKind: Percent/FixedAmount/AgentPercentOfPool/AgentPercentOfPrice (форма применённого правила распределения пула)
AppliedBoostCampaignIdGuid?Только у строки Agency, если применён активный boostAppliedBoostCampaignId (снапшот применённой boost-кампании; null — применялось базовое правило политики)
PayoutOrderItemIdGuid?Нет (только строки Agent)PayoutOrderItemId (null = не включена в поручение)
PaidAtDateTimeOffset?НетPaidAt

CommissionAccrualModel (полная проекция CommissionAccrualEntity; masking по area — см. Masking-правила)​

ПолеТипОбязательностьИсточник
IdGuidДаCommissionAccrualEntity.Id
DealIdGuidДаDealId
DeveloperCompanyIdGuidДаDeveloperCompanyId
AgencyCompanyIdGuidДаTenantId
AgentUserIdGuidДаAgentUserId
PropertyObjectIdGuidДаPropertyObjectId
DealCompletedAtDateTimeOffsetДаDealCompletedAt
CalculationBasestring (enum CommissionCalculationBase)ДаCalculationBase
CommissionPercentdecimalДаCommissionPercent
BasePriceAmountMoneyModelДаBasePriceAmount
FinalPriceAmountMoneyModelДаFinalPriceAmount
CommissionAmountMoneyModelДаCommissionAmount (итоговая сумма — после корректировок gross, INV-11)
OriginalCommissionAmountMoneyModel?Нет (null — сумма не корректировалась)OriginalCommissionAmount
PlatformRetentionPercentagePointsdecimalДаPlatformRetentionPercentagePoints (снапшот условий платформы; 0 — fallback, ADR-0066)
PlatformFeeAmountMoneyModelДаPlatformFeeAmount (удержание ПИН; пул агентства = CommissionAmount − PlatformFeeAmount)
AppliedRuleAppliedRuleRefModelДавложенная ref-модель применённого правила (id + имя); дом — ниже
AppliedPolicyIdGuid?НетAppliedPolicyId
Statusstring (enum CommissionAccrualStatus)ДаStatus: PendingConfirmation/Confirmed/MoneyReceived/Paid/Cancelled
ConfirmedAtDateTimeOffset?НетConfirmedAt
MoneyReceivedAtDateTimeOffset?НетMoneyReceivedAt (регистрация акта поступления — гейт ADR-0067)
PlatformReceiptIdGuid?НетPlatformReceiptId (акт, подтвердивший получение денег; агентству виден эффект гейта — ../domain/platform-receipt.md)
PaidAtDateTimeOffset?НетPaidAt
CancelledAtDateTimeOffset?НетCancelledAt
CancelReasonstring? (enum CommissionCancelReason)НетCancelReason
DistributionsIReadOnlyList<CommissionDistributionModel>Да (пусто до Confirmed; с Confirmed — три строки Platform/Agency/Agent)child-коллекция; только agency-area
AdjustmentsIReadOnlyList<AdjustmentModel>Да (может быть пустым)child-коллекция аудита корректировок; только agency-area
CreatedAtDateTimeOffsetДаCreatedAt
VersionlongДаVersion

AppliedRuleRefModel (ref-модель применённого правила; вложена в CommissionAccrualModel)​

ПолеТипОбязательностьИсточник
RuleIdGuid?Нет (null — ручное начисление)AppliedRuleId
RuleNamestringДаAppliedRuleSnapshot.RuleName ("manual" для ручных)

PayoutOrderItemModel (проекция PayoutOrderItemEntity)​

ПолеТипОбязательностьИсточник
IdGuidДаPayoutOrderItemEntity.Id
RecipientUserIdGuidДаRecipientUserId — агент (AgencyCommission) / реферальный партнёр (ReferralReward)
AmountMoneyModelДаAmount
DistributionsCountintДаDistributionsCount
PaidAtDateTimeOffset?НетPaidAt

PayoutOrderModel (полная проекция PayoutOrderEntity)​

ПолеТипОбязательностьИсточник
IdGuidДаPayoutOrderEntity.Id
Kindstring (enum PayoutOrderKind)ДаKind: AgencyCommission/ReferralReward (../domain/payout-order.md)
NumberstringДаNumber (PO-{yyyy}-{seq})
Titlestring?НетTitle
PeriodFromDateTimeOffsetДаPeriodFrom
PeriodToDateTimeOffsetДаPeriodTo
Statusstring (enum PayoutOrderStatus)ДаStatus: Draft/PendingPayment/Paid/Rejected/Cancelled
TotalAmountMoneyModelДаTotalAmount
ItemsCountintДаItemsCount
ApprovedAtDateTimeOffset?НетApprovedAt
PaidAtDateTimeOffset?НетPaidAt
RejectedAtDateTimeOffset?НетRejectedAt
RejectReasonstring?НетRejectReason
CancelledAtDateTimeOffset?НетCancelledAt
CreatedAtDateTimeOffsetДаCreatedAt
VersionlongДаVersion
ItemsIReadOnlyList<PayoutOrderItemModel>Даchild-коллекция (в списках может отдаваться пустой — см. документ операции)

AdjustmentModel (проекция CommissionAccrualAdjustmentEntity — дом: ../domain/commission-accrual.md)​

ПолеТипОбязательностьИсточник
IdGuidДаCommissionAccrualAdjustmentEntity.Id
Kindstring (enum CommissionAdjustmentKind)ДаKind: GrossAmount/Distribution
OldAmountMoneyModelДаOldAmount (для GrossAmount — комиссия, для Distribution — доля агента до правки)
NewAmountMoneyModelДаNewAmount (та же семантика)
ReasonstringДаReason (обязательная причина, INV-11)
ActorUserIdGuidДаActorUserId
CreatedAtDateTimeOffsetДаCreatedAt

CommissionAdjustmentRequestModel (проекция CommissionAdjustmentRequestEntity — дом: ../domain/commission-accrual.md)​

Заявка агента на корректировку своей доли (схема «агент запрашивает → руководитель одобряет», INV-12). Отдаётся агенту-заявителю (только свои заявки, record-level RequestedByAgentUserId) и agency-area (руководителю — все заявки tenant-а).

ПолеТипОбязательностьИсточник
IdGuidДаCommissionAdjustmentRequestEntity.Id
AccrualIdGuidДаAccrualId
RequestedByAgentUserIdGuidДаRequestedByAgentUserId
ProposedAgentAmountMoneyModelДаProposedAgentAmount (предлагаемая доля Agent-строки)
ReasonstringДаReason (обязательное обоснование заявителя)
Statusstring (enum CommissionAdjustmentRequestStatus)ДаStatus: Pending/Approved/Rejected
ResolvedByUserIdGuid?Нет (заполняется при разрешении)ResolvedByUserId (руководитель)
ResolvedAtDateTimeOffset?НетResolvedAt
ResolutionCommentstring?Нет (обязателен при Rejected)ResolutionComment
AppliedAdjustmentIdGuid?Нет (заполняется при Approved)AppliedAdjustmentId (id аудит-строки Distribution)
CreatedAtDateTimeOffsetДаCreatedAt

PlatformTermsModel (полная проекция PlatformCommissionTermsEntity — дом: ../domain/platform-commission-terms.md; только platform-area)​

ПолеТипОбязательностьИсточник
IdGuidДаPlatformCommissionTermsEntity.Id
AgencyCompanyIdGuid?Нет (null = глобальный дефолт)AgencyCompanyId
RetentionPercentagePointsdecimalДаRetentionPercentagePoints (0.25..1.50, scale 2, INV-PT-1)
Commentstring?НетComment
Statusstring (enum PlatformCommissionTermsStatus)ДаStatus: Draft/Active/Archived
ActivatedAtDateTimeOffset?НетActivatedAt (начало интервала asOf-резолюции)
ArchivedAtDateTimeOffset?НетArchivedAt (конец интервала, исключительно)
CreatedAt / UpdatedAtDateTimeOffsetДаaudit-поля
VersionlongДаVersion — ExpectedVersion мутаций

ReferralRateRuleModel (полная проекция ReferralRateRuleEntity — дом: ../domain/referral-rate-rule.md; только platform-area)​

ПолеТипОбязательностьИсточник
IdGuidДаReferralRateRuleEntity.Id
PartnerUserIdGuid?Нет (null = любой партнёр)PartnerUserId
DeveloperCompanyIdGuid?Нет (null = любой застройщик)DeveloperCompanyId
Scopestring (enum ReferralRateScope)Даcomputed из заполненности измерений: PartnerDeveloper/Partner/Developer/Global
PercentdecimalДаPercent (0 < x <= 100, scale 2, INV-RR-1)
EffectiveFromDateTimeOffsetДаEffectiveFrom
EffectiveToDateTimeOffset?Нет (null = бессрочно)EffectiveTo
Commentstring?НетComment
Statusstring (enum ReferralRateRuleStatus)ДаStatus: Draft/Active/Archived
CreatedAt / UpdatedAtDateTimeOffsetДаaudit-поля
VersionlongДаVersion

ReferralAccrualModel (проекция ReferralAccrualEntity — дом: ../domain/referral-accrual.md; platform-area и partner-area с masking)​

ПолеТипОбязательностьИсточник
IdGuidДаReferralAccrualEntity.Id
DealIdGuidДаDealId
BondIdGuidДаBondId (реферальная связь — основание)
PartnerUserIdGuidДаPartnerUserId
DeveloperCompanyIdGuidДаDeveloperCompanyId
CommissionAccrualIdGuid?Нет; только platform-areaCommissionAccrualId (родительское начисление — гейт денег)
AppliedPercentdecimalДаAppliedRateSnapshot.Percent
AppliedRateScopestring (enum ReferralRateScope)ДаAppliedRateSnapshot.Scope
BaseAmountMoneyModelДа; только platform-areaBaseAmount (конечная цена сделки)
AmountMoneyModelДаAmount (INV-RA-2; после first-class корректировки — скорректированное значение, INV-RA-6)
OriginalAmountMoneyModel?Нет; только platform-areaOriginalAmount (исходная сумма до корректировок; null — не корректировалась, INV-RA-6)
Statusstring (enum ReferralAccrualStatus)ДаStatus: Pending/Approved/Paid/Cancelled
DealCompletedAtDateTimeOffsetДаDealCompletedAt
ApprovedAt / PaidAt / CancelledAtDateTimeOffset?Нетстатусные даты
CancelReasonstring? (enum ReferralCancelReason)НетCancelReason
PayoutOrderItemIdGuid?Нет; только platform-areaPayoutOrderItemId
CreatedAtDateTimeOffsetДаCreatedAt
VersionlongДаVersion

InvestorUserId в модель не проецируется ни в одной area (PII приведённого инвестора — дом ../domain/referral-accrual.md).

PlatformReceiptModel (полная проекция PlatformReceiptEntity — дом: ../domain/platform-receipt.md; только platform-area)​

ПолеТипОбязательностьИсточник
IdGuidДаPlatformReceiptEntity.Id
NumberstringДаNumber (RC-{yyyy}-{seq})
DeveloperCompanyIdGuidДаDeveloperCompanyId
AmountMoneyModelДаAmount (сумма фактического поступления)
ItemsCountintДаItemsCount
PaymentReferencestring?НетPaymentReference
Commentstring?НетComment
Statusstring (enum PlatformReceiptStatus)ДаStatus: Draft/Registered/Cancelled
RegisteredAt / CancelledAtDateTimeOffset?Нетстатусные даты
CreatedAtDateTimeOffsetДаCreatedAt
VersionlongДаVersion
ItemsIReadOnlyList<PlatformReceiptItemModel>Даchild-коллекция позиций

PlatformReceiptItemModel​

ПолеТипОбязательностьИсточник
IdGuidДаPlatformReceiptItemEntity.Id
CommissionAccrualIdGuidДаCommissionAccrualId
AgencyCompanyIdGuidДаAgencyCompanyId
AmountMoneyModelДаAmount (= CommissionAmount начисления на момент включения)
CreatedAtDateTimeOffsetДаCreatedAt

RewardsExportJobModel (задача Excel-выгрузки — agency/create-rewards-export.md, ADR-0041)​

ПолеТипОбязательностьИсточник
IdGuidДаid задачи выгрузки (jobId маршрутов)
ReportTypestring (enum RewardsReportType)ДаByEmployeePerDeal/PeriodSummary
Statusstring (enum RewardsExportJobStatus)ДаQueued/Running/Completed/Failed/Expired
PeriodFrom / PeriodToDateTimeOffsetДаснапшот фильтров задачи
AgentUserIdGuid?Нетснапшот фильтров
StatusFilterstring? (enum CommissionAccrualStatus)Нетснапшот фильтров
RowsCountint?Нет (заполняется при Completed)число строк файла
FailureCodestring?Только при Failedпричина (REWARDS_EXPORT_ROW_LIMIT_EXCEEDED и др.)
DownloadUrlstring?Только при Completed и живом файлекороткоживущая подписанная ссылка (TTL 1 час)
DownloadUrlExpiresAtDateTimeOffset?Вместе с DownloadUrlмомент истечения ссылки
CreatedAtDateTimeOffsetДапостановка задачи
CompletedAtDateTimeOffset?Нетзавершение генерации

ReferralRewardsExportJobModel (задача Excel-выгрузки реферальных вознаграждений — partner/create-referral-rewards-export.md, ADR-0041)​

ПолеТипОбязательностьИсточник
IdGuidДаid задачи выгрузки (jobId маршрутов)
ReportTypestring (enum ReferralRewardsReportType)ДаByPartner/PeriodSummary
Scopestring (own/all)Даобласть выборки, разрешённая по permission (own — свои начисления; all — все партнёры)
Statusstring (enum RewardsExportJobStatus)ДаQueued/Running/Completed/Failed/Expired
PeriodFrom / PeriodToDateTimeOffsetДаснапшот фильтров задачи
PartnerUserIdGuid?Нетснапшот фильтров (при Scope = own = актор; при Scope = all — опциональный фильтр)
StatusFilterstring? (enum ReferralAccrualStatus)Нетснапшот фильтров
RowsCountint?Нет (заполняется при Completed)число строк файла
FailureCodestring?Только при Failedпричина (REWARDS_EXPORT_ROW_LIMIT_EXCEEDED и др.)
DownloadUrlstring?Только при Completed и живом файлекороткоживущая подписанная ссылка (TTL 1 час)
DownloadUrlExpiresAtDateTimeOffset?Вместе с DownloadUrlмомент истечения ссылки
CreatedAtDateTimeOffsetДапостановка задачи
CompletedAtDateTimeOffset?Нетзавершение генерации

CommissionSummaryModel (сводка ЛК: «получим/получили × подтверждено/ожидает»)​

Каждая метрика — пара сумма+количество; вычисляется SQL-агрегацией (SUM, COUNT) по rewards.commission_accruals / rewards.commission_distributions (ADR-0056, без ClickHouse).

ПолеТипОбязательностьФормула (источник)
PendingConfirmationTotalMoneyModelДаΣ по строкам области видимости со Status = PendingConfirmation («получим, ожидает подтверждения»)
PendingConfirmationCountintДаcount тех же строк
ConfirmedTotalMoneyModelДаΣ со Status = Confirmed («получим, подтверждено; деньги от застройщика ещё не получены»)
ConfirmedCountintДаcount тех же строк
MoneyReceivedTotalMoneyModelДаΣ со Status = MoneyReceived («деньги получены, готово к выплате» — гейт ADR-0067 пройден)
MoneyReceivedCountintДаcount тех же строк
PaidTotalMoneyModelДаΣ со Status = Paid («получили»)
PaidCountintДаcount тех же строк
CancelledTotalMoneyModelДаΣ со Status = Cancelled (справочно)
CancelledCountintДаcount тех же строк

База суммирования зависит от области: агентство — CommissionAmount (gross) + отдельно AgencyRetainedTotal/AgentsShareTotal (дельта в get-agency-commission-summary.md); агент — Amount его Agent-строки распределения, для PendingConfirmation (строк ещё нет) — прогноз по активной политике (дельта в get-my-commission-summary.md).

Paging (все list-операции)​

ПолеИсточникТипОграничения
Pagequeryint>= 1, default 1
PageSizequeryint1..100, default 20

Ответ — страница: Items : IReadOnlyList<TItem>, Page : int, PageSize : int, TotalCount : long.

Masking-правила (все операции)​

ПравилоЗначение
InvestorUserIdНикогда не отдаётся в API rewards (ни агентству, ни агенту, ни застройщику, ни партнёру) — трассировка только через DealId в crm
DistributionsОтдаются только agency-area (rewards.commission.view-all); агенту — только собственная Agent-строка (проекция MyAccrualModel); застройщику — не отдаются (внутреннее дело агентства и платформы)
Условия платформы и ставкиPlatformTermsModel/ReferralRateRuleModel — только platform-area; агентству/партнёру видны лишь применённые значения в снапшотах начислений (PlatformRetentionPercentagePoints/PlatformFeeAmount, AppliedPercent)
Акты поступления средствPlatformReceiptModel — только platform-area (rewards.receipts.manage); агентству виден эффект: Status = MoneyReceived, MoneyReceivedAt, PlatformReceiptId начисления
Реферальные начисленияПартнёру — только свои (record-level PartnerUserId, rewards.referral.view-own); BaseAmount, CommissionAccrualId, PayoutOrderItemId — только platform-area
СуммыSensitive: не логируются (в logs — только Id/Status/counts), доступ строго по permissions; выгрузки — audit ExportSensitive (ADR-0041)
Полный документ политикиАгенту не отдаётся; агент видит только применённое к нему удержание в своих проекциях

Общие ошибки (все операции; коды не дублируются в файлах операций)​

КодHTTP statusУсловие
ValidationError400Валидатор отклонил вход (формат/диапазоны/enum)
FORBIDDEN403Нет permission / чужой tenant / record-level нарушение
UNAUTHORIZED401Нет/просрочен JWT (m2m — неверный audience)
REWARDS_CONCURRENCY_CONFLICT409ExpectedVersion не совпал с Version агрегата

Согласованность и порядок событий (общее для area)​

Единые гарантии для всех операций контекста — файлы операций на них ссылаются, не повторяя:

  • Атомарность. Изменение агрегата и публикация его интеграционных событий происходят в одном согласованном изменении (транзакционный outbox): наблюдатель никогда не видит изменённое состояние без соответствующего события и наоборот.
  • Ключ партиционирования и порядок. Ключ каждого события — идентификатор его агрегата (RuleId для правил, AccrualId для начислений — в т.ч. commission-money-received при регистрации акта, PayoutOrderId для поручений, id реферального начисления для топика pin.rewards.referral-accruals.v1). Порядок событий в пределах одного агрегата сохраняется; межагрегатного глобального порядка нет.
  • Доставка и идемпотентность. Доставка — at-least-once; потребители обязаны быть идемпотентными (дедуп по идентификатору агрегата + Version/переходу либо по натуральному ключу вроде DealId). Повторная доставка одного события не должна давать двойного эффекта.
  • Синхронный ответ vs витрины. HTTP-ответ операции всегда отражает уже зафиксированное состояние сразу. Производные представления в других сервисах (комиссия в витрине catalog, self-проекция AgentPerformance, ленты уведомлений) обновляются асинхронно — окно eventual-consistency измеряется секундами; в этом окне пользователь может видеть прежнее значение в производном представлении при уже применённом изменении в источнике (rewards). Конкретные окна — в разделе «Побочные эффекты» соответствующей операции.
  • Конкурентность мутаций. Мутации агрегатов используют optimistic concurrency по ExpectedVersion; проигравший параллельную гонку получает REWARDS_CONCURRENCY_CONFLICT (409), перечитывает актуальное состояние и повторяет. Единственность (приоритет активного правила, одно начисление на сделку) страхуется уникальными индексами — гонка двух создающих запросов даёт доменный конфликт-код операции.

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