---
title: "API администрирования"
description: "Проверенные маршруты `/api/admin/*` для управления пользователями, модерацией, заказами, настройками платформы и Email CRM"
locale: "ru"
---
# API администрирования

> **Info**
> Фильтруйте по **Founder** / **Developer** в боковом меню. В старых версиях упоминались **12 конечных точек**, придуманные маршруты `GET /api/admin/users` (список/поиск), `GET /api/admin/analytics`, IP whitelisting и отдельное ограничение по частоте для админов — **ничего из этого не подтверждено** в репозитории. Ниже перечислено то, что реально доступно в `app/api/admin/**/route.ts` начиная с v1.6.4.

Админ-маршруты обслуживают **консоль администратора** (`/admin/*`): роли пользователей, модерация сущностей, верификационное управление, статусы заказов, бренд/AI настройки платформы, пайплайны ProcessConductor, инструменты Web3-деска и Email AI-CRM. Все браузерные запросы используют **Auth.js session cookies** на том же домене — см. [API reference](/docs/api.md).

## Уровни доступа

| Проверка | Роли | Обычные маршруты |
|----------|------|------------------|
| `isPlatformAdmin()` | `admin`, `superadmin` | Пользователи, заказы, модерация, верификация |
| `isSuperadmin()` / `requireSuperadminApi()` | только `superadmin` | Настройки платформы, процессы, Web3-деск, сохранение бренда |
| Проверки в сервисе | Админ в доменном сервисе | Очередь модерации, действия по верификации |
| `requireEmailAdmin()` | Админ платформы + email CRM | `/api/admin/email/*` |

SSOT: `features/auth/user-role.ts` — роли в нижнем регистре (`visitor` … `superadmin`).

### For founders

## Что операторы контролируют через API администрирования

Эти HTTP-обработчики поддерживают кнопки в UI администратора — вручную вы редко их вызываете, только для автоматизации.

  
- **[Консоль администратора](/docs/features/admin.md)** — Трёхпанельная навигация с учётом ролей, вкладки Security hub, оболочка Email CRM — основной UI для всех этих API.

  
- **[Стол пользователя](/docs/features/admin.md)** — Просмотр и редактирование одного пользователя, смена роли, ручная выдача бейджа верификации, удаление аккаунта (не своего), вкладка Платежи (членство + пополнение счёта).

  
- **[Trust & Safety](/docs/features/admin.md)** — Панель безопасности (антифрод / верификация / события), очередь модерации, процедуры KYC.

  
- **[ERP магазина](/docs/features/store.md)** — Изменение статуса заказа: `new` → `paid` → `processing` → `shipped` → `completed` / `canceled`.

  
- **[Email AI-CRM](/docs/api/email-ai-crm.md)** — Потоки, черновики, задачи, аналитика — отдельное email пространство для админов.

  
- **[Аналитика платформы](/docs/deployment/monitoring.md)** — Дашборд находится по `/admin/analytics` — это не монолитный `/api/admin/analytics`.

### Типовые сценарии работы оператора

- **Проверить платежи** — Админ → Пользователи → Глаз → вкладка Платежи загружает `GET /api/admin/users/{id}/payments` (назначения: `membership_upgrade`, `wallet_topup` из `payment_transactions`).
- **Повысить роль участника** — через UI администратора `PUT /api/admin/users/{id}/role` или наследованный `POST /api/admin/set-user-role`.
- **Обработать очередь верификации** — `/admin/security?tab=verification` (старый `/admin/verification` перенаправляет сюда) → `POST /api/admin/verification/procedures/{n}/{action}` (`approve`, `reject`, `request-info`, `under-review`).
- **Заблокировать злонамеренную сущность** — очередь модерации → `POST /api/admin/entity-moderation/block` с `entityId` и `reason`.
- **Сохранить новый бренд (цвета)** — настройки superadmin → `POST /api/admin/whitelabel/save` (редирект на настройки).
- **Установить курс RING/USD** — Web3-деск → `POST /api/admin/web3/settings` с `{ "nativePerMainCurrency": "..." }`; хранится в коллекции `platform_settings` в namespace `web3`.

> **Warning**
> Изменения только для **superadmin** (AI-ключи, JSON бренда, запуск пайплайнов вручную, курс RING) влияют на всех пользователей — ограничьте количество ролей `superadmin` в боевых клонах.

### For developers

## Схема авторизации

```mermaid
sequenceDiagram

  participant C as Клиент (cookie)

  participant R as /api/admin/*

  participant A as auth()

  participant S as Доменный сервис

  C->>R: fetch credentials include

  R->>A: session

  alt не админ платформы

    R-->>C: 401 / 403

  else авторизован

    R->>S: Zod-валидированный body

    S-->>R: результат

    R-->>C: JSON
```

{`curl -s "http://localhost:3000/api/admin/entity-moderation" \\
  -H "Cookie: authjs.session-token=ВАШ_SESSION_COOKIE" | jq .`}

Глобального ограничения частоты для admin-маршрутов в `app/api/admin/*` **нет**. Добавляйте защиту на уровне edge/reverse proxy по ситуации.

## Реестр маршрутов (только подтверждённые)

### Пользователи и роли

| Метод | Путь | Авторизация | Примечания |
|-------|------|-------------|------------|
| GET | `/api/admin/users/[id]` | Админ платформы | JSONB-док пользователя, пароли скрыты |
| GET | `/api/admin/users/[id]/payments` | Админ платформы | Строки платежей (`membership_upgrade`, `wallet_topup`); query: `?limit=` (до 100), `?purposes=a,b` |
| DELETE | `/api/admin/users/[id]` | Админ платформы | Самостоятельное удаление невозможно |
| PUT | `/api/admin/users/[id]/role` | Админ платформы | Body: `{ "role": "member" }` |
| PUT | `/api/admin/users/[id]/verification` | Ручная верификация | Body: `{ "isVerified": true, ... }` |
| POST | `/api/admin/set-user-role` | Админ платформы | Устарело: `{ "uid", "role" }`; запрещает самопонижение |

**НЕ реализовано:** `GET /api/admin/users` (список/поиск) — используйте UI администратора или DatabaseService для своих инструментов.

**UI для вкладки Платежи:** компонент `features/auth/components/admin-user-detail-sheet.tsx` (открывается из `admin-user-manager.tsx` по кнопке-глаз), делает запрос `/api/admin/users/${user.id}/payments?limit=50`.

### Модерация и верификация

| Метод | Путь | Примечания |
|-------|------|------------|
| GET | `/api/admin/entity-moderation` | `{ items: EntityModerationQueueItem[] }` |
| POST | `/api/admin/entity-moderation/block` | `{ entityId, reason }` |
| GET | `/api/admin/verification/queue` | `{ success, queue }` |
| POST | `/api/admin/verification/procedures/[procedureNumber]/[action]` | `approve` \| `reject` \| `request-info` \| `under-review` |

### Магазин

| Метод | Путь | Тело запроса |
|-------|------|-------------|
| POST | `/api/admin/orders/[id]/status` | `{ "status": "processing" }` (enum: `new`, `paid`, `processing`, `shipped`, `completed`, `canceled`) |

### Настройки платформы (superadmin)

| Метод | Путь | Примечания |
|-------|------|------------|
| GET | `/api/admin/platform-settings?namespace=ai\|branding` | Чтение namespace |
| PUT | `/api/admin/platform-settings` | JSON body: `{ namespace, data, secrets? }` |
| POST | `/api/admin/whitelabel/save` | POST формы → цвета бренда → редирект |
| POST | `/api/admin/save` | Устарело: сохранение бренда (JSON, редирект) |

**Персистентность:** сервис `features/admin/platform-settings/platform-settings-service.ts` читает/записывает коллекцию `platform_settings` через `db()` из `@/lib/database`. Namespace `ai` и `branding` используют методы `readDoc` / `updateDoc` / `createDoc` и кэшируются модулем `platform-settings-cache.ts`.

| Env | Эффект |
|-----|--------|
| `PLATFORM_SETTINGS_DISABLE_DB=true` | Чтение — дефолты/пусто, запись — ошибка. Для тестов/clone без БД. |

`importPlatformSettingsFromEnv()` подхватывает настройки из env и `ring-config.json` при отсутствии строк в БД.

### Процессы ProcessConductor (superadmin)

| Метод | Путь | Назначение |
|-------|------|------------|
| GET | `/api/admin/processes` | Список пайплайнов |
| POST | `/api/admin/processes/[id]/run` | Ручной запуск пайплайна |
| GET | `/api/admin/processes/[id]/history` | История запусков |

Кроны используют `/api/cron/*` + `CRON_SECRET` — подробнее см. ProcessConductor в [Monitoring](/docs/deployment/monitoring.md).

### Web3-деск (superadmin)

| Метод | Путь | Примечания |
|-------|------|------------|
| GET | `/api/admin/web3/settings` | Курс оракула, настройка, аудит-лог, газ-резерв |
| POST | `/api/admin/web3/settings` | `{ "nativePerMainCurrency": "..." }` |
| GET | `/api/admin/web3/gas-reserve` | Баланс fee-payer Solana |

**Хранение курса оракула:** сервис `features/wallet/services/native-token-oracle.ts` хранит `nativePerMainCurrency` и аудит в документе `platform_settings` id `web3` (через `db()`). Если `PLATFORM_SETTINGS_DISABLE_DB=true` — чтение из `RING_ORACLE_DEFAULT_RATE` (`100`), запись блокируется.

### Email AI-CRM (админ платформы)

Полная таблица маршрутов: **[Email AI-CRM API](/docs/api/email-ai-crm.md)** — потоки, черновики, задачи, контакты, `GET /api/admin/email/analytics?range=7d`.

### Обслуживание (superadmin, будьте осторожны)

| Метод | Путь | Назначение |
|-------|------|------------|
| POST | `/api/admin/migrate-users` | Разовая миграция пользователей — не используйте как рутину |

## Аналитика (НЕ через `/api/admin`)

| Метод | Путь | Авторизация |
|-------|------|-------------|
| GET | `/api/analytics/platform-stats` | Админ платформы |
| GET | `/api/analytics/web-vitals?scope=platform` | Админ платформы |
| GET | `/api/analytics/errors` | Админ платформы |

В UI: `/admin/analytics` → `getPlatformAnalytics()` (`features/analytics/services/get-platform-analytics.ts`).

### Пример — смена роли

### Войти как админ через браузер

Войдите под аккаунтом с ролью `admin` или `superadmin`.

### PUT — смена роли

{`curl -X PUT "http://localhost:3000/api/admin/users/USER_ID/role" \\
  -H "Content-Type: application/json" \\
  -H "Cookie: authjs.session-token=..." \\
  -d '{"role":"confidential"}'`}

### Проверить

Обновите пользователя или откройте Admin → Users; роль будет в нижнем регистре в `users.data.role`.

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

  
- **[API-индекс](/docs/api.md)** — Модель сессий и доменное деление.

  
- **[Email AI-CRM API](/docs/api/email-ai-crm.md)** — Все маршруты `/api/admin/email/*`.

  
- **[Модель безопасности](/docs/architecture/security.md)** — RBAC и уровни доступа.

  
- **[Мониторинг](/docs/deployment/monitoring.md)** — Аналитика админа и логирование ошибок.

  
- **[Wallet API — оракул](/docs/api/wallet.md)** — Котировки для пользователей; админский rate см. в Web3-деске выше.