Путь партнера

Полный путь от зарегистрированного пользователя до активного MLM-партнера, получающего комиссии.

Обзор

Путь партнера включает:

1. Проверка предварительных условий (зарегистрированный пользователь, KYC подтвержден)
2. Вступление в партнерскую программу
3. Настройка профиля партнера и способа выплат
4. Управление реферальными ссылками
5. Отслеживание рефералов и получение комиссий
6. Продвижение по рангам
7. Запрос и получение выплат

---

Основная диаграмма процесса

---

Детали этапов

1. Проверка предварительных условий

Требования для участия:

Требование	Проверка	Код ошибки
Пользователь зарегистрирован	Пользователь существует и активен	USER_NOT_FOUND
Email подтвержден	email_verified_at заполнен	EMAIL_NOT_VERIFIED
KYC подтвержден	kyc_verification.status = APPROVED	KYC_REQUIRED
Еще не партнер	Запись партнера не существует	ALREADY_PARTNER
Возрастное требование	DOB указывает на 18+ лет	AGE_REQUIREMENT

Эндпоинт: GET /users/me/partner-eligibility

Ответ:

{
  "eligible": true,
  "requirements": {
    "registered": { "met": true },
    "emailVerified": { "met": true },
    "kycApproved": { "met": true },
    "ageRequirement": { "met": true }
  }
}

---

2. Становление партнером

Эндпоинт: POST /partners/enroll

Тело запроса:

{
  "acceptTerms": true,
  "acceptPrivacyPolicy": true,
  "marketingConsent": false
}

Создаваемая запись партнера:

{
  "id": "uuid",
  "userId": "user-uuid",
  "sponsorId": "sponsor-partner-uuid or null",
  "referralCode": "ABC123XY",
  "status": "ACTIVE",
  "currentRankId": "starter-rank-uuid",
  "highestRankId": "starter-rank-uuid",
  "directReferralsCount": 0,
  "totalNetworkSize": 0,
  "treeDepth": 0,
  "joinedAt": "2024-01-15T10:30:00Z",
  "activatedAt": "2024-01-15T10:30:00Z"
}

Генерация реферального кода:

• 8 буквенно-цифровых символов
• Только заглавные буквы
• Исключены неоднозначные символы (0, O, 1, I, L)
• Проверка на коллизии с повтором

Записи в таблице замыкания:

-- Самоссылка (всегда создается)
INSERT INTO mlm.partner_tree_paths (ancestor_id, descendant_id, depth)
VALUES (new_partner_id, new_partner_id, 0);

-- Записи вышестоящей линии (если есть спонсор)
INSERT INTO mlm.partner_tree_paths (ancestor_id, descendant_id, depth)
SELECT ancestor_id, new_partner_id, depth + 1
FROM mlm.partner_tree_paths
WHERE descendant_id = sponsor_id;

---

3. Настройка профиля партнера

Способы выплат

Эндпоинт: POST /partners/me/payout-methods

Поддерживаемые способы:

Способ	Обязательные поля
BANK_CARD	cardNumber, cardHolderName, expiryMonth, expiryYear
BANK_TRANSFER	bankName, accountNumber, bik, correspondentAccount
EWALLET	provider (yoomoney, qiwi), accountId

Запрос (банковская карта):

{
  "type": "BANK_CARD",
  "cardNumber": "4111111111111111",
  "cardHolderName": "IVAN PETROV",
  "expiryMonth": 12,
  "expiryYear": 2025,
  "isDefault": true
}

Безопасность:

• Номера карт зашифрованы (AES-256-GCM)
• Только последние 4 цифры хранятся в открытом виде
• Требуется соответствие PCI DSS

Налоговая информация

Эндпоинт: PUT /partners/me/tax-info

Запрос:

{
  "taxIdType": "INN",
  "taxId": "123456789012",
  "isIndividualEntrepreneur": false,
  "taxResidency": "RUS"
}

---

4. Генерация реферальных ссылок

Эндпоинт: POST /partners/me/links

Запрос:

{
  "name": "Instagram Bio",
  "targetUrl": "/products/featured",
  "utmSource": "instagram",
  "utmMedium": "bio",
  "utmCampaign": "winter_2024"
}

Структура сгенерированной ссылки:

https://platform.com/products/featured?ref=ABC123XY&utm_source=instagram&utm_medium=bio&utm_campaign=winter_2024

Возможности ссылок:

• Пользовательские коды (опционально, премиум-функция)
• Настройка целевого URL
• Отслеживание UTM-параметров
• Дата истечения (опционально)
• Аналитика кликов

Правила валидации:

Правило	Ограничение
Название	Максимум 100 символов
Целевой URL	Должен быть валидным путем платформы
Пользовательский код	4-20 буквенно-цифровых символов, уникальный
UTM-параметры	Максимум 100 символов каждый
Ссылок на партнера	Максимум 50 активных ссылок

---

5. Распространение и отслеживание

Эндпоинт дашборда: GET /partners/me/dashboard

Ответ:

{
  "summary": {
    "totalClicks": 1250,
    "totalRegistrations": 85,
    "totalConversions": 42,
    "conversionRate": 3.36
  },
  "earnings": {
    "pendingBalance": 15000.00,
    "availableBalance": 45000.00,
    "totalEarned": 120000.00,
    "totalWithdrawn": 60000.00,
    "currency": "RUB"
  },
  "rank": {
    "current": "Silver",
    "nextRank": "Gold",
    "progressPercent": 65,
    "requirements": [
      { "type": "CAREER_POINTS_PERIOD", "current": 6500, "required": 10000 },
      { "type": "DIRECT_REFERRALS", "current": 8, "required": 10 }
    ]
  },
  "recentActivity": [
    { "type": "COMMISSION", "amount": 500, "source": "ORDER", "date": "2024-01-15" },
    { "type": "REGISTRATION", "referralName": "John D.", "date": "2024-01-14" }
  ],
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

Статистика в реальном времени:

• Клики: Обновляются мгновенно через счетчик Redis
• Регистрации: Обновляются при создании пользователя
• Комиссии: Обновляются после завершения задания комиссии

---

6. Получение комиссий

Источники комиссий:

Тип источника	Триггерное событие	База комиссии
ORDER	Статус заказа = CONFIRMED	Сумма заказа
INVESTMENT	Статус участия = ACTIVE	Сумма инвестиции
RANK_BONUS	Повышение ранга	Единовременный бонус

Расчет комиссий: Смотрите Жизненный цикл комиссии для детального расчета.

Статусы комиссий:

PENDING -> APPROVED -> PAID
                   \-> HELD -> REVERSED/CLAWBACK

---

7. Продвижение по рангам

Иерархия рангов:

Ранг	Уровень	Краткие требования
Starter	1	Ранг по умолчанию
Bronze	2	1,000 CP + 3 прямых реферала
Silver	3	5,000 CP + 5 прямых рефералов
Gold	4	15,000 CP + 10 прямых рефералов + 2 Silver
Platinum	5	50,000 CP + 20 прямых рефералов + 3 Gold
Diamond	6	150,000 CP + 50 прямых рефералов + 4 Platinum

Расписание оценки:

• Автоматическая: Ежедневно в 02:00 UTC
• По требованию: После значительной активности (покупка, реферал)

Преимущества рангов:

Ранг	Уровни комиссии	Бонусные функции
Starter	1-3	Базовый дашборд
Bronze	1-5	Приоритетная поддержка
Silver	1-7	Пользовательские реферальные коды
Gold	1-10	Персональный менеджер
Platinum	1-10	Бонусный пул лидерства
Diamond	1-10	Награды высшего уровня

---

8. Запрос выплаты

Эндпоинт: POST /partners/me/payouts

Запрос:

{
  "amount": 5000.00,
  "currency": "RUB",
  "payoutMethodId": "method-uuid"
}

Правила валидации:

Правило	Значение
Минимальная выплата	1,000 RUB
Максимальная выплата	500,000 RUB за запрос
Доступный баланс	Должен быть >= запрашиваемой суммы
Статус KYC	Должен быть APPROVED
Ожидающие выплаты	Максимум 1 ожидающий запрос за раз

Поток статусов выплаты:

PENDING -> APPROVED -> PROCESSING -> COMPLETED
    |          |            |
    v          v            v
CANCELLED  REJECTED     FAILED

---

9. Обработка выплат

Сроки обработки:

Способ	Время проверки	Время обработки	Итого
Банковская карта	1-24 часа	Мгновенно	1-24 часа
Банковский перевод	1-24 часа	1-3 рабочих дня	2-4 дня
Электронный кошелек	1-24 часа	Мгновенно	1-24 часа

Автоматическое одобрение (если включено):

• Партнер имеет 5+ успешных выплат
• Сумма < 10,000 RUB
• Нет недавних флагов или удержаний

Подтверждение выплаты:

• Email-уведомление с деталями транзакции
• Уведомление в приложении
• SMS (опционально)

---

Сценарии ошибок

Ошибки регистрации

Сценарий	HTTP-код	Код ошибки	Сообщение
KYC не подтвержден	403	KYC_REQUIRED	"Сначала пройдите верификацию личности"
Уже партнер	409	ALREADY_PARTNER	"Вы уже зарегистрированы как партнер"
Условия не приняты	400	TERMS_REQUIRED	"Необходимо принять условия и положения"

Ошибки выплат

Сценарий	HTTP-код	Код ошибки	Сообщение
Недостаточный баланс	422	INSUFFICIENT_BALANCE	"Доступный баланс меньше запрашиваемой суммы"
Ниже минимума	400	BELOW_MINIMUM	"Минимальная сумма выплаты 1,000 RUB"
Есть ожидающая выплата	409	PAYOUT_ALREADY_PENDING	"У вас есть ожидающий запрос на выплату"
Нет способа выплаты	400	NO_PAYOUT_METHOD	"Сначала добавьте способ выплаты"
KYC истек	403	KYC_EXPIRED	"Срок действия вашей верификации истек"

Ошибки генерации ссылок

Сценарий	HTTP-код	Код ошибки	Сообщение
Дублирующий пользовательский код	409	CODE_EXISTS	"Этот реферальный код уже занят"
Неверный целевой URL	400	INVALID_TARGET	"Целевой URL должен быть валидным путем платформы"
Достигнут лимит ссылок	400	LINK_LIMIT	"Достигнуто максимальное количество реферальных ссылок"

---

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

• Регистрация пользователя
• Процесс атрибуции рефералов
• Жизненный цикл комиссии
• MLM-схема
• Комиссионный движок