openapi: 3.0.3
info:
  title: Bot Distribution System API
  description: |
    واجهة برمجة التطبيقات لنظام توزيع أكواد الحسابات.
    
    ## المصادقة
    جميع الـ endpoints تتطلب مفتاح API في الـ header:
    ```
    X-API-Key: your-admin-api-key
    ```
    
    ## أنواع القسائم
    - `sd`: قسيمة اشتراك موزع
    - `activation_bundle`: حزمة أكواد تفعيل
  version: 2.0.0
  contact:
    name: API Support

servers:
  - url: /api/v1
    description: API v1

tags:
  - name: Vouchers
    description: إدارة القسائم
  - name: Payments
    description: webhooks الدفع
  - name: System
    description: فحص النظام
  - name: Broadcast
    description: إعدادات البث
  - name: Accounts
    description: إدارة الحسابات

paths:
  /vouchers:
    post:
      tags: [Vouchers]
      summary: إنشاء قسيمة جديدة
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, payload]
              properties:
                type:
                  type: string
                  enum: [sd, activation_bundle]
                  description: نوع القسيمة
                payload:
                  type: object
                  description: بيانات القسيمة حسب النوع
                  oneOf:
                    - $ref: '#/components/schemas/SDPayload'
                    - $ref: '#/components/schemas/BundlePayload'
                max_uses:
                  type: integer
                  default: 1
                  description: الحد الأقصى للاستخدام
                expires_at:
                  type: string
                  format: date-time
                  description: تاريخ انتهاء الصلاحية
                admin_id:
                  type: integer
                  description: معرف المسؤول المنشئ
            examples:
              sd_voucher:
                summary: قسيمة موزع
                value:
                  type: sd
                  payload:
                    accounts:
                      - account_id: 1
                        duration_days: 30
                        limits:
                          daily: 10
                          weekly: 50
                  max_uses: 1
              bundle_voucher:
                summary: حزمة أكواد
                value:
                  type: activation_bundle
                  payload:
                    account_id: 1
                    codes_count: 10
                    access_type: timed
                    access_days: 30
      responses:
        '200':
          description: تم إنشاء القسيمة بنجاح
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      voucher_id:
                        type: integer
                      code:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    
    get:
      tags: [Vouchers]
      summary: قائمة القسائم
      security:
        - ApiKeyAuth: []
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [sd, activation_bundle]
        - name: status
          in: query
          schema:
            type: string
            enum: [unused, partial, used, expired, disabled]
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: قائمة القسائم
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Voucher'

  /vouchers/{code}:
    get:
      tags: [Vouchers]
      summary: جلب قسيمة بالكود
      security:
        - ApiKeyAuth: []
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
          example: VCH-A1B2-C3D4
      responses:
        '200':
          description: بيانات القسيمة
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Voucher'
        '404':
          $ref: '#/components/responses/NotFound'

  /vouchers/redeem:
    post:
      tags: [Vouchers]
      summary: استرداد قسيمة
      description: |
        يمكن استدعاء هذا الـ endpoint من البوت أو من تطبيق خارجي.
        لا يتطلب مفتاح API ولكن يتطلب Telegram ID صالح.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, redeemer_telegram_id]
              properties:
                code:
                  type: string
                  description: كود القسيمة
                redeemer_telegram_id:
                  type: integer
                  format: int64
                  description: Telegram ID للمستفيد
            example:
              code: VCH-A1B2-C3D4
              redeemer_telegram_id: 123456789
      responses:
        '200':
          description: تم الاسترداد بنجاح
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    description: نتيجة الاسترداد (تختلف حسب نوع القسيمة)
        '400':
          $ref: '#/components/responses/BadRequest'

  /payments/webhook:
    post:
      tags: [Payments]
      summary: Webhook الدفع
      description: |
        يستقبل إشعارات الدفع من مزودي الدفع الخارجيين.
        عند تأكيد الدفع، يتم إنشاء قسيمة تلقائياً.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  description: مزود الدفع
                payment_id:
                  type: string
                  description: معرف الدفع
                event_type:
                  type: string
                  description: نوع الحدث
                  example: payment.completed
                amount:
                  type: number
                  format: float
                currency:
                  type: string
                  maxLength: 3
                payer_email:
                  type: string
                  format: email
                metadata:
                  type: object
                  description: بيانات إضافية لإنشاء القسيمة
                  properties:
                    voucher_type:
                      type: string
                    payload:
                      type: object
                    telegram_id:
                      type: integer
      responses:
        '200':
          description: تم استلام الـ webhook
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      voucher_code:
                        type: string

  /system/check:
    post:
      tags: [System]
      summary: تشغيل فحص النظام
      security:
        - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [full, quick, custom]
                  default: full
                tests:
                  type: array
                  items:
                    type: string
                  description: قائمة الاختبارات (لـ custom فقط)
                admin_id:
                  type: integer
      responses:
        '200':
          description: تقرير الفحص
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      report_id:
                        type: integer
                      stats:
                        $ref: '#/components/schemas/CheckStats'
                      summary:
                        type: string
                      report_file_json:
                        type: string

  /system/reports:
    get:
      tags: [System]
      summary: قائمة تقارير الفحص
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 50
      responses:
        '200':
          description: قائمة التقارير
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CheckReport'

  /system/reports/{id}:
    get:
      tags: [System]
      summary: جلب تقرير محدد
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: بيانات التقرير
        '404':
          $ref: '#/components/responses/NotFound'

  /broadcast/settings:
    get:
      tags: [Broadcast]
      summary: جلب إعدادات البث
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: إعدادات البث
    
    post:
      tags: [Broadcast]
      summary: تحديث إعدادات البث
      security:
        - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
            example:
              chunk_size: "50"
              blacklist_enabled: "1"
      responses:
        '200':
          description: تم التحديث

  /broadcast/blacklist:
    get:
      tags: [Broadcast]
      summary: جلب القائمة السوداء
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: قائمة الكلمات المحظورة
    
    post:
      tags: [Broadcast]
      summary: إضافة للقائمة السوداء
      security:
        - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [word]
              properties:
                word:
                  type: string
                type:
                  type: string
                  enum: [word, regex, domain]
                  default: word
                severity:
                  type: string
                  enum: [block, warn, log]
                  default: block
                admin_id:
                  type: integer
      responses:
        '200':
          description: تمت الإضافة

  /broadcast/blocked:
    get:
      tags: [Broadcast]
      summary: البثات المحظورة
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: قائمة البثات المحظورة

  /accounts/batch:
    post:
      tags: [Accounts]
      summary: إضافة حسابات دفعة واحدة
      security:
        - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [accounts]
              properties:
                accounts:
                  type: array
                  items:
                    type: object
                    required: [name, slug]
                    properties:
                      name:
                        type: string
                      slug:
                        type: string
                      access_type:
                        type: string
                        enum: [lifetime, timed]
                      access_days:
                        type: integer
                      secret_key:
                        type: string
                mode:
                  type: string
                  enum: [fail-fast, partial-commit]
                  default: fail-fast
                preview:
                  type: boolean
                  default: false
      responses:
        '200':
          description: نتيجة الإدراج
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                      success:
                        type: integer
                      failed:
                        type: integer
                      errors:
                        type: array
                        items:
                          type: object
                      created:
                        type: array
                        items:
                          type: object

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    SDPayload:
      type: object
      required: [accounts]
      properties:
        accounts:
          type: array
          items:
            type: object
            required: [account_id, duration_days]
            properties:
              account_id:
                type: integer
              duration_days:
                type: integer
              limits:
                type: object
                properties:
                  daily:
                    type: integer
                  weekly:
                    type: integer
                  monthly:
                    type: integer

    BundlePayload:
      type: object
      required: [account_id, codes_count]
      properties:
        account_id:
          type: integer
        codes_count:
          type: integer
          minimum: 1
        access_type:
          type: string
          enum: [lifetime, timed]
          default: lifetime
        access_days:
          type: integer

    Voucher:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        type:
          type: string
          enum: [sd, activation_bundle]
        payload:
          type: object
        max_uses:
          type: integer
        current_uses:
          type: integer
        status:
          type: string
          enum: [unused, partial, used, expired, disabled]
        expires_at:
          type: string
          format: date-time
        payment_id:
          type: string
        payment_provider:
          type: string
        payment_amount:
          type: number
        payment_currency:
          type: string
        created_at:
          type: string
          format: date-time

    CheckStats:
      type: object
      properties:
        total:
          type: integer
        passed:
          type: integer
        failed:
          type: integer
        warnings:
          type: integer

    CheckReport:
      type: object
      properties:
        id:
          type: integer
        check_type:
          type: string
        triggered_by:
          type: string
        total_tests:
          type: integer
        passed_tests:
          type: integer
        failed_tests:
          type: integer
        warnings:
          type: integer
        summary:
          type: string
        duration_ms:
          type: integer
        created_at:
          type: string
          format: date-time

  responses:
    BadRequest:
      description: طلب غير صالح
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string

    Unauthorized:
      description: غير مصرح
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: Unauthorized

    NotFound:
      description: غير موجود
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: Not found
