uChecker Аутентификация API
Вход, регистрация, управление JWT-токенами и API ключами, привязка Telegram
OpenAPI Specification
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 <token>`.
- `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 <token>`). 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 }` — дашборд по этому призна�
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/uchecker/refs/heads/main/openapi/uchecker-default-api-openapi.yml