Admin User Management Endpoints

Аудитория: разработчики, разработчики админских панелей Последнее обновление: 2025-11-17 Краткое содержание: Детальная документация Admin User Management endpoints — просмотр пользователей, детали, обновление статуса, управление разрешениями. Полное руководство по интеграции для админских панелей.

---

Обзор Endpoints

Метод	Endpoint	Описание	Auth Required	Permission
GET	/api/admin/users	Список всех пользователей	✅ Admin	users:read
GET	/api/admin/users/:id	Детали пользователя	✅ Admin	users:read
PUT	/api/admin/users/:id	Обновить статус пользователя	✅ Admin	users:write
DELETE	/api/admin/users/:id	Деактивировать пользователя	✅ Admin	users:delete

---

👥 GET /api/admin/users

Получить постраничный список всех пользователей платформы с фильтрацией.

Запрос

GET /api/admin/users?page=1&limit=50&status=active&search=john
Authorization: Bearer <admin_jwt_token>

Заголовки:

Заголовок	Значение	Обязательно	Описание
Authorization	Bearer <admin_token>	✅ Да	Admin JWT токен

Query параметры:

Параметр	Тип	Обязательно	Описание	По умолчанию
page	number	❌ Нет	Номер страницы (начинается с 1)	1
limit	number	❌ Нет	Элементов на странице (макс: 100)	50
status	string	❌ Нет	Фильтр по статусу: active, suspended, inactive	Все
search	string	❌ Нет	Поиск по email, wallet адресу или имени	-
sortBy	string	❌ Нет	Поле сортировки: createdAt, lastLoginAt, totalInvested	createdAt
orderBy	string	❌ Нет	Порядок сортировки: asc, desc	desc
minInvestment	string	❌ Нет	Фильтр минимальной общей инвестированной суммы	-
registeredAfter	string	❌ Нет	Фильтр пользователей зарегистрированных после даты (ISO 8601)	-

Ответ

Успех (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "user_123abc",
      "email": "john@example.com",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "status": "active",
      "emailVerified": true,
      "createdAt": "2025-09-15T10:00:00Z",
      "lastLoginAt": "2025-10-03T12:30:00Z",
      "stats": {
        "totalInvested": "5000.00",
        "totalWithdrawn": "500.00",
        "totalEarnings": "150.50",
        "activeInvestments": 2,
        "lifetimeTransactions": 15
      },
      "riskProfile": {
        "level": "medium",
        "score": 5,
        "strategies": ["balanced-10", "conservative-5"]
      }
    },
    {
      "id": "user_456def",
      "email": "jane@example.com",
      "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "status": "active",
      "emailVerified": false,
      "createdAt": "2025-10-01T14:00:00Z",
      "lastLoginAt": "2025-10-02T09:15:00Z",
      "stats": {
        "totalInvested": "1000.00",
        "totalWithdrawn": "0.00",
        "totalEarnings": "5.50",
        "activeInvestments": 1,
        "lifetimeTransactions": 3
      },
      "riskProfile": {
        "level": "low",
        "score": 2,
        "strategies": ["conservative-5"]
      }
    }
  ],
  "summary": {
    "totalUsers": 523,
    "activeUsers": 480,
    "suspendedUsers": 3,
    "inactiveUsers": 40,
    "totalPlatformTVL": "8500000.00",
    "averageInvestmentPerUser": "16284.80"
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 523,
    "totalPages": 11,
    "hasNext": true,
    "hasPrevious": false
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
data[].stats.totalInvested	string	Пожизненная общая инвестированная сумма (SafeDecimal)
data[].stats.totalEarnings	string	Пожизненные доходы (SafeDecimal)
data[].riskProfile.level	string	Толерантность к риску: low, medium, high
summary.totalPlatformTVL	string	Общая заблокированная стоимость всех пользователей

Ошибки:

Код статуса	Код ошибки	Описание
401	TOKEN_EXPIRED	Admin JWT токен истёк
403	PERMISSION_DENIED	Недостаточно разрешений (требуется users:read)
400	INVALID_PAGINATION	Невалидные page или limit

Пример cURL

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."

# Получить всех активных пользователей
curl -X GET "https://app.saga.surf/api/admin/users?status=active" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Поиск пользователей
curl -X GET "https://app.saga.surf/api/admin/users?search=john@example.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Пользователи с крупными инвестициями (> $10K)
curl -X GET "https://app.saga.surf/api/admin/users?minInvestment=10000&sortBy=totalInvested&orderBy=desc" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Пример TypeScript

const fetchUsers = async (filters = {}) => {
  const params = new URLSearchParams({
    page: '1',
    limit: '50',
    ...filters
  });

  const response = await fetch(`/api/admin/users?${params}`, {
    headers: {
      'Authorization': `Bearer ${adminToken}`
    }
  });

  const { data: users, summary, pagination } = await response.json();

  console.log('Platform Summary:');
  console.log('  Total Users:', summary.totalUsers);
  console.log('  Active:', summary.activeUsers);
  console.log('  Platform TVL: $', summary.totalPlatformTVL);

  users.forEach(user => {
    console.log(`\n${user.email} (${user.status})`);
    console.log(`  Invested: $${user.stats.totalInvested}`);
    console.log(`  Earnings: $${user.stats.totalEarnings}`);
    console.log(`  Last Login: ${user.lastLoginAt}`);
  });

  return { users, summary, pagination };
};

---

GET /api/admin/users/:id

Получить детальную информацию о конкретном пользователе.

Запрос

GET /api/admin/users/user_123abc
Authorization: Bearer <admin_jwt_token>

Path параметры:

Параметр	Тип	Обязательно	Описание
id	string	✅ Да	ID пользователя (например, user_123abc)

Ответ

Успех (200 OK):

{
  "success": true,
  "data": {
    "id": "user_123abc",
    "email": "john@example.com",
    "emailVerified": true,
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "status": "active",
    "createdAt": "2025-09-15T10:00:00Z",
    "lastLoginAt": "2025-10-03T12:30:00Z",
    "profile": {
      "name": "John Doe",
      "preferences": {
        "language": "en",
        "currency": "USD",
        "notifications": {
          "email": true,
          "push": false
        }
      }
    },
    "stats": {
      "totalInvested": "5000.00",
      "currentBalance": "5150.50",
      "totalWithdrawn": "500.00",
      "totalEarnings": "150.50",
      "activeInvestments": 2,
      "closedInvestments": 1,
      "lifetimeTransactions": 15,
      "failedTransactions": 0
    },
    "investments": [
      {
        "id": "inv_abc123",
        "strategyId": "balanced-10",
        "amount": "3000.00",
        "currentValue": "3150.25",
        "earnings": "150.25",
        "status": "active",
        "createdAt": "2025-09-20T14:00:00Z"
      },
      {
        "id": "inv_def456",
        "strategyId": "conservative-5",
        "amount": "2000.00",
        "currentValue": "2050.50",
        "earnings": "50.50",
        "status": "active",
        "createdAt": "2025-10-01T10:00:00Z"
      }
    ],
    "recentActivity": [
      {
        "type": "investment",
        "description": "Invested $2000 in Conservative 5% APY",
        "timestamp": "2025-10-01T10:00:00Z"
      },
      {
        "type": "earning",
        "description": "Daily yield: +$5.50",
        "timestamp": "2025-10-03T00:00:00Z"
      }
    ],
    "riskProfile": {
      "level": "medium",
      "score": 5,
      "strategies": ["balanced-10", "conservative-5"],
      "largestInvestment": "3000.00",
      "preferredStrategy": "balanced-10"
    },
    "compliance": {
      "kycStatus": "not_required",
      "amlChecks": "passed",
      "ipAddress": "203.0.113.45",
      "country": "United States",
      "registrationSource": "organic"
    }
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
data.investments	array	Активные инвестиции пользователя
data.recentActivity	array	Лог недавней активности пользователя
data.riskProfile	object	Оценка риска пользователя
data.compliance	object	Информация о KYC/AML соответствии

Ошибки:

Код статуса	Код ошибки	Описание
403	PERMISSION_DENIED	Недостаточно разрешений
404	USER_NOT_FOUND	ID пользователя не существует

Пример cURL

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET https://app.saga.surf/api/admin/users/user_123abc \
  -H "Authorization: Bearer $ADMIN_TOKEN"

---

✏️ PUT /api/admin/users/:id

Обновить статус пользователя или настройки.

Запрос

PUT /api/admin/users/user_123abc
Authorization: Bearer <admin_jwt_token>
Content-Type: application/json

{
  "status": "suspended",
  "reason": "Suspicious activity detected",
  "notifyUser": true
}

Схема тела запроса:

Поле	Тип	Обязательно	Описание
status	string	⚠️ Условно	Новый статус: active, suspended, inactive
reason	string	⚠️ Условно	Обязателен если status = "suspended"
notifyUser	boolean	❌ Нет	Отправить email уведомление (по умолчанию: true)

Ответ

Успех (200 OK):

{
  "success": true,
  "data": {
    "id": "user_123abc",
    "email": "john@example.com",
    "status": "suspended",
    "updatedAt": "2025-10-03T12:34:56Z",
    "updatedBy": "admin_456def",
    "statusHistory": [
      {
        "status": "active",
        "changedAt": "2025-09-15T10:00:00Z",
        "changedBy": "system"
      },
      {
        "status": "suspended",
        "reason": "Suspicious activity detected",
        "changedAt": "2025-10-03T12:34:56Z",
        "changedBy": "admin_456def"
      }
    ]
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Ошибки:

Код статуса	Код ошибки	Описание
400	INVALID_STATUS	Невалидное значение статуса
400	REASON_REQUIRED	Причина обязательна для suspension
403	PERMISSION_DENIED	Недостаточно разрешений (требуется users:write)
404	USER_NOT_FOUND	ID пользователя не существует

Пример cURL

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X PUT https://app.saga.surf/api/admin/users/user_123abc \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended",
    "reason": "Suspicious activity detected",
    "notifyUser": true
  }'

---

DELETE /api/admin/users/:id

Деактивировать аккаунт пользователя (soft delete).

Запрос

DELETE /api/admin/users/user_123abc
Authorization: Bearer <admin_jwt_token>

Query параметры:

Параметр	Тип	Обязательно	Описание
permanent	boolean	❌ Нет	Постоянное удаление (по умолчанию: false, soft delete)

Ответ

Успех (200 OK):

{
  "success": true,
  "data": {
    "userId": "user_123abc",
    "email": "john@example.com",
    "status": "inactive",
    "deactivatedAt": "2025-10-03T12:34:56Z",
    "deactivatedBy": "admin_456def",
    "finalStats": {
      "totalInvested": "5000.00",
      "totalWithdrawn": "5150.50",
      "totalEarnings": "150.50"
    }
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Ошибки:

Код статуса	Код ошибки	Описание
403	PERMISSION_DENIED	Недостаточно разрешений (требуется users:delete)
404	USER_NOT_FOUND	ID пользователя не существует
422	ACTIVE_INVESTMENTS_EXIST	Нельзя удалить пользователя с активными инвестициями

---

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

Другие Admin Endpoints:

• Admin Auth - Админская аутентификация
• Admin Investments - Управление инвестициями
• Admin Dashboard - Метрики панели управления

Архитектура:

---

---

---

📋 Метаданные

Версия: 2.6.268

Обновлено: 2025-10-21

Статус: Published

---