{
  "openapi": "3.1.0",
  "info": {
    "title": "AuthGuard API",
    "version": "1.0.0",
    "description": "Техническая проверка почтовой инфраструктуры email-домена перед регистрацией пользователя. Сервис не проверяет существование отдельного почтового ящика и не является юридическим заключением."
  },
  "servers": [
    { "url": "https://api.authguard.ru" }
  ],
  "paths": {
    "/v1/check/email": {
      "post": {
        "operationId": "checkEmailDomain",
        "summary": "Проверить почтовый домен email",
        "description": "Определяет почтового провайдера по MX-записям и возвращает техническое решение для сценария регистрации.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CheckEmailRequest" },
              "example": { "email": "user@company.ru" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Проверка выполнена. Решение находится в can_register и decision.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckEmailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/InsufficientBalance" },
          "429": { "$ref": "#/components/responses/DailyLimitReached" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API-ключ AuthGuard из личного кабинета."
      }
    },
    "schemas": {
      "CheckEmailRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email", "examples": ["user@company.ru"] }
        }
      },
      "CheckEmailResponse": {
        "type": "object",
        "required": ["email_domain", "allowed", "can_register", "decision", "risk_level", "reason_code", "evidence", "meta"],
        "properties": {
          "email_domain": { "type": "string" },
          "allowed": { "type": "boolean" },
          "can_register": { "type": "boolean", "description": "Основное поле для логики регистрации." },
          "decision": { "type": "string", "enum": ["allow", "block", "manual_review"] },
          "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
          "provider": { "type": ["string", "null"] },
          "reason_code": { "type": "string", "examples": ["foreign_mail_provider"] },
          "matched_rule": { "type": ["string", "null"] },
          "evidence": {
            "type": "object",
            "required": ["mx"],
            "properties": {
              "mx": { "type": "array", "items": { "type": "string" } }
            }
          },
          "meta": {
            "type": "object",
            "required": ["api_key_name", "requests_today", "requests_remaining", "daily_limit"],
            "properties": {
              "api_key_name": { "type": "string" },
              "requests_today": { "type": "integer", "minimum": 0 },
              "requests_remaining": { "type": "integer", "minimum": 0 },
              "daily_limit": { "type": "integer", "minimum": 0 }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Некорректный JSON или email.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Ключ отсутствует, недействителен или отозван.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "InsufficientBalance": {
        "description": "Недостаточно средств.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "DailyLimitReached": {
        "description": "Исчерпан суточный лимит ключа.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "InternalError": {
        "description": "Внутренняя ошибка сервиса.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}