openapi: 3.0.3
info:
  title: API طرح معرفی دوستان نوبیتکس
  version: "1.1.0"
  description: |
    APIهای مربوط به کد دعوت، لینک‌های دعوت و وضعیت معرفی دوستان.

    مسیرهای این بخش برای سازگاری با کلاینت‌های قدیمی ممکن است `GET` را نیز بپذیرند؛
    قرارداد مستند و روش توصیه‌شده برای فراخوانی آن‌ها `POST` است.

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

tags:
  - name: معرفی دوستان
    description: مدیریت کدها و وضعیت طرح معرفی دوستان

paths:
  /users/referral/links-list:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - معرفی دوستان
      summary: فهرست لینک‌های دعوت
      description: |
        لیست لینک‌های دعوت کاربر را برمی‌گرداند.

        - محدودیت فراخوانی: ۵۰ درخواست در هر ۱۰ دقیقه
        - برای لینک پیش‌فرض، آمار معاملاتی (`statsTrades`/`statsProfit`) شامل کارمزدهای پیش از ایجاد طرح نیز می‌شود.
      security:
        - TokenAuth: []
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  links:
                    type: array
                    items:
                      $ref: "#/components/schemas/ReferralLink"

  /users/referral/links-add:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - معرفی دوستان
      summary: ایجاد لینک دعوت
      description: |
        یک لینک دعوت جدید برای کاربر می‌سازد.

        - محدودیت فراخوانی: ۵ درخواست در دقیقه
        - `friendShare` در صورت عدم ارسال، `0` در نظر گرفته می‌شود.
        - `agenda` اختیاری است و در صورت عدم ارسال، مقدار پیش‌فرض برنامهٔ ارجاع استفاده می‌شود.
      security:
        - TokenAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                friendShare:
                  type: integer
                  description: سهم کارمزد اهدایی به دوست دعوت‌شده
                  default: 0
                  example: 10
                agenda:
                  type: string
                  description: شناسه برنامه یا سناریوی لینک دعوت
                  example: default
      responses:
        "200":
          description: موفق یا ناموفق
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        example: ok
                      result:
                        $ref: "#/components/schemas/ReferralLink"
                  - $ref: "#/components/schemas/ReferralFailedResponse"

  /users/referral/referral-status:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - معرفی دوستان
      summary: وضعیت معرف کاربر
      description: |
        مشخص می‌کند آیا کاربر فعلی توسط کاربر دیگری معرفی شده است یا خیر.

        - محدودیت فراخوانی: ۵۰ درخواست در هر ۱۰ دقیقه
      security:
        - TokenAuth: []
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  hasReferrer:
                    type: boolean
                    example: true

  /users/referral/set-referrer:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - معرفی دوستان
      summary: ثبت معرف کاربر
      description: |
        کد معرف را برای کاربر فعلی ثبت می‌کند.

        - محدودیت فراخوانی: ۵۰ درخواست در هر ۱۰ دقیقه
        - این عملیات فقط تا ۲۴ ساعت پس از ثبت‌نام مجاز است.
        - در صورت خارج بودن از بازه مجاز، `code=ReferrerChangeUnavailable` برمی‌گردد.
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - referrerCode
              properties:
                referrerCode:
                  type: string
                  description: کد دعوت کاربر دعوت‌کننده
                  example: "40404"
      responses:
        "200":
          description: موفق یا ناموفق
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        example: ok
                  - $ref: "#/components/schemas/ReferralFailedResponse"

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

  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization

  schemas:
    ReferralLink:
      type: object
      description: |
        فیلدهای زیر مجموعه‌ای از فیلدهای بازگشتی هستند؛ بک‌اند ممکن است بسته به نسخه
        فیلدهای آماری بیشتری نیز برگرداند.
      additionalProperties: true
      properties:
        id:
          type: integer
          example: 1001
        referralCode:
          type: string
          example: "40404"
        createdAt:
          type: string
          format: date-time
          example: "2020-07-15T11:32:38.326809+00:00"
        userShare:
          type: integer
          example: 20
        friendShare:
          type: integer
          example: 10
        agenda:
          type: string
          description: شناسه برنامه یا سناریوی لینک دعوت
          example: default
        description:
          type: string
          nullable: true
          example: Shared on Instagram page X
        statsRegisters:
          type: integer
          example: 20
        statsTrades:
          type: integer
          example: 240
        statsProfit:
          type: integer
          description: درآمد ریالی از این کد دعوت
          example: 320000

    ReferralFailedResponse:
      type: object
      properties:
        status:
          type: string
          example: failed
        code:
          type: string
          example: InvalidGivebackShare
        message:
          type: string
          example: Failed to create the requested referral link