---
title: "Партнерська та реферальна підтримка"
description: "Подвійна економіка рефералів — комісії ERP, фінансовані продавцями, і ончейн-токенові винагороди платформи зі спільною атрибуцією та аудитом"
locale: "uk"
---
# Партнерська та реферальна підтримка

Ring Platform поєднує **застарілу інфраструктуру комісій продавців** із модулем зростання **refcodes**. Один cookie атрибуції керує двома рейками виплат: продавці фінансують фіатну реферальну комісію через ERP-розрахунки, а платформа фінансує **токенові** винагороди реферерів через ончейн-мінтер. Обидві рейки використовують `orderReference` для перехресного аудиту.

**Реферери отримують токени.** **Продавці фінансують** свою частку реферальної комісії з розрахунку. **Покупці** бачать реферальний бейдж під час checkout, якщо їх атрибутовано. **Оператори** схвалюють фіатні мінти, запускають cron для черги та переглядають комісії за адресою `/admin/store/commissions`.

> **Докладніше:** [Реферальні коди (refcodes)](/docs/features/refcodes.md) · [Архітектура refcodes](/docs/architecture/refcodes.md) · [Комісії ERP](/docs/features/erp/commissions.md)

## Економіка двох рейок

| Рейка | Хто платить | Механізм | Коли запускається |
|------|----------|-----------|--------------|
| **ERP (фінансує продавець)** | Чиста виплата продавцю | `calculateCommission()` → `settlements.metadata.commissionBreakdown.referralCommission` | Оплачений order магазину (WayForPay або кредит) |
| **Refcodes (фінансує платформа)** | Скарбниця / мінтер платформи | `ReferralRewardService` → `ReferralRewards.payReferral` у Polygon | Після оплати order (фіат: після схвалення; кредит: одразу) |

Обидві рейки використовують **`resolveReferralCommissionPercent`** (`features/store/lib/referral-commission.ts`) — override продукту → конфігурація продавця → типовий параметр платформи (`5%`) → env `REFERRAL_REWARD_PERCENT`.

**У межах:** замовлення магазину та оновлення membership. **Поза межами цієї ітерації:** реферали просування новин і знижки referee під час checkout (стимул лише для реферера).

```mermaid
flowchart TB
    subgraph Edge["Attribution"]
        Ref["?ref=CODE"]
        Cookie["ring_ref + ring_ref_visible"]
        Signup["users.data.referredBy on first sign-in"]
    end
    subgraph Order["Paid order / membership"]
        ORD["orders + orderReference"]
        ATTR["resolveOrderReferral guards"]
    end
    subgraph RailA["ERP rail — vendor-funded"]
        SET["recordSettlementsForPaidOrder"]
        BRK["commissionBreakdown.referralCommission"]
        ASSIST["erp_sales_assists + stock movement metadata"]
    end
    subgraph RailB["Refcodes rail — platform token"]
        RW["referral_rewards ledger"]
        MINT["reward-minter → ReferralRewards"]
        NOTIFY["REFERRAL_REWARD_MINTED notification"]
    end
    Ref --> Cookie
    Cookie --> Signup
    Cookie --> ATTR
    Signup --> ATTR
    ATTR --> ORD
    ORD --> SET --> BRK
    ORD --> ASSIST
    ORD --> RW --> MINT --> NOTIFY
    ORD -.->|same orderReference| BRK
    ORD -.->|same orderReference| RW
```

## Життєвий цикл атрибуції

**Перехід із `?ref=`** — `proxy.ts` встановлює httpOnly `ring_ref` і доступний клієнту `ring_ref_visible` (30 днів, перший дотик).

**Beacon візиту** — `ReferralAttributionEffect` викликає `POST /api/refcodes/track`; `visitDaily` групує статистику dashboard (утримання 28 днів).

**Збереження signup** — `signIn` Auth.js для нових користувачів запускає `persistSignupReferralAttribution`, тому `users.data.referredBy` переживає завершення cookie.

**Checkout** — крок Review показує `ReferralCheckoutBadge`; API order повертають `referralApplied` + `referralCode`; кредитний checkout показує toast, WayForPay зберігає flash у sessionStorage.

**Успішна оплата** — webhook магазину або кредитний шлях записує settlements (ERP) і `referral_rewards` (токени). Webhook membership викликає `ReferralRewardService.onMembershipPaid`, якщо задано `referredBy`.

## Поверхні оператора

- **[Dashboard реферера](/docs/features/refcodes.md)** — `/refcodes` — посилання, історія винагород, статистика візитів (усього / сьогодні / 7d / 28d).

- **[Адміністрування refcodes](/docs/features/refcodes.md)** — `/admin/refcodes` — схвалення фіатних винагород, пакетний мінт, агрегати візитів.

- **[Адміністрування комісій](/docs/features/erp/commissions.md)** — `/admin/store/commissions` — ledger розрахунків, реферальна розбивка, виплати.

- **[Архітектура](/docs/architecture/refcodes.md)** — Мапа інтеграції cookie → ledger → contract та ключі ідемпотентності.

## Перехресний аудит рейок

Кожна атрибутована оплачена подія повинна мати те саме **`orderReference`** (рядок PaymentConductor) у таких записах:

| Запис | Поле |
|--------|-------|
| `settlements` | `orderId` / metadata |
| `erp_sales_assists` | `orderId` |
| `referral_rewards` | `orderReference` (унікальний індекс) |
| On-chain | `keccak256(orderReference)` у `ReferralRewards.paidOrders` |

Smoke: `scripts/smoke-erp-referral-pipeline.cts`, `scripts/smoke-growth-pipelines.cts`, `scripts/smoke-refcodes-http.cts` (потрібні `DB_BACKEND_MODE` + `NODE_OPTIONS=--conditions=react-server`).

## Операційний чекліст

| Крок | Дія |
|------|--------|
| **1. Міграції** | Застосуйте `005_refcodes_schema.sql`, потім `007_settlements_schema.sql`. |
| **2. Env** | Заповніть REFERRAL CODES і CRON_SECRET у `env.local.template`; розгорніть проксі ReferralRewards і надайте йому право мінту. |
| **3. Cron** | Заплануйте `GET /api/cron/refcodes-mint` з `Authorization: Bearer $CRON_SECRET` (до 20 схвалених винагород за запуск). |
| **4. Перевірка** | Referred order → `settlements` + `erp_sales_assists` + `referral_rewards` зі спільним `orderReference`. |

Запустіть `./scripts/run-all-smokes.sh` (встановлює `DB_BACKEND_MODE` і `NODE_OPTIONS=--conditions=react-server`). Цільові набори: `smoke-erp-referral-pipeline.cts`, `smoke-growth-pipelines.cts`, `smoke-refcodes-http.cts`.

## Пов’язана документація

  
- [features/refcodes](/docs/features/refcodes.md) — Поглиблення: UI користувача/адміністратора, деплой contract і env для токенових винагород.

  
- [features/erp/commissions](/docs/features/erp/commissions.md) — Той самий процес: ієрархія розрахунків, фінансованих продавцем, і режими виплат.

  
- [features/erp/inventory](/docs/features/erp/inventory.md) — Залежність: оплачений commitSaleForOrder працює поруч із settlement для замовлень магазину.

  
- [features/payment-conductor](/docs/features/payment-conductor.md) — Передумова: webhooks і контракт orderReference.

  
- [features/store](/docs/features/store.md) — Передумова: checkout і потоки продавця живлять referred orders.