uChecker ESP Провайдеры API

openapi: 3.2.0
info:
  title: UChecker ESP Провайдеры API
  description: '## О сервисе


    UChecker — платформа валидации email-адресов для маркетологов, ESP-провайдеров и разработчиков.'
  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:
    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
    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
    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.