openapi: 3.2.0 info: title: UChecker Аутентификация API description: "\n## О сервисе\n\nUChecker — платформа валидации email-адресов для маркетологов, ESP-провайдеров и разработчиков. Проверяйте email поштучно или массово — до миллионов адресов за одну задачу. API определяет существование почтового ящика на уровне SMTP, DNS/MX и провайдера, возвращая однозначный результат: `good` или `bad`.\n\nБазовый URL: `https://api.uchecker.net`\n\n---\n\n## Быстрый старт\n\n**Шаг 1.** Получите API ключ — он доступен в [личном кабинете](https://app.uchecker.net) сразу после регистрации.\n\n**Шаг 2.** Отправьте запрос на валидацию:\n```bash\ncurl -X POST https://api.uchecker.net/api/v1/validate/single \\\n -H \"x-api-key: ваш_ключ\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"user@example.com\"}'\n```\n\n**Шаг 3.** Получите результат по `task_id` из ответа:\n```bash\ncurl https://api.uchecker.net/api/v1/tasks/123/results \\\n -H \"x-api-key: ваш_ключ\"\n```\n\n---\n\n## Аутентификация\n\nAPI поддерживает два равноценных способа аутентификации. Используйте любой из них — оба дают полный доступ ко всем эндпоинтам.\n\n### API Key (рекомендуется для интеграций)\n\nПередайте ключ в заголовке `x-api-key`. Ключ не истекает и действует до ручного сброса.\n\n```\nx-api-key: uk_xxxxxxxxxxxxx\n```\n\n### Bearer Token (рекомендуется для фронтенд-приложений)\n\nПолучите JWT через `POST /auth/login`, передайте в заголовке `Authorization`.\n\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n```\n\n| Токен | Время жизни | Назначение |\n|-------|-------------|------------|\n| access_token | 1 час | Аутентификация запросов |\n| refresh_token | 7 дней | Обновление access_token через `POST /auth/refresh` |\n\n> **Совет:** при серверной интеграции используйте API Key — это проще и не требует управления токенами.\n\n---\n\n## Лимиты и тарификация\n\nUChecker работает по кредитной модели. Каждая проверка одного email-адреса списывает **1 кредит** с вашего баланса.\n\n- **Rate limits отсутствуют** — вы можете отправлять запросы с любой частотой.\n- Кредиты списываются в момент постановки email в очередь.\n- Email с невалидным синтаксисом (при массовой отправке) **не тарифицируются** и возвращаются в поле `invalid_details`.\n- Текущий баланс доступен через `GET /api/v1/account/balance`.\n\n---\n\n## Результаты валидации\n\nКаждый email получает одно из двух значений `validation_result`:\n\n| Результат | Описание |\n|-----------|----------|\n| `good` | Почтовый ящик существует и принимает почту. Адрес безопасен для рассылки. |\n| `bad` | Почтовый ящик не существует, отключён, или домен не принимает почту. |\n\nДля адресов со статусом `bad` в поле `result` указывается детальная причина: `mailbox_not_found`, `domain_not_found`, `smtp_rejected` и другие.\n\n---\n\n## Жизненный цикл задачи\n\nКаждый запрос на валидацию создаёт задачу (task), которая проходит через состояния:\n\n```\npending → processing → completed\n ↘ failed\n```\n\n| Состояние | Код | Описание |\n|-----------|-----|----------|\n| `pending` | 0 | Задача создана, ожидает начала обработки |\n| `processing` | 1 | Email-адреса проверяются. Прогресс доступен в поле `progress_percent` |\n| `completed` | 3 | Все адреса проверены. Результаты доступны для скачивания |\n| `failed` | -1 | Произошла ошибка. Обратитесь в поддержку с `task_id` |\n\n**Рекомендуемый polling-интервал:** каждые 5–10 секунд через `GET /api/v1/tasks/:taskId`. Или укажите `webhook_url` при создании задачи — мы отправим POST-запрос с результатами, когда задача завершится.\n\n---\n\n## Обработка ошибок\n\nAPI возвращает стандартные HTTP-коды и JSON-ответы:\n\n| Код | Значение | Когда возникает |\n|-----|----------|-----------------|\n| 200 | Успех | Запрос выполнен |\n| 400 | Ошибка запроса | Невалидные параметры, неверный формат данных |\n| 401 | Не авторизован | Отсутствует или неверный API ключ / JWT токен |\n| 403 | Доступ запрещён | Недостаточно кредитов на балансе |\n| 404 | Не найдено | Задача не существует или не принадлежит вашему аккаунту |\n| 500 | Внутренняя ошибка | Ошибка сервера — повторите запрос позже |\n\nТело ошибки всегда содержит поля `success: false` и `error` с человекочитаемым описанием.\n\n---\n\n## Поддержка\n\nПо вопросам интеграции и техническим вопросам: **support@uchecker.net**\n " version: 1.0.0 contact: {} servers: - url: https://api.uchecker.net description: Production tags: - name: Аутентификация description: Вход, регистрация, управление JWT-токенами и API ключами, привязка Telegram paths: /auth/login: post: description: 'Аутентификация по email и паролю. При успешном входе возвращает набор данных для работы с API. **Что возвращается:** - `access_token` — JWT токен для аутентификации запросов (время жизни: **1 час**). Передавайте в заголовке `Authorization: Bearer `. - `refresh_token` — токен для обновления access_token (время жизни: **7 дней**). Используйте `POST /auth/refresh`. - `api_key` — персональный API ключ для программного доступа. Не истекает. - `user` — информация об аккаунте. **Рекомендация:** Для серверных интеграций используйте API ключ (`x-api-key`) вместо JWT — это проще и не требует логики обновления токенов. JWT подходит для фронтенд-приложений, где нужна сессия с ограниченным временем жизни.' operationId: AuthController_login parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginDto' responses: '200': description: Успешная аутентификация. Ответ содержит JWT токены, API ключ и данные аккаунта. content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '401': description: Неверный email или пароль. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' summary: Вход по email и паролю tags: - Аутентификация /auth/refresh: post: description: 'Обменивает действующий refresh token на новую пару access + refresh токенов. Используется для продления сессии без повторного ввода пароля. **Ротация токенов:** При каждом вызове старый refresh token **немедленно аннулируется**, и выдаётся новый. Это обеспечивает безопасность: если refresh token скомпрометирован, он может быть использован только один раз. **Когда вызывать:** Вызывайте этот эндпоинт, когда access token истёк (ответ `401`) или заблаговременно — например, за 5 минут до истечения. Refresh token действует 7 дней. **Важно:** для вызова этого эндпоинта необходимо передать текущий access token в заголовке `Authorization`, даже если он просрочен — сервер проверяет его подпись, но не срок действия.' operationId: AuthController_refresh parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefreshTokenDto' responses: '200': description: Новая пара токенов. Старый refresh token аннулирован. content: application/json: schema: $ref: '#/components/schemas/RefreshTokenResponse' '401': description: Refresh token недействителен, просрочен или уже был использован. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' security: - bearer: [] summary: Обновить JWT токены tags: - Аутентификация /auth/telegram-login: post: description: 'Аутентификация по Telegram chat ID. Предназначен для интеграции с Telegram-ботом UChecker. **Как это работает:** 1. Пользователь взаимодействует с Telegram-ботом UChecker. 2. Бот получает `chat_id` пользователя и вызывает этот эндпоинт. 3. Если аккаунт с таким `chat_id` существует — возвращаются JWT токены и API ключ (аналогично `POST /auth/login`). **Требования:** Аккаунт должен быть предварительно привязан к Telegram через `POST /auth/link-telegram` или создан через бота. Если аккаунт не найден — возвращается ошибка 400. **Область применения:** этот эндпоинт используется внутренним Telegram-ботом и не предназначен для прямого вызова из пользовательских приложений.' operationId: AuthController_telegramLogin parameters: [] requestBody: required: true content: application/json: schema: type: object properties: telegram_id: type: string example: '123456789' description: Telegram chat ID пользователя (числовой, передаётся как строка) required: - telegram_id responses: '200': description: Успешная аутентификация. Ответ идентичен `POST /auth/login`. content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '400': description: Аккаунт с указанным Telegram chat ID не найден. Необходима привязка. summary: Вход через Telegram tags: - Аутентификация /auth/forgot-password: post: description: 'Инициирует процесс восстановления пароля. Если указанный email зарегистрирован, на него отправляется письмо со ссылкой для сброса (через тот же канал, что и подтверждение регистрации — Rusender). **Защита от перебора:** Эндпоинт всегда возвращает одно и то же сообщение, независимо от того, зарегистрирован email или нет. Это защищает от перечисления существующих аккаунтов. **Срок действия ссылки:** 60 минут с момента отправки письма. Повторный вызов выпускает новый токен — старая ссылка перестаёт работать. **Что происходит после сброса:** После успешной смены пароля (`POST /auth/reset-password`) все активные сессии аккаунта инвалидируются — refresh_token обнуляется. На всех устройствах потребуется повторный вход.' operationId: AuthController_forgotPassword parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ForgotPasswordDto' responses: '200': description: Запрос принят. Если email зарегистрирован — письмо отправлено. summary: Запросить сброс пароля tags: - Аутентификация /auth/reset-password: post: description: 'Завершает процесс сброса пароля. Принимает одноразовый токен из письма и новый пароль. **Поведение:** - Токен валидируется по сроку действия (60 минут). Просроченный или несуществующий токен — `400`. - При успехе пароль заменяется, токен обнуляется, все активные сессии завершаются (refresh_token = null). - Эндпоинт **не возвращает JWT** — пользователь должен войти с новым паролем через `POST /auth/login`.' operationId: AuthController_resetPassword parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResetPasswordDto' responses: '200': description: Пароль успешно изменён. '400': description: Токен недействителен или истёк. summary: Установить новый пароль по токену из письма tags: - Аутентификация /auth/reset-api-key: post: description: 'Генерирует новый API ключ и **немедленно аннулирует** предыдущий. Все запросы со старым ключом начнут возвращать `401 Unauthorized`. **Когда использовать:** - Подозрение на компрометацию ключа. - Ротация ключей в рамках политики безопасности. - Передача доступа другому разработчику. **Важные моменты:** - Требуется JWT аутентификация (`Authorization: Bearer `). API ключ нельзя использовать для его собственного сброса. - Новый ключ возвращается в ответе **один раз**. Сохраните его — в дальнейшем он отображается только в маскированном виде. - Все активные интеграции, использующие старый ключ, перестанут работать. Обновите ключ во всех системах.' operationId: AuthController_resetApiKey parameters: [] responses: '200': description: Новый API ключ сгенерирован. Старый ключ аннулирован. content: application/json: schema: $ref: '#/components/schemas/ResetApiKeyResponse' '401': description: JWT токен отсутствует, невалиден или просрочен. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' security: - bearer: [] summary: Сбросить и перегенерировать API ключ tags: - Аутентификация /auth/link-telegram: post: description: 'Начинает процесс привязки Telegram-аккаунта к веб-аккаунту UChecker. После привязки пользователь сможет входить через Telegram-бота и управлять задачами из мессенджера. **Пошаговый процесс привязки:** 1. Пользователь пишет команду `/link` в Telegram-бот UChecker и получает 6-значный код. 2. Пользователь вводит этот код в личном кабинете на сайте — приложение вызывает данный эндпоинт. 3. Бот отправляет пользователю запрос на подтверждение в Telegram. 4. Пользователь подтверждает в боте — привязка завершена. **Ошибки:** - Неверный или просроченный код — `400`. - Аккаунт уже привязан к другому Telegram — `400`. - Telegram-аккаунт уже привязан к другому веб-аккаунту — `400`.' operationId: AuthController_initiateLinkTelegram parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiateLinkDto' responses: '200': description: Запрос на привязку создан. Ожидается подтверждение в Telegram-боте. '400': description: Неверный/просроченный код, аккаунт уже привязан, или Telegram ID уже используется. security: - bearer: [] summary: Инициировать привязку Telegram аккаунта tags: - Аутентификация /auth/confirm-link: post: description: 'Завершает процесс привязки Telegram-аккаунта. Вызывается Telegram-ботом, когда пользователь нажимает кнопку «Подтвердить» или «Отклонить». **Внутренний эндпоинт:** Предназначен для вызова Telegram-ботом, а не пользовательскими приложениями напрямую. **Параметры:** - `request_id` — идентификатор запроса на привязку (из callback_data кнопки). - `chat_id` — Telegram chat ID для дополнительной верификации. - `confirmed` — `true` для подтверждения, `false` для отклонения. **Поведение:** При подтверждении (`confirmed: true`) Telegram chat ID привязывается к веб-аккаунту, и пользователь получает возможность входить через бота. При отклонении запрос аннулируется.' operationId: AuthController_confirmLink parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfirmLinkDto' responses: '200': description: Привязка подтверждена или отклонена. '400': description: Запрос на привязку не найден, истёк, или уже обработан. summary: Подтвердить или отклонить привязку Telegram (для бота) tags: - Аутентификация /auth/confirm-link-simple: post: description: 'Упрощённая версия подтверждения привязки Telegram — автоматически находит ожидающий запрос по `chat_id`, не требуя `request_id`. **Когда использовать:** Используйте этот эндпоинт вместо `POST /auth/confirm-link`, если у бота нет доступа к `request_id` из callback_data — например, при обработке текстовых команд вместо inline-кнопок. **Внутренний эндпоинт:** Предназначен для вызова Telegram-ботом. Если для указанного `chat_id` нет ожидающих запросов — возвращается ошибка 400.' operationId: AuthController_confirmLinkSimple parameters: [] requestBody: required: true content: application/json: schema: type: object properties: chat_id: type: number example: 123456789 description: Telegram chat ID пользователя confirmed: type: boolean example: true description: true — подтвердить привязку, false — отклонить required: - chat_id - confirmed responses: '200': description: Привязка подтверждена или отклонена. '400': description: Нет ожидающих запросов на привязку для указанного chat_id. summary: Подтвердить привязку по chat_id (упрощённая версия, для бота) tags: - Аутентификация /auth/pending-links: get: description: 'Возвращает список ожидающих (неподтверждённых) запросов на привязку Telegram-аккаунта для указанного `chat_id`. **Внутренний эндпоинт:** Используется Telegram-ботом для проверки наличия запросов перед показом кнопок подтверждения пользователю. **Типичный сценарий:** 1. Бот получает команду или callback от пользователя. 2. Бот вызывает этот эндпоинт, передавая `chat_id`. 3. Если есть ожидающие запросы — бот показывает кнопки «Подтвердить» / «Отклонить». 4. Если нет — бот сообщает, что запросов нет. Запросы на привязку имеют ограниченный срок действия. Просроченные запросы не возвращаются.' operationId: AuthController_getPendingLinks parameters: - name: chat_id required: true in: query schema: type: string responses: '200': description: Массив ожидающих запросов на привязку. Пустой массив, если запросов нет. summary: Проверить ожидающие запросы на привязку (для бота) tags: - Аутентификация /auth/register-with-code: post: description: 'Регистрация нового веб-аккаунта с одновременной привязкой к существующему Telegram-аккаунту. Позволяет пользователям бота получить полноценный веб-доступ к платформе. **Сценарий использования:** Пользователь начал работу через Telegram-бот и хочет зарегистрироваться на сайте, сохранив свой баланс и историю задач. **Как это работает:** 1. Пользователь запрашивает 6-значный код в Telegram-боте (команда `/link`). 2. На странице регистрации вводит email, пароль и код. 3. Система создаёт веб-аккаунт и привязывает его к Telegram-аккаунту. 4. Баланс кредитов и история задач из бота становятся доступны в веб-интерфейсе. **Без кода:** Если `telegram_code` не передан — создаётся обычный веб-аккаунт без привязки к Telegram. **Ошибки:** - `400` — код невалиден или просрочен. - `409` — email уже зарегистрирован, или Telegram-аккаунт уже привязан к другому веб-аккаунту.' operationId: AuthController_registerWithCode parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterWithCodeDto' responses: '200': description: Аккаунт создан. Если передан telegram_code — привязка к Telegram выполнена. '400': description: Telegram-код невалиден или просрочен. '409': description: 'Конфликт: email уже зарегистрирован или Telegram-аккаунт уже привязан.' summary: Регистрация с привязкой Telegram tags: - Аутентификация /api/v1/billing/history: get: description: 'Возвращает постраничный список всех платёжных транзакций для текущего аккаунта, отсортированных по дате — новые первыми. **Что включено в историю:** Каждая запись содержит сумму, статус, описание пакета, дату и идентификатор платежа. Отображаются транзакции во всех состояниях. **Статусы транзакций:** | Статус | Описание | |--------|----------| | `pending` | Платёж инициирован, ожидает подтверждения от платёжной системы | | `completed` | Платёж успешен, кредиты зачислены на баланс | | `failed` | Платёж отклонён платёжной системой | | `cancelled` | Платёж отменён пользователем или по таймауту | **Пагинация:** Используйте параметры `page` и `limit`. Ответ содержит объект `pagination` с полями `total` и `totalPages` для навигации.' operationId: BillingController_getPaymentHistory parameters: - name: limit required: false in: query description: 'Количество записей на странице. По умолчанию: 10.' schema: example: 10 type: number - name: page required: false in: query description: 'Номер страницы. Нумерация начинается с 1. По умолчанию: 1.' schema: example: 1 type: number responses: '200': description: Постраничный список транзакций с метаданными пагинации. content: application/json: schema: $ref: '#/components/schemas/PaymentHistoryResponse' '401': description: Не авторизован. Проверьте API ключ или JWT токен. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' security: - bearer: [] - api-key: [] summary: Получить историю платежей tags: - Аутентификация /api/v1/referral/click: post: description: 'Вызывается из браузера с `credentials: ''include''`. Записывает клик и устанавливает cookie атрибуции `uc_attr` сроком на 30 дней. Cookie не перезаписывается, если уже установлена: побеждает первый переход (first-click). Всегда возвращает `204` независимо от того, удалось ли опознать партнёра — иначе перебором можно было бы выяснить, какие коды заняты.' operationId: ReferralController_trackClick parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TrackClickDto' responses: '204': description: Запрос принят. summary: Зафиксировать переход по партнёрской ссылке tags: - Аутентификация /api/v1/referral/me: get: description: 'Если партнёрская программа для аккаунта не включена, возвращает только `{ enabled: false }` — дашборд по этому признаку скрывает раздел.' operationId: ReferralController_getMe parameters: [] responses: '200': description: '' security: - bearer: [] summary: 'Сводка партнёрского кабинета: код, ссылка, ставка, баланс и счётчики' tags: - Аутентификация /api/v1/referral/stats: get: description: Возвращает clicks, signups, payments, paying и earnings. Оплаты считаются по собственной дате, а не по дате регистрации реферала. operationId: ReferralController_getStats parameters: - name: group_by required: true in: query schema: example: utm_campaign type: string enum: - day - utm_source - utm_medium - utm_campaign - utm_content - utm_term - landing - name: from required: false in: query description: Формат YYYY-MM-DD schema: example: '2026-08-01' type: string - name: to required: false in: query description: Формат YYYY-MM-DD schema: example: '2026-08-31' type: string responses: '403': description: Партнёрская программа не включена для аккаунта. security: - bearer: [] summary: Статистика в разрезе даты, utm-метки или посадочной страницы tags: - Аутентификация /api/v1/referral/referrals: get: operationId: ReferralController_getReferrals parameters: - name: page required: false in: query schema: minimum: 1 default: 1 type: number - name: limit required: false in: query schema: minimum: 1 maximum: 100 default: 20 type: number responses: '403': description: Партнёрская программа не включена для аккаунта. security: - bearer: [] summary: Список приведённых пользователей. Email маскируется. tags: - Аутентификация /api/v1/referral/earnings: get: operationId: ReferralController_getEarnings parameters: - name: page required: false in: query schema: minimum: 1 default: 1 type: number - name: limit required: false in: query schema: minimum: 1 maximum: 100 default: 20 type: number responses: '403': description: Партнёрская программа не включена для аккаунта. security: - bearer: [] summary: Журнал начислений комиссии tags: - Аутентификация /api/v1/referral/admin/payouts: post: description: Деньги переводятся вне системы. Эта запись списывает сумму с доступного баланса. Идемпотентна по external_id, отклоняет сумму сверх баланса. operationId: ReferralAdminController_createPayout parameters: - name: x-admin-token in: header description: Админский токен из ADMIN_API_TOKEN required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayoutDto' responses: '400': description: Сумма превышает доступный баланс. '404': description: Партнёр не найден. summary: Зафиксировать выплату партнёру tags: - Аутентификация /api/v1/referral/admin/rate: patch: operationId: ReferralAdminController_updateRate parameters: - name: x-admin-token in: header description: Админский токен из ADMIN_API_TOKEN required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRateDto' responses: '404': description: Партнёр не найден. summary: Установить индивидуальную ставку комиссии партнёру tags: - Аутентификация /api/v1/referral/admin/access: patch: description: По умолчанию раздел скрыт у всех. Атрибуция и начисления при этом работают в фоне, поэтому при включении партнёр сразу видит накопленную историю. operationId: ReferralAdminController_setAccess parameters: - name: x-admin-token in: header description: Админский токен из ADMIN_API_TOKEN required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetReferralAccessDto' responses: '404': description: Партнёр не найден. summary: Включить или выключить партнёрский раздел для аккаунта tags: - Аутентификация /api/v1/referral/admin/earnings/{id}/reverse: post: description: Для возврата платежа или выявленного фрода. Баланс пересчитывается автоматически, поскольку он вычисляемый. operationId: ReferralAdminController_reverseEarning parameters: - name: x-admin-token in: header description: Админский токен из ADMIN_API_TOKEN required: true schema: type: string - name: id required: true in: path schema: type: string responses: '404': description: Активное начисление не найдено. summary: Откатить начисление tags: - Аутентификация components: schemas: ForgotPasswordDto: type: object properties: email: type: string example: user@example.com description: Email-адрес аккаунта. Если email зарегистрирован, на него будет отправлена ссылка для сброса пароля. required: - email LoginResponse: type: object properties: user: description: Информация об аккаунте пользователя allOf: - $ref: '#/components/schemas/UserInfo' api_key: type: string example: uk_xxxxxxxxxxxxx description: Персональный API ключ. Используйте в заголовке `x-api-key` для аутентификации запросов. Не имеет срока действия. access_token: type: string example: eyJhbGciOiJIUzI1NiIs... description: 'JWT access token. Время жизни: 1 час. Передавайте в заголовке `Authorization: Bearer `.' refresh_token: type: string example: eyJhbGciOiJIUzI1NiIs... description: 'JWT refresh token. Время жизни: 7 дней. Используйте для обновления access token через `POST /auth/refresh`.' required: - user - api_key - access_token - refresh_token UnauthorizedResponse: type: object properties: statusCode: type: number example: 401 description: HTTP-код ошибки message: type: string example: Не авторизован description: API ключ или JWT токен отсутствует, невалиден или просрочен. Проверьте заголовки `x-api-key` или `Authorization`. required: - statusCode - message ConfirmLinkDto: type: object properties: request_id: type: number example: 1 description: Идентификатор запроса на привязку. Получен из callback_data inline-кнопки в Telegram. chat_id: type: number example: 123456789 description: Telegram chat ID пользователя. Используется для дополнительной верификации запроса. confirmed: type: boolean example: true description: '`true` — подтвердить привязку, `false` — отклонить. При подтверждении Telegram-аккаунт привязывается к веб-аккаунту.' required: - request_id - chat_id - confirmed ResetApiKeyResponse: type: object properties: message: type: string example: API ключ успешно сброшен description: Подтверждение операции api_key: type: string example: uk_new_xxxxxxxxxxxxx description: Новый API ключ. Сохраните его — в дальнейшем он отображается только в маскированном виде. required: - message - api_key RefreshTokenResponse: type: object properties: access_token: type: string example: eyJhbGciOiJIUzI1NiIs... description: 'Новый JWT access token. Время жизни: 1 час.' refresh_token: type: string example: eyJhbGciOiJIUzI1NiIs... description: 'Новый JWT refresh token. Время жизни: 7 дней. Предыдущий refresh token аннулирован.' required: - access_token - refresh_token RegisterWithCodeDto: type: object properties: email: type: string example: user@example.com description: Email-адрес для нового веб-аккаунта. Должен быть уникальным. password: type: string example: password123 description: Пароль для нового аккаунта. Минимум 6 символов. telegram_code: type: number example: 123456 description: 6-значный код из Telegram-бота для привязки существующего бот-аккаунта к новому веб-аккаунту. Если не указан — создаётся обычный аккаунт без привязки к Telegram. required: - email - password LoginDto: type: object properties: email: type: string example: user@example.com description: Email-адрес, указанный при регистрации password: type: string example: password123 description: Пароль аккаунта required: - email - password InitiateLinkDto: type: object properties: telegram_code: type: number example: 123456 description: 6-значный числовой код, полученный от Telegram-бота UChecker командой `/link` required: - telegram_code UserInfo: type: object properties: id: type: number example: 1 description: Числовой идентификатор аккаунта email: type: string example: user@example.com description: Email-адрес аккаунта telegram_code: type: number example: 123456 description: 6-значный код для привязки Telegram-аккаунта. Присутствует, если аккаунт поддерживает Telegram-интеграцию. required: - id - email RefreshTokenDto: type: object properties: refresh_token: type: string description: Действующий refresh token, полученный при входе или предыдущем обновлении. Каждый refresh token можно использовать только один раз. example: eyJhbGciOiJIUzI1NiIs... required: - refresh_token ResetPasswordDto: type: object properties: token: type: string example: a1b2c3... description: Одноразовый токен из ссылки в письме. Действует 60 минут. password: type: string example: newpassword123 description: Новый пароль. Минимум 6 символов. required: - token - password PaginationInfo: type: object properties: page: type: number example: 1 description: Текущая страница limit: type: number example: 10 description: Количество записей на странице total: type: number example: 5 description: Общее количество записей totalPages: type: number example: 1 description: Общее количество страниц. Рассчитывается как `Math.ceil(total / limit)`. required: - page - limit - total - totalPages PaymentHistoryResponse: type: object properties: data: description: Массив транзакций. Отсортирован по дате — новые первыми. type: array items: $ref: '#/components/schemas/PaymentHistoryItem' pagination: description: Метаданные пагинации allOf: - $ref: '#/components/schemas/PaginationInfo' required: - data - pagination PaymentHistoryItem: type: object properties: id: type: number example: 1 description: Уникальный идентификатор транзакции amount: type: number example: 1000 description: Сумма платежа в рублях (RUB) status: type: string example: completed enum: - pending - completed - failed - cancelled description: 'Статус транзакции: `pending` (ожидает), `completed` (успешно), `failed` (отклонён), `cancelled` (отменён)' product_details: type: string example: 5000 addresses (5k) via freekassa from web description: 'Описание покупки: количество кредитов, платёжная система и источник (web/bot)' creation_date: format: date-time type: string example: '2024-01-01T12:00:00.000Z' description: Дата и время создания транзакции. Формат ISO 8601. payment_id: type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: Уникальный идентификатор платежа в платёжной системе required: - id - amount - status - product_details - creation_date - payment_id TrackClickDto: type: object properties: ref: type: string example: uc00042 description: Реферальный код партнёра из параметра ?ref= utm_source: type: string example: vc.ru utm_medium: type: string example: article utm_campaign: type: string example: may utm_content: type: string utm_term: type: string landing_path: type: string example: /blog/proverka-email-adresov description: Путь посадочной страницы referer: type: string CreatePayoutDto: type: object properties: partner_pk: type: number example: 42 description: account_pk партнёра amount: type: number example: 3400 description: Выплаченная сумма в рублях external_id: type: string example: sbp-2026-08-14-001 description: Ключ идемпотентности. Повтор с тем же значением не создаст вторую выплату. note: type: string example: СБП, 2026-08-14 required: - partner_pk - amount - external_id SetReferralAccessDto: type: object properties: partner_pk: type: number example: 42 description: account_pk партнёра enabled: type: boolean example: true description: Показывать ли аккаунту партнёрский раздел. По умолчанию выключено у всех. required: - partner_pk - enabled UpdateRateDto: type: object properties: partner_pk: type: number example: 42 rate: type: number example: 0.25 minimum: 0 maximum: 1 description: 'Ставка долей единицы: 0.25 — это 25%. Верхняя граница обязательна, иначе значение не влезет в NUMERIC(5,4).' required: - partner_pk - rate securitySchemes: api-key: type: apiKey in: header name: x-api-key description: Персональный API ключ. Отображается в личном кабинете (https://app.uchecker.net). Передавайте в заголовке `x-api-key` каждого запроса. Ключ не имеет срока действия — действует до ручного сброса через `POST /auth/reset-api-key`. bearer: scheme: bearer bearerFormat: JWT type: http description: JWT access token, полученный через `POST /auth/login`. Время жизни — 1 час. Для обновления используйте `POST /auth/refresh` с refresh token.