API MLM

Общая информация

Базовый URL

/api/v1/mlm

Заголовок аутентификации

Authorization: Bearer <access_token>

Формат ответа

Все ответы следуют стандартному формату:

typescript

// Успешный ответ
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    [key: string]: unknown;
  };
}

// Ответ с ошибкой
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, string[]>;
  };
}

Формат пагинации

typescript

interface PaginationMeta {
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
  hasNext: boolean;
  hasPrevious: boolean;
}

Ограничения запросов

Эндпоинт	Лимит
Общие эндпоинты MLM	100/мин
POST /payouts/request	1/мин на пользователя
Запросы сети	50/мин

Заголовки ограничения запросов для финансовых эндпоинтов

X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705329600
X-RateLimit-Policy: financial

Эндпоинты партнера

POST /api/v1/mlm/partner/register

Регистрация в качестве партнера (аффилиата) в MLM сети.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

typescript

interface PartnerRegisterRequest {
  referralCode?: string;        // Реферальный код спонсора (опционально)
  acceptPartnerTerms: boolean;  // Должно быть true
}

Параметры запроса

Нет

Ответ (201 Created)

typescript

interface PartnerRegisterResponse {
  partnerId: string;
  referralCode: string;
  status: 'ACTIVE';
  sponsor: {
    id: string;
    name: string;
  } | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Условия не приняты
401	UNAUTHORIZED	Недействительный или истекший access token
404	INVALID_REFERRAL_CODE	Реферальный код спонсора не найден
409	ALREADY_PARTNER	Пользователь уже зарегистрирован как партнер
403	KYC_REQUIRED	Требуется KYC верификация для становления партнером

Пример

Запрос:

bash

curl -X POST https://api.iwm-platform.com/api/v1/mlm/partner/register \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "ABC123XY",
    "acceptPartnerTerms": true
  }'

Ответ:

json

{
  "success": true,
  "data": {
    "partnerId": "cc0e8400-e29b-41d4-a716-446655440000",
    "referralCode": "DEF456ZW",
    "status": "ACTIVE",
    "sponsor": {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith"
    },
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

GET /api/v1/mlm/partner/me

Получение профиля текущего партнера.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface PartnerProfileResponse {
  id: string;
  userId: string;
  referralCode: string;
  status: 'PENDING' | 'ACTIVE' | 'SUSPENDED' | 'TERMINATED';
  currentRank: {
    id: string;
    name: string;
    code: string;
    level: number;
    badgeUrl: string | null;
  } | null;
  highestRank: {
    id: string;
    name: string;
    code: string;
    level: number;
  } | null;
  sponsor: {
    id: string;
    name: string;
    rank: string | null;
  } | null;
  stats: {
    directReferralsCount: number;
    totalNetworkSize: number;
    treeDepth: number;
  };
  joinedAt: string;
  activatedAt: string | null;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/partner/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "id": "cc0e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "referralCode": "DEF456ZW",
    "status": "ACTIVE",
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2,
      "badgeUrl": "https://cdn.iwm-platform.com/badges/silver.png"
    },
    "highestRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2
    },
    "sponsor": {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith",
      "rank": "Gold Partner"
    },
    "stats": {
      "directReferralsCount": 15,
      "totalNetworkSize": 87,
      "treeDepth": 4
    },
    "joinedAt": "2024-01-15T10:00:00Z",
    "activatedAt": "2024-01-15T10:00:00Z"
  }
}

PATCH /api/v1/mlm/partner/me

Обновление профиля партнера.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

typescript

interface UpdatePartnerRequest {
  payoutDetails?: {
    method: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
    cardNumber?: string;          // Для BANK_CARD
    bankName?: string;            // Для BANK_TRANSFER
    bankBik?: string;             // Для BANK_TRANSFER
    accountNumber?: string;       // Для BANK_TRANSFER
    walletType?: string;          // Для EWALLET (например, 'YOOMONEY', 'QIWI')
    walletId?: string;            // Для EWALLET
  };
}

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface UpdatePartnerResponse {
  id: string;
  payoutDetails: {
    method: string;
    maskedDetails: string;        // например, "**** **** **** 1234"
    lastUpdated: string;
  } | null;
  updatedAt: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные данные для выплаты
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X PATCH https://api.iwm-platform.com/api/v1/mlm/partner/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "payoutDetails": {
      "method": "BANK_CARD",
      "cardNumber": "4111111111111234"
    }
  }'

Ответ:

json

{
  "success": true,
  "data": {
    "id": "cc0e8400-e29b-41d4-a716-446655440000",
    "payoutDetails": {
      "method": "BANK_CARD",
      "maskedDetails": "**** **** **** 1234",
      "lastUpdated": "2024-01-15T16:00:00Z"
    },
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}

GET /api/v1/mlm/partner/network

Получение структуры нижестоящей сети.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 50 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
page	number	Номер страницы (опционально)
pageSize	number	Элементов на странице, макс. 100 (опционально)
depth	number	Максимальная глубина уровня, 1-10 (опционально)
level	number	Конкретный уровень для получения (опционально)
status	string	Фильтр по статусу: 'ACTIVE', 'SUSPENDED', 'ALL' (опционально)
search	string	Поиск по имени или реферальному коду (опционально)

Ответ (200 OK)

typescript

interface NetworkResponse {
  partners: NetworkPartner[];
  summary: {
    totalCount: number;
    byLevel: {
      level: number;
      count: number;
    }[];
  };
}

interface NetworkPartner {
  id: string;
  name: string;
  referralCode: string;
  level: number;                  // Глубина от текущего партнера
  status: string;
  rank: {
    name: string;
    code: string;
  } | null;
  directReferralsCount: number;
  joinedAt: string;
  lastActiveAt: string | null;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные параметры запроса
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/partner/network?depth=3&page=1&pageSize=20" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "partners": [
      {
        "id": "ff0e8400-e29b-41d4-a716-446655440001",
        "name": "Alice Johnson",
        "referralCode": "ALI789AB",
        "level": 1,
        "status": "ACTIVE",
        "rank": {
          "name": "Bronze Partner",
          "code": "BRONZE"
        },
        "directReferralsCount": 5,
        "joinedAt": "2024-01-20T14:00:00Z",
        "lastActiveAt": "2024-01-25T10:30:00Z"
      },
      {
        "id": "ff0e8400-e29b-41d4-a716-446655440002",
        "name": "Bob Williams",
        "referralCode": "BOB456CD",
        "level": 2,
        "status": "ACTIVE",
        "rank": null,
        "directReferralsCount": 2,
        "joinedAt": "2024-01-22T09:00:00Z",
        "lastActiveAt": "2024-01-24T16:45:00Z"
      }
    ],
    "summary": {
      "totalCount": 87,
      "byLevel": [
        { "level": 1, "count": 15 },
        { "level": 2, "count": 32 },
        { "level": 3, "count": 40 }
      ]
    }
  },
  "meta": {
    "pagination": {
      "total": 87,
      "page": 1,
      "pageSize": 20,
      "totalPages": 5,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

GET /api/v1/mlm/partner/network/stats

Получение статистики сети.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 50 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
period	string	Период: 'DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR', 'ALL' (опционально)

Ответ (200 OK)

typescript

interface NetworkStatsResponse {
  period: string;
  periodStart: string;
  periodEnd: string;
  overview: {
    totalPartners: number;
    activePartners: number;
    newPartnersInPeriod: number;
    totalVolume: number;
    personalVolume: number;
    groupVolume: number;
  };
  growth: {
    date: string;
    newPartners: number;
    volume: number;
  }[];
  topPerformers: {
    id: string;
    name: string;
    volume: number;
    referrals: number;
  }[];
  rankDistribution: {
    rankCode: string;
    rankName: string;
    count: number;
    percentage: number;
  }[];
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный период
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/partner/network/stats?period=MONTH" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "period": "MONTH",
    "periodStart": "2024-01-01T00:00:00Z",
    "periodEnd": "2024-01-31T23:59:59Z",
    "overview": {
      "totalPartners": 87,
      "activePartners": 65,
      "newPartnersInPeriod": 12,
      "totalVolume": 1250000,
      "personalVolume": 150000,
      "groupVolume": 1100000
    },
    "growth": [
      { "date": "2024-01-01", "newPartners": 2, "volume": 45000 },
      { "date": "2024-01-08", "newPartners": 3, "volume": 62000 },
      { "date": "2024-01-15", "newPartners": 4, "volume": 78000 },
      { "date": "2024-01-22", "newPartners": 3, "volume": 55000 }
    ],
    "topPerformers": [
      { "id": "ff0e8400-e29b-41d4-a716-446655440001", "name": "Alice Johnson", "volume": 250000, "referrals": 8 },
      { "id": "ff0e8400-e29b-41d4-a716-446655440002", "name": "Bob Williams", "volume": 180000, "referrals": 5 }
    ],
    "rankDistribution": [
      { "rankCode": "STARTER", "rankName": "Starter", "count": 45, "percentage": 51.72 },
      { "rankCode": "BRONZE", "rankName": "Bronze Partner", "count": 25, "percentage": 28.74 },
      { "rankCode": "SILVER", "rankName": "Silver Partner", "count": 12, "percentage": 13.79 },
      { "rankCode": "GOLD", "rankName": "Gold Partner", "count": 5, "percentage": 5.75 }
    ]
  }
}

Эндпоинты реферальных ссылок

GET /api/v1/mlm/referrals/links

Список всех реферальных ссылок.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
page	number	Номер страницы (опционально)
pageSize	number	Элементов на странице, макс. 50 (опционально)
status	string	Фильтр: 'ACTIVE', 'EXPIRED', 'ALL' (опционально)

Ответ (200 OK)

typescript

interface ReferralLinksResponse {
  links: ReferralLink[];
  defaultLink: string;
}

interface ReferralLink {
  id: string;
  code: string;
  name: string | null;
  fullUrl: string;
  targetUrl: string | null;
  utmParams: {
    source: string | null;
    medium: string | null;
    campaign: string | null;
  };
  stats: {
    clicks: number;
    registrations: number;
    conversions: number;
  };
  isActive: boolean;
  expiresAt: string | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/referrals/links?status=ACTIVE" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "gg0e8400-e29b-41d4-a716-446655440001",
        "code": "DEF456ZW-IG",
        "name": "Instagram Bio",
        "fullUrl": "https://iwm-platform.com/ref/DEF456ZW-IG",
        "targetUrl": null,
        "utmParams": {
          "source": "instagram",
          "medium": "social",
          "campaign": "bio_link"
        },
        "stats": {
          "clicks": 1250,
          "registrations": 45,
          "conversions": 12
        },
        "isActive": true,
        "expiresAt": null,
        "createdAt": "2024-01-10T14:00:00Z"
      }
    ],
    "defaultLink": "https://iwm-platform.com/ref/DEF456ZW"
  },
  "meta": {
    "pagination": {
      "total": 5,
      "page": 1,
      "pageSize": 20,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

POST /api/v1/mlm/referrals/links

Создание новой реферальной ссылки.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

typescript

interface CreateReferralLinkRequest {
  name: string;                   // Описательное название (например, "YouTube Channel")
  targetUrl?: string;             // URL конкретной целевой страницы
  utmSource?: string;             // UTM source параметр
  utmMedium?: string;             // UTM medium параметр
  utmCampaign?: string;           // UTM campaign параметр
  expiresAt?: string;             // Опциональная дата истечения (ISO 8601)
}

Параметры запроса

Нет

Ответ (201 Created)

typescript

interface CreateReferralLinkResponse {
  id: string;
  code: string;
  name: string;
  fullUrl: string;
  targetUrl: string | null;
  utmParams: {
    source: string | null;
    medium: string | null;
    campaign: string | null;
  };
  isActive: boolean;
  expiresAt: string | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные входные данные
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер
400	MAX_LINKS_REACHED	Достигнут максимум в 20 реферальных ссылок

Пример

Запрос:

bash

curl -X POST https://api.iwm-platform.com/api/v1/mlm/referrals/links \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "YouTube Channel",
    "utmSource": "youtube",
    "utmMedium": "video",
    "utmCampaign": "tutorial_series"
  }'

Ответ:

json

{
  "success": true,
  "data": {
    "id": "hh0e8400-e29b-41d4-a716-446655440001",
    "code": "DEF456ZW-YT",
    "name": "YouTube Channel",
    "fullUrl": "https://iwm-platform.com/ref/DEF456ZW-YT",
    "targetUrl": null,
    "utmParams": {
      "source": "youtube",
      "medium": "video",
      "campaign": "tutorial_series"
    },
    "isActive": true,
    "expiresAt": null,
    "createdAt": "2024-01-15T17:00:00Z"
  }
}

GET /api/v1/mlm/referrals/links/:id/stats

Получение детальной статистики по реферальной ссылке.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Параметры пути

Параметр	Тип	Описание
id	string (UUID)	ID реферальной ссылки

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
period	string	Период: 'DAY', 'WEEK', 'MONTH', 'ALL' (опционально)

Ответ (200 OK)

typescript

interface LinkStatsResponse {
  linkId: string;
  linkCode: string;
  period: string;
  periodStart: string;
  periodEnd: string;
  totals: {
    clicks: number;
    uniqueVisitors: number;
    registrations: number;
    conversions: number;
    conversionRate: number;
    totalRevenue: number;
    totalCommissions: number;
  };
  timeline: {
    date: string;
    clicks: number;
    registrations: number;
    conversions: number;
  }[];
  topReferrals: {
    userId: string;
    name: string;
    status: string;
    registeredAt: string;
    totalPurchases: number;
  }[];
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный период
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер
404	LINK_NOT_FOUND	Реферальная ссылка не найдена

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/referrals/links/gg0e8400-e29b-41d4-a716-446655440001/stats?period=MONTH" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "linkId": "gg0e8400-e29b-41d4-a716-446655440001",
    "linkCode": "DEF456ZW-IG",
    "period": "MONTH",
    "periodStart": "2024-01-01T00:00:00Z",
    "periodEnd": "2024-01-31T23:59:59Z",
    "totals": {
      "clicks": 1250,
      "uniqueVisitors": 980,
      "registrations": 45,
      "conversions": 12,
      "conversionRate": 26.67,
      "totalRevenue": 450000,
      "totalCommissions": 45000
    },
    "timeline": [
      { "date": "2024-01-01", "clicks": 45, "registrations": 2, "conversions": 0 },
      { "date": "2024-01-02", "clicks": 62, "registrations": 3, "conversions": 1 }
    ],
    "topReferrals": [
      {
        "userId": "ii0e8400-e29b-41d4-a716-446655440001",
        "name": "Carol Davis",
        "status": "ACTIVE",
        "registeredAt": "2024-01-05T10:00:00Z",
        "totalPurchases": 150000
      }
    ]
  }
}

DELETE /api/v1/mlm/referrals/links/:id

Удаление реферальной ссылки.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Параметры пути

Параметр	Тип	Описание
id	string (UUID)	ID реферальной ссылки

Тело запроса

Нет

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface DeleteLinkResponse {
  message: string;
  linkId: string;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер
404	LINK_NOT_FOUND	Реферальная ссылка не найдена
400	CANNOT_DELETE_DEFAULT	Нельзя удалить реферальную ссылку по умолчанию

Пример

Запрос:

bash

curl -X DELETE https://api.iwm-platform.com/api/v1/mlm/referrals/links/hh0e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "message": "Referral link deleted successfully",
    "linkId": "hh0e8400-e29b-41d4-a716-446655440001"
  }
}

Эндпоинты комиссий

GET /api/v1/mlm/commissions

Список транзакций комиссий.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
page	number	Номер страницы (опционально)
pageSize	number	Элементов на странице, макс. 100 (опционально)
status	string	Фильтр: 'PENDING', 'APPROVED', 'PAID', 'REVERSED', 'ALL' (опционально)
sourceType	string	Фильтр: 'ORDER', 'INVESTMENT', 'BONUS', 'RANK_BONUS' (опционально)
dateFrom	string	Начальная дата (ISO 8601) (опционально)
dateTo	string	Конечная дата (ISO 8601) (опционально)

Ответ (200 OK)

typescript

interface CommissionsResponse {
  commissions: Commission[];
}

interface Commission {
  id: string;
  sourceType: 'ORDER' | 'INVESTMENT' | 'BONUS' | 'RANK_BONUS' | 'CLAWBACK';
  sourceId: string;
  sourcePartner: {
    id: string;
    name: string;
  } | null;
  levelDepth: number | null;
  grossAmount: number;
  netAmount: number;
  careerPoints: number;
  currency: string;
  status: 'PENDING' | 'APPROVED' | 'PAID' | 'HELD' | 'REVERSED' | 'CLAWBACK' | 'CANCELLED';
  periodId: string | null;
  processedAt: string | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные параметры запроса
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/commissions?status=APPROVED&page=1&pageSize=20" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "commissions": [
      {
        "id": "jj0e8400-e29b-41d4-a716-446655440001",
        "sourceType": "ORDER",
        "sourceId": "kk0e8400-e29b-41d4-a716-446655440001",
        "sourcePartner": {
          "id": "ff0e8400-e29b-41d4-a716-446655440001",
          "name": "Alice Johnson"
        },
        "levelDepth": 1,
        "grossAmount": 1000,
        "netAmount": 1000,
        "careerPoints": 100,
        "currency": "RUB",
        "status": "APPROVED",
        "periodId": "2024-01",
        "processedAt": "2024-01-16T09:00:00Z",
        "createdAt": "2024-01-15T18:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 156,
      "page": 1,
      "pageSize": 20,
      "totalPages": 8,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

GET /api/v1/mlm/commissions/summary

Получение сводки комиссий по периоду.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
period	string	Период: 'DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR', 'ALL' (опционально)

Ответ (200 OK)

typescript

interface CommissionSummaryResponse {
  period: string;
  periodStart: string;
  periodEnd: string;
  totals: {
    grossEarned: number;
    netEarned: number;
    pending: number;
    approved: number;
    paid: number;
    reversed: number;
    careerPointsEarned: number;
  };
  bySource: {
    sourceType: string;
    count: number;
    total: number;
    careerPoints: number;
  }[];
  byLevel: {
    level: number;
    count: number;
    total: number;
  }[];
  trend: {
    date: string;
    earned: number;
    careerPoints: number;
  }[];
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный период
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/commissions/summary?period=MONTH" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "period": "MONTH",
    "periodStart": "2024-01-01T00:00:00Z",
    "periodEnd": "2024-01-31T23:59:59Z",
    "totals": {
      "grossEarned": 125000,
      "netEarned": 125000,
      "pending": 15000,
      "approved": 50000,
      "paid": 60000,
      "reversed": 0,
      "careerPointsEarned": 12500
    },
    "bySource": [
      { "sourceType": "ORDER", "count": 45, "total": 75000, "careerPoints": 7500 },
      { "sourceType": "INVESTMENT", "count": 12, "total": 45000, "careerPoints": 4500 },
      { "sourceType": "RANK_BONUS", "count": 1, "total": 5000, "careerPoints": 500 }
    ],
    "byLevel": [
      { "level": 1, "count": 30, "total": 60000 },
      { "level": 2, "count": 18, "total": 36000 },
      { "level": 3, "count": 10, "total": 29000 }
    ],
    "trend": [
      { "date": "2024-01-01", "earned": 4500, "careerPoints": 450 },
      { "date": "2024-01-02", "earned": 3200, "careerPoints": 320 }
    ]
  }
}

Эндпоинты рангов

GET /api/v1/mlm/ranks/current

Получение деталей текущего ранга.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface CurrentRankResponse {
  currentRank: {
    id: string;
    name: string;
    code: string;
    level: number;
    description: string | null;
    badgeUrl: string | null;
    colorCode: string | null;
  } | null;
  achievedAt: string | null;
  benefits: {
    commissionMultiplier: number;
    maxCommissionLevels: number;
    bonusPercentage: number;
  };
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/ranks/current \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2,
      "description": "Achieve 50,000 career points and have 10 direct referrals",
      "badgeUrl": "https://cdn.iwm-platform.com/badges/silver.png",
      "colorCode": "#C0C0C0"
    },
    "achievedAt": "2024-01-10T14:30:00Z",
    "benefits": {
      "commissionMultiplier": 1.1,
      "maxCommissionLevels": 5,
      "bonusPercentage": 2.0
    }
  }
}

GET /api/v1/mlm/ranks/progress

Получение прогресса к следующему рангу.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface RankProgressResponse {
  currentRank: {
    id: string;
    name: string;
    code: string;
    level: number;
  } | null;
  nextRank: {
    id: string;
    name: string;
    code: string;
    level: number;
    badgeUrl: string | null;
  } | null;
  requirements: {
    type: string;
    description: string;
    current: number;
    required: number;
    percentage: number;
    isMet: boolean;
  }[];
  overallProgress: number;
  estimatedAchievement: string | null;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/ranks/progress \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2
    },
    "nextRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440002",
      "name": "Gold Partner",
      "code": "GOLD",
      "level": 3,
      "badgeUrl": "https://cdn.iwm-platform.com/badges/gold.png"
    },
    "requirements": [
      {
        "type": "CAREER_POINTS_TOTAL",
        "description": "Total career points",
        "current": 75000,
        "required": 100000,
        "percentage": 75.0,
        "isMet": false
      },
      {
        "type": "DIRECT_REFERRALS",
        "description": "Direct referrals",
        "current": 15,
        "required": 20,
        "percentage": 75.0,
        "isMet": false
      },
      {
        "type": "GROUP_VOLUME",
        "description": "Monthly group volume",
        "current": 800000,
        "required": 500000,
        "percentage": 100.0,
        "isMet": true
      }
    ],
    "overallProgress": 75.0,
    "estimatedAchievement": "2024-03-15"
  }
}

GET /api/v1/mlm/ranks/history

Получение истории продвижения по рангам.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
page	number	Номер страницы (опционально)
pageSize	number	Элементов на странице, макс. 50 (опционально)

Ответ (200 OK)

typescript

interface RankHistoryResponse {
  history: RankChange[];
}

interface RankChange {
  id: string;
  fromRank: {
    name: string;
    code: string;
    level: number;
  } | null;
  toRank: {
    name: string;
    code: string;
    level: number;
  };
  changeType: 'PROMOTION' | 'DEMOTION' | 'INITIAL';
  qualificationSnapshot: {
    careerPoints: number;
    directReferrals: number;
    groupVolume: number;
  };
  periodId: string | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/ranks/history?page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440001",
        "fromRank": {
          "name": "Bronze Partner",
          "code": "BRONZE",
          "level": 1
        },
        "toRank": {
          "name": "Silver Partner",
          "code": "SILVER",
          "level": 2
        },
        "changeType": "PROMOTION",
        "qualificationSnapshot": {
          "careerPoints": 50000,
          "directReferrals": 10,
          "groupVolume": 250000
        },
        "periodId": "2024-01",
        "createdAt": "2024-01-10T14:30:00Z"
      },
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440000",
        "fromRank": null,
        "toRank": {
          "name": "Bronze Partner",
          "code": "BRONZE",
          "level": 1
        },
        "changeType": "INITIAL",
        "qualificationSnapshot": {
          "careerPoints": 0,
          "directReferrals": 0,
          "groupVolume": 0
        },
        "periodId": null,
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 2,
      "page": 1,
      "pageSize": 10,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

Эндпоинты баланса и выплат

GET /api/v1/mlm/balance

Получение деталей баланса.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface BalanceResponse {
  availableBalance: number;
  pendingBalance: number;
  totalEarned: number;
  totalWithdrawn: number;
  careerPoints: {
    total: number;
    currentPeriod: number;
  };
  currency: string;
  lastCalculatedAt: string | null;
  minimumPayout: number;
  canRequestPayout: boolean;
  payoutRestrictions: string[];
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/balance \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "availableBalance": 45000,
    "pendingBalance": 15000,
    "totalEarned": 180000,
    "totalWithdrawn": 120000,
    "careerPoints": {
      "total": 75000,
      "currentPeriod": 12500
    },
    "currency": "RUB",
    "lastCalculatedAt": "2024-01-15T23:59:59Z",
    "minimumPayout": 100,
    "canRequestPayout": true,
    "payoutRestrictions": []
  }
}

GET /api/v1/mlm/payouts

Список запросов на выплату.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

Параметры запроса

Параметр	Тип	Описание
page	number	Номер страницы (опционально)
pageSize	number	Элементов на странице, макс. 50 (опционально)
status	string	Фильтр: 'PENDING', 'APPROVED', 'PROCESSING', 'COMPLETED', 'REJECTED', 'CANCELLED', 'ALL' (опционально)

Ответ (200 OK)

typescript

interface PayoutsResponse {
  payouts: Payout[];
}

interface Payout {
  id: string;
  amount: number;
  currency: string;
  method: {
    type: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
    maskedDetails: string;
  };
  status: 'PENDING' | 'APPROVED' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'CANCELLED';
  rejectionReason: string | null;
  externalReference: string | null;
  processedAt: string | null;
  completedAt: string | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные параметры запроса
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер

Пример

Запрос:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/payouts?status=ALL&page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "payouts": [
      {
        "id": "mm0e8400-e29b-41d4-a716-446655440001",
        "amount": 30000,
        "currency": "RUB",
        "method": {
          "type": "BANK_CARD",
          "maskedDetails": "**** **** **** 1234"
        },
        "status": "COMPLETED",
        "rejectionReason": null,
        "externalReference": "PAY-2024011501234",
        "processedAt": "2024-01-15T10:00:00Z",
        "completedAt": "2024-01-15T10:05:00Z",
        "createdAt": "2024-01-14T18:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 12,
      "page": 1,
      "pageSize": 10,
      "totalPages": 2,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

POST /api/v1/mlm/payouts/request

Запрос на выплату.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 1 запрос в минуту (финансовый эндпоинт)

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

typescript

interface PayoutRequestBody {
  amount: number;                 // Должно быть >= минимальной суммы выплаты
  currency?: string;              // По умолчанию валюта аккаунта (RUB)
  methodType: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
  // Использовать сохраненные данные для выплаты или указать новые
  useSavedDetails?: boolean;      // Использовать сохраненные данные для выплаты
  // Или указать данные явно:
  details?: {
    cardNumber?: string;          // Для BANK_CARD
    bankName?: string;            // Для BANK_TRANSFER
    bankBik?: string;             // Для BANK_TRANSFER
    accountNumber?: string;       // Для BANK_TRANSFER
    walletType?: string;          // Для EWALLET
    walletId?: string;            // Для EWALLET
  };
}

Параметры запроса

Нет

Ответ (201 Created)

typescript

interface PayoutRequestResponse {
  payoutId: string;
  amount: number;
  currency: string;
  method: {
    type: string;
    maskedDetails: string;
  };
  status: 'PENDING';
  estimatedProcessingTime: string;
  newAvailableBalance: number;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные входные данные
400	AMOUNT_BELOW_MINIMUM	Сумма ниже минимального порога выплаты
400	INSUFFICIENT_BALANCE	Недостаточно доступного баланса
400	PAYOUT_DETAILS_REQUIRED	Данные для выплаты не указаны и не сохранены
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер
403	KYC_REQUIRED	Требуется KYC верификация для выплат
409	PAYOUT_ALREADY_PENDING	Запрос на выплату уже на рассмотрении
429	RATE_LIMIT_EXCEEDED	Слишком много запросов на выплату

Пример

Запрос:

bash

curl -X POST https://api.iwm-platform.com/api/v1/mlm/payouts/request \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "methodType": "BANK_CARD",
    "useSavedDetails": true
  }'

Ответ:

json

{
  "success": true,
  "data": {
    "payoutId": "nn0e8400-e29b-41d4-a716-446655440001",
    "amount": 25000,
    "currency": "RUB",
    "method": {
      "type": "BANK_CARD",
      "maskedDetails": "**** **** **** 1234"
    },
    "status": "PENDING",
    "estimatedProcessingTime": "1-3 business days",
    "newAvailableBalance": 20000,
    "createdAt": "2024-01-15T19:00:00Z"
  }
}

GET /api/v1/mlm/payouts/:id

Получение деталей выплаты.

Аутентификация: Обязательна (Партнер)

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Параметры пути

Параметр	Тип	Описание
id	string (UUID)	ID запроса на выплату

Тело запроса

Нет

Параметры запроса

Нет

Ответ (200 OK)

typescript

interface PayoutDetailsResponse {
  id: string;
  amount: number;
  currency: string;
  method: {
    type: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
    maskedDetails: string;
  };
  status: 'PENDING' | 'APPROVED' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'CANCELLED';
  statusHistory: {
    status: string;
    changedAt: string;
    changedBy: string | null;
    note: string | null;
  }[];
  rejectionReason: string | null;
  externalReference: string | null;
  processedBy: string | null;
  processedAt: string | null;
  completedAt: string | null;
  createdAt: string;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
403	NOT_A_PARTNER	Пользователь не зарегистрирован как партнер
404	PAYOUT_NOT_FOUND	Запрос на выплату не найден

Пример

Запрос:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/payouts/mm0e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

json

{
  "success": true,
  "data": {
    "id": "mm0e8400-e29b-41d4-a716-446655440001",
    "amount": 30000,
    "currency": "RUB",
    "method": {
      "type": "BANK_CARD",
      "maskedDetails": "**** **** **** 1234"
    },
    "status": "COMPLETED",
    "statusHistory": [
      {
        "status": "PENDING",
        "changedAt": "2024-01-14T18:00:00Z",
        "changedBy": null,
        "note": "Payout request created"
      },
      {
        "status": "APPROVED",
        "changedAt": "2024-01-15T09:00:00Z",
        "changedBy": "Admin User",
        "note": "Approved for processing"
      },
      {
        "status": "PROCESSING",
        "changedAt": "2024-01-15T10:00:00Z",
        "changedBy": "System",
        "note": "Sent to payment processor"
      },
      {
        "status": "COMPLETED",
        "changedAt": "2024-01-15T10:05:00Z",
        "changedBy": "System",
        "note": "Payment confirmed"
      }
    ],
    "rejectionReason": null,
    "externalReference": "PAY-2024011501234",
    "processedBy": "Admin User",
    "processedAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:05:00Z",
    "createdAt": "2024-01-14T18:00:00Z"
  }
}

API MLM ​

Общая информация ​

Базовый URL ​

Заголовок аутентификации ​

Формат ответа ​

Формат пагинации ​

Ограничения запросов ​

Заголовки ограничения запросов для финансовых эндпоинтов ​

Эндпоинты партнера ​

POST /api/v1/mlm/partner/register ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (201 Created) ​

Ответы с ошибками ​

Пример ​

GET /api/v1/mlm/partner/me ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

PATCH /api/v1/mlm/partner/me ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

GET /api/v1/mlm/partner/network ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

GET /api/v1/mlm/partner/network/stats ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

Эндпоинты реферальных ссылок ​

GET /api/v1/mlm/referrals/links ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

POST /api/v1/mlm/referrals/links ​

Заголовки запроса ​

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

Параметры запроса ​

Ответ (201 Created) ​

Ответы с ошибками ​

Пример ​

GET /api/v1/mlm/referrals/links/:id/stats ​

Заголовки запроса ​

Параметры пути ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

DELETE /api/v1/mlm/referrals/links/:id ​

Заголовки запроса ​

Параметры пути ​

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

Параметры запроса ​

Ответ (200 OK) ​

Ответы с ошибками ​

Пример ​

Эндпоинты комиссий ​

GET /api/v1/mlm/commissions ​

Заголовки запроса ​

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

Параметры запроса ​

API MLM

Общая информация

Базовый URL

Заголовок аутентификации

Формат ответа

Формат пагинации

Ограничения запросов

Заголовки ограничения запросов для финансовых эндпоинтов

Эндпоинты партнера

POST /api/v1/mlm/partner/register

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (201 Created)

Ответы с ошибками

Пример

GET /api/v1/mlm/partner/me

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

PATCH /api/v1/mlm/partner/me

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

GET /api/v1/mlm/partner/network

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

GET /api/v1/mlm/partner/network/stats

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

Эндпоинты реферальных ссылок

GET /api/v1/mlm/referrals/links

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

POST /api/v1/mlm/referrals/links

Заголовки запроса

Тело запроса

Параметры запроса

Ответ (201 Created)

Ответы с ошибками

Пример

GET /api/v1/mlm/referrals/links/:id/stats

Заголовки запроса

Параметры пути

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

DELETE /api/v1/mlm/referrals/links/:id

Заголовки запроса

Параметры пути

Тело запроса

Параметры запроса

Ответ (200 OK)

Ответы с ошибками

Пример

Эндпоинты комиссий

GET /api/v1/mlm/commissions

Заголовки запроса

Тело запроса

Параметры запроса