openapi: 3.0.3
info:
  title: API احراز هویت نوبیتکس
  version: "1.1.0"
  description: |
    APIهای مربوط به احراز هویت در نوبیتکس، شامل ورود نسخه قدیم و جدید، مرحله دوم ورود و خروج.

servers:
  - url: https://apiv2.nobitex.ir
  - url: https://testnetapiv2.nobitex.ir

tags:
  - name: احراز هویت
    description: ورود، مرحله دوم ورود و خروج از حساب

paths:
  /v2/auth/login:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - احراز هویت
      summary: ورود نسخه ۲
      description: |
        ورود کاربر در نسخه جدید API.

        - محدودیت فراخوانی: ۳۰ درخواست در هر ۱۰ دقیقه
        - برای شروع ورود، `username`، `password` و کپچا را ارسال کنید.
        - در صورت نیاز به مرحله دوم ورود، به‌جای توکن نهایی، `mfaToken` و `mfaMethod` برگردانده می‌شود.
        - برای تکمیل مرحله دوم، همان مسیر را با `username`، `mfaToken`، `device` و در صورت نیاز `otp` فراخوانی کنید.
        - اگر `mfaMethod=2` باشد، کد TOTP را در هدر `X-TOTP` بفرستید.
        - برای بات API: `captcha=api` را در بدنه، هدر `User-Agent` را به‌صورت `TraderBot/<name-and-version>`، و کد TOTP را در هدر `X-TOTP` ارسال کنید. در این حالت ورود تک‌مرحله‌ای است و مرحله دوم (`mfaToken`/`mfaMethod`) انجام نمی‌شود.
      parameters:
        - $ref: "#/components/parameters/XTOTP"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/LoginRequest"
                - $ref: "#/components/schemas/MfaLoginRequest"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/LoginSuccessResponse"
                  - $ref: "#/components/schemas/MfaChallengeResponse"
        "400":
          description: درخواست نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginFailedResponse"
        "401":
          description: نام کاربری یا گذرواژه نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginFailedResponse"
        "422":
          description: خطای تجاری
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginFailedResponse"

  /v2/auth/login/otp:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - احراز هویت
      summary: ارسال مجدد OTP مرحله دوم ورود
      description: |
        در جریان ورود چندمرحله‌ای، OTP جدید برای کاربر ارسال می‌کند.

        - محدودیت فراخوانی: ۱ درخواست در دقیقه
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MfaOtpResendRequest"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtpResendResponse"

  /auth/login/:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - احراز هویت
      summary: ورود نسخه قدیم
      description: |
        ورود کاربر در API قدیمی.

        - محدودیت فراخوانی: ۳۰ درخواست در هر ۱۰ دقیقه
        - این مسیر همچنان فعال است و در بک‌اند با نسخه `v1` پردازش می‌شود.
        - برای استفاده بات API، `captcha=api` را در بدنه، هدر `User-Agent` را به‌صورت `TraderBot/<name-and-version>`، و کد دوعاملی را در هدر `X-TOTP` ارسال کنید.
      parameters:
        - $ref: "#/components/parameters/XTOTP"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginSuccessResponse"
        "400":
          description: درخواست نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LegacyLoginFailedResponse"
        "403":
          description: نام کاربری یا گذرواژه نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LegacyLoginFailedResponse"
        "422":
          description: خطای تجاری
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LegacyLoginFailedResponse"

  /auth/logout/:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - احراز هویت
      summary: خروج از حساب
      description: |
        توکن فعلی را باطل می‌کند.
      security:
        - TokenAuth: []
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogoutResponse"

components:
  parameters:
    TraderBotUserAgent:
      name: User-Agent
      in: header
      required: false
      description: |
        برای شناسایی بات، این هدر را در همه درخواست‌های HTTP بات با الگوی
        `TraderBot/<name-and-version>` ارسال کنید. این هدر هنگام ورود خودکار با
        `captcha=api` الزامی و در سایر فراخوانی‌های بات اکیداً توصیه می‌شود.
      schema:
        type: string
      example: TraderBot/MyBot-1.0.0
    XTOTP:
      name: X-TOTP
      in: header
      required: false
      description: کد دوعاملی؛ هنگام ورود با `captcha=api` یا `mfaMethod=2` الزامی است.
      schema:
        type: string
      example: "123456"

  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: توکن احراز هویت به صورت `Token yourTOKENhereHEX0000` در هدر ارسال می‌شود.

  schemas:
    LoginRequest:
      type: object
      required:
        - username
        - password
        - captcha
      properties:
        username:
          type: string
          description: نام کاربری کاربر
          example: name@example.com
        password:
          type: string
          description: گذرواژه کاربر
          example: secret-password-1234
        captcha:
          type: string
          description: مقدار کپچا؛ برای بات API مقدار `api` استفاده می‌شود
          example: api
        remember:
          type: string
          description: در صورت `yes` توکن ماندگار صادر می‌شود
          example: yes

    MfaLoginRequest:
      type: object
      required:
        - username
        - mfaToken
        - device
      properties:
        username:
          type: string
          description: نام کاربری کاربر
          example: name@example.com
        mfaToken:
          type: string
          description: توکن موقت برگشتی از مرحله اول ورود
        device:
          type: string
          description: شناسه دستگاه برگشتی از مرحله اول ورود
          example: device-id-1234
        otp:
          type: string
          description: OTP مرحله دوم؛ برای `mfaMethod=3` یا `mfaMethod=4`
          example: "123456"

    MfaOtpResendRequest:
      type: object
      required:
        - username
        - mfaToken
        - device
      properties:
        username:
          type: string
          example: name@example.com
        mfaToken:
          type: string
          description: توکن موقت برگشتی از مرحله اول ورود
        device:
          type: string
          description: شناسه دستگاه برگشتی از مرحله اول ورود
          example: device-id-1234

    OtpResendResponse:
      type: object
      properties:
        status:
          type: string
          example: ok

    LoginSuccessResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        key:
          type: string
          description: توکن احراز هویت
          example: yourTOKENhereHEX0000
        expiresIn:
          type: integer
          description: زمان اعتبار توکن بر حسب ثانیه
        device:
          type: string
          description: شناسه دستگاه
          example: device-id-1234
        we_id:
          type: string
          description: شناسه کاربر در WebEngage

    MfaChallengeResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        mfaToken:
          type: string
        mfaMethod:
          type: integer
          description: |
            شناسه روش MFA. مقادیر شناخته‌شده:
            - `2` — TOTP (Google Authenticator)
            - `3` — OTP پیامک
            - `4` — OTP ایمیل
          enum: [2, 3, 4]
          example: 3
        device:
          type: string
          example: device-id-1234
        target:
          type: string
          nullable: true
          description: مقصد ماسک‌شده ارسال OTP

    LoginFailedResponse:
      type: object
      properties:
        status:
          type: string
          example: failed
        code:
          type: string
          example: InvalidCredential
        message:
          type: string
          example: Unable to log in with provided credentials.
        captchaAcceptableTypes:
          type: array
          items:
            type: string

    LegacyLoginFailedResponse:
      type: object
      properties:
        code:
          type: string
          example: ActionIsRestricted
        non_field_errors:
          type: array
          items:
            type: string
        acceptableTypes:
          type: array
          items:
            type: string

    LogoutResponse:
      type: object
      properties:
        detail:
          type: string
        message:
          type: string