uChecker ESP Провайдеры API
Программный интерфейс для ESP-провайдеров: расчёт стоимости и автоматическое создание аккаунтов с зачислением кредитов
OpenAPI Specification
openapi: 3.2.0
info:
title: UChecker ESP Провайдеры 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: ESP Провайдеры
description: 'Программный интерфейс для ESP-провайдеров: расчёт стоимости и автоматическое создание аккаунтов с зачислением кредитов'
paths:
/api/v1/esp/price:
get:
description: 'Возвращает стоимость указанного количества кредитов на валидацию email. Используется ESP-провайдерами для отображения цен в своём интерфейсе.
**Объёмные скидки:**
Цена за один email снижается при увеличении объёма. Точная формула зависит от условий вашего партнёрского соглашения. Поле `price_per_email` в ответе показывает итоговую цену за один адрес.
**Валюта:**
Все цены указываются в рублях (RUB). Поле `currency` в ответе всегда содержит `RUB`.
**Аутентификация:**
Этот эндпоинт использует токен ESP-провайдера (`x-esp-token`), а не стандартные API ключ или JWT. Токен выдаётся при регистрации партнёра.'
operationId: EspController_getPrice
parameters:
- name: count
required: true
in: query
description: 'Количество кредитов для расчёта стоимости. Минимум: 1.'
schema:
example: 10000
type: number
- name: x-esp-token
required: true
in: header
description: Токен аутентификации ESP-провайдера. Выдаётся при регистрации партнёра.
schema:
type: string
responses:
'200':
description: 'Расчёт стоимости: общая цена, цена за email, валюта.'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'401':
description: Токен ESP-провайдера отсутствует, невалиден или деактивирован.
content:
application/json:
schema:
$ref: '#/components/schemas/EspErrorResponse'
summary: Рассчитать стоимость кредитов
tags:
- ESP Провайдеры
/api/v1/esp/provision:
post:
description: 'Создаёт новый аккаунт UChecker или пополняет кредиты существующему. Основной эндпоинт для ESP-провайдеров, вызываемый после подтверждения оплаты пользователем.
**Логика работы:**
- Если аккаунт с указанным email **не существует** — создаётся новый аккаунт, генерируется API ключ, зачисляются кредиты. Поле `is_new_account: true`.
- Если аккаунт **существует** — кредиты добавляются к текущему балансу. Поле `is_new_account: false`.
**Идемпотентность:**
Передайте `external_id` (ID заказа на стороне ESP). При повторном вызове с тем же `external_id` кредиты не будут зачислены повторно — вернётся исходный ответ с `is_duplicate: true`.
**Возвращаемые данные:**
Ответ содержит `api_key` аккаунта — передайте его пользователю для доступа к API. Также возвращаются `credits_added` (зачислено) и `total_credits` (итоговый баланс).
**Аутентификация:**
Требуется токен ESP-провайдера в заголовке `x-esp-token`.'
operationId: EspController_provisionAccount
parameters:
- name: x-esp-token
required: true
in: header
description: Токен аутентификации ESP-провайдера. Выдаётся при регистрации партнёра.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProvisionAccountDto'
responses:
'200':
description: Аккаунт создан или пополнен. Ответ содержит API ключ, зачисленные и итоговые кредиты.
content:
application/json:
schema:
$ref: '#/components/schemas/ProvisionResponse'
'400':
description: Ошибка при создании аккаунта или зачислении кредитов.
content:
application/json:
schema:
$ref: '#/components/schemas/EspErrorResponse'
'401':
description: Токен ESP-провайдера отсутствует, невалиден или деактивирован.
content:
application/json:
schema:
$ref: '#/components/schemas/EspErrorResponse'
summary: Создать аккаунт или пополнить кредиты
tags:
- ESP Провайдеры
components:
schemas:
ProvisionAccountDto:
type: object
properties:
email:
type: string
description: Email-адрес пользователя. Если аккаунт с таким email существует — кредиты будут добавлены к текущему балансу. Если нет — будет создан новый аккаунт.
example: user@example.com
credits:
type: number
description: Количество кредитов для зачисления на аккаунт. 1 кредит = 1 проверка email-адреса.
example: 10000
minimum: 1
external_id:
type: string
description: Внешний идентификатор заказа/транзакции на стороне ESP-провайдера. Используется для идемпотентности — повторный запрос с тем же `external_id` не создаст дубликат.
example: order_12345
required:
- email
- credits
PriceResponse:
type: object
properties:
success:
type: boolean
example: true
description: Признак успешного расчёта
credits:
type: number
example: 10000
description: Запрошенное количество кредитов
price:
type: number
example: 2000
description: Общая стоимость в рублях (RUB)
price_per_email:
type: number
example: 0.2
description: Стоимость одного кредита (проверки одного email) в рублях. Уменьшается при увеличении объёма.
currency:
type: string
example: RUB
description: Код валюты. Всегда `RUB`.
required:
- success
- credits
- price
- price_per_email
- currency
ProvisionResponse:
type: object
properties:
success:
type: boolean
example: true
description: Признак успешного выполнения операции
message:
type: string
example: Аккаунт создан и лимиты зачислены успешно
description: Человекочитаемое описание результата
account_id:
type: number
example: 123
description: Числовой идентификатор аккаунта UChecker
email:
type: string
example: user@example.com
description: Email-адрес аккаунта
api_key:
type: string
example: uk_xxxxxxxxxxxxx
description: API ключ аккаунта. Передайте пользователю для доступа к API. Для новых аккаунтов — только что сгенерированный ключ.
credits_added:
type: number
example: 10000
description: Количество кредитов, зачисленных в рамках этой операции
total_credits:
type: number
example: 10000
description: Итоговый баланс кредитов на аккаунте (включая ранее зачисленные)
is_new_account:
type: boolean
example: false
description: '`true` — создан новый аккаунт, `false` — кредиты добавлены к существующему'
is_duplicate:
type: boolean
example: false
description: '`true` — запрос с таким `external_id` уже обработан ранее. Кредиты не были зачислены повторно (идемпотентный ответ).'
required:
- success
- message
- account_id
- email
- api_key
- credits_added
- total_credits
- is_new_account
EspErrorResponse:
type: object
properties:
success:
type: boolean
example: false
description: Всегда `false` для ошибок
error:
type: string
example: Неверный токен провайдера
description: Описание ошибки
required:
- success
- error
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.