openapi: 3.0.0
info:
  title: Panelchi API
  version: 1.0.0
tags: []
paths:
  /account/info:
    get:
      operationId: Account_getInfo
      summary: دریافت اطلاعات حساب
      description: دریافت اطلاعات حساب کاربر، پلن و موجودی کیف پول
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Api.AccountInfoResponse'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: عملیات با موفقیت انجام شد.
                      requestId:
                        type: string
                        example: 'uuid (ex: d9647fb8-4e9e-4709-9ba4-dfe9927b05a7)'
                      serverTime:
                        type: string
                        format: date-time
                        example: '2026-05-11T11:01:36.152123Z'
                    required:
                      - message
                      - requestId
                      - serverTime
                required:
                  - data
                  - meta
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '401':
          description: Access is unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '403':
          description: Access is forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '500':
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
      security:
        - BearerAuth: []
  /plan/tariff:
    get:
      operationId: Plan_getTariff
      summary: دریافت پلن
      description: دریافت پلن، تعرفه و ضرایب (متن، صدا، سایر) برای کاربر احراز هویت‌شده. در صورت نبود پلن/تعرفه 404 برمی‌گردد.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Api.PlanTariffResponse'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: عملیات با موفقیت انجام شد.
                      requestId:
                        type: string
                        example: 'uuid (ex: d9647fb8-4e9e-4709-9ba4-dfe9927b05a7)'
                      serverTime:
                        type: string
                        format: date-time
                        example: '2026-05-11T11:01:36.152123Z'
                    required:
                      - message
                      - requestId
                      - serverTime
                required:
                  - data
                  - meta
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '401':
          description: Access is unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '403':
          description: Access is forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '429':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '500':
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
      security:
        - BearerAuth: []
  /sms/delivery:
    get:
      operationId: Sms_getDelivery
      summary: دریافت وضعیت پیامک
      description: |-
        دریافت وضعیت پیامک ارسالی وبسرویس: از طریق شناسهٔ یکتای گیرنده‌های پیامک.

        Statuses:

        - `CREATED`: در انتظار تایید
        - `SENDING`: در حال ارسال
        - `SENT`: ارسال شد
        - `FAILED`: ناموفق
        - `REJECTED`: رد شد
        - `CANCELED`: لغو شد
        - `SENDING_ERROR`: خطا در ارسال
        - `NOT_DELIVERED_TO_MOBILE`: نرسیده به گوشی
        - `DELIVERED_TO_MOBILE`: رسیده به گوشی
        - `DELIVERED_TO_TELE`: رسیده به مخابرات
        - `SEND_TO_TELE`: ارسال به مخابرات
        - `BLOCKED_LIST`: بلاک لیست

        محدودیت: ۲۰۰ شناسه یکتا در هر درخواست.
      parameters:
        - $ref: '#/components/parameters/Api.GetSmsDeliveryRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Api.GetSmsDeliveryResponse'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: عملیات با موفقیت انجام شد.
                      requestId:
                        type: string
                        example: 'uuid (ex: d9647fb8-4e9e-4709-9ba4-dfe9927b05a7)'
                      serverTime:
                        type: string
                        format: date-time
                        example: '2026-05-11T11:01:36.152123Z'
                    required:
                      - message
                      - requestId
                      - serverTime
                required:
                  - data
                  - meta
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '401':
          description: Access is unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '403':
          description: Access is forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '422':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ValidationResponseBody'
        '429':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '500':
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
      security:
        - BearerAuth: []
  /sms/pattern:
    post:
      operationId: Sms_sendPattern
      summary: ارسال پیامک پترن
      description: |-
        ارسال یک پیامک با پترن: اسلاگ پترن، مقادیر متغیرها، یک گیرنده و یک سرشماره.

        Domain errors:

        - statusCode = 412: `code = 1003 (UserInactive)` — وضعیت حساب کاربری شما فعال نمی باشد.
        - statusCode = 400: `code = 2001 (InsufficientBalance)` — موجودی کیف پول شما کافی نمی باشد
        - statusCode = 422: `code = 3002 (SmsPatternNoActiveVersion)` — این پترن نسخه فعالی ندارد.
        - statusCode = 412: `code = 3011 (SmsSendNotAllowed)` — ارسال پیامک موقتا غیرفعال می‌باشد.
        - statusCode = 406: `code = 3013 (SmsPatternHeadNumberNotAcceptable)` — سرشماره انتخاب شده برای ارسال پیامک از طریق وبسرویس، نامعتبر است.
        - statusCode = 406: `code = 3014 (SmsPatternVariableHasNoValue)` — مقداری برای متغیر :variable_name داده نشده است.
        - statusCode = 406: `code = 3015 (SmsPatternVariableNotValid)` — مقدار متغیر :variable_name نامعتبر است.
        - statusCode = 406: `code = 4004 (HeadNumberNotFoundException)` — سرشماره انتخاب شده برای ارسال پیامک از طریق وبسرویس، نامعتبر است.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Api.SendSmsResponse'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: عملیات با موفقیت انجام شد.
                      requestId:
                        type: string
                        example: 'uuid (ex: d9647fb8-4e9e-4709-9ba4-dfe9927b05a7)'
                      serverTime:
                        type: string
                        format: date-time
                        example: '2026-05-11T11:01:36.152123Z'
                    required:
                      - message
                      - requestId
                      - serverTime
                required:
                  - data
                  - meta
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '401':
          description: Access is unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '403':
          description: Access is forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '406':
          description: پاسخ خطای استاندارد (RFC 7807 Problem Details)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '412':
          description: پاسخ خطای استاندارد (RFC 7807 Problem Details)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '422':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ValidationResponseBody'
        '429':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '500':
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api.PatternSendRequest'
      security:
        - BearerAuth: []
  /sms/send:
    post:
      operationId: Sms_sendSimple
      summary: ارسال پیامک ساده
      description: |-
        ارسال یک پیامک ساده: متن پیامک، گیرنده‌ها، یک سرشماره و زمان‌بندی برای ارسال.

        Domain errors:

        - statusCode = 422: `code = 422 (ErrorTypeValidation)` — تعداد شماره های ارسالی بیش از حدمجاز است.
        - statusCode = 412: `code = 1003 (UserInactive)` — وضعیت حساب کاربری شما فعال نمی باشد.
        - statusCode = 400: `code = 2001 (InsufficientBalance)` — موجودی کیف پول شما کافی نمی باشد
        - statusCode = 412: `code = 3011 (SmsSendNotAllowed)` — ارسال پیامک موقتا غیرفعال می‌باشد.
        - statusCode = 406: `code = 4004 (HeadNumberNotFoundException)` — سرشماره انتخاب شده برای ارسال پیامک از طریق وبسرویس، نامعتبر است.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Api.SendSmsResponse'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: عملیات با موفقیت انجام شد.
                      requestId:
                        type: string
                        example: 'uuid (ex: d9647fb8-4e9e-4709-9ba4-dfe9927b05a7)'
                      serverTime:
                        type: string
                        format: date-time
                        example: '2026-05-11T11:01:36.152123Z'
                    required:
                      - message
                      - requestId
                      - serverTime
                required:
                  - data
                  - meta
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '401':
          description: Access is unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '403':
          description: Access is forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '406':
          description: پاسخ خطای استاندارد (RFC 7807 Problem Details)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '412':
          description: پاسخ خطای استاندارد (RFC 7807 Problem Details)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '422':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ValidationResponseBody'
        '429':
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
        '500':
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Common.ProblemResponseBody'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api.SendSimpleRequest'
      security:
        - BearerAuth: []
components:
  parameters:
    Api.GetSmsDeliveryRequest:
      name: uids[]
      in: query
      required: true
      schema:
        type: array
        items:
          type: string
        maxItems: 200
  schemas:
    Api.AccountInfoPart:
      type: object
      required:
        - username
        - fullName
        - legalType
        - mobile
        - status
      properties:
        username:
          type: string
          description: نام کاربری
        fullName:
          type: string
          description: نام کامل یا نام شرکت
        legalType:
          allOf:
            - $ref: '#/components/schemas/Api.AccountLegalType'
          description: نوع کاربری (حقیقی/حقوقی)
          example: INDIVIDUAL
        mobile:
          type: string
          description: شماره موبایل
        email:
          type: string
          nullable: true
          description: ایمیل
        nationalId:
          type: string
          nullable: true
          description: کد ملی
        birthdate:
          type: string
          nullable: true
          description: تاریخ تولد
        phone:
          type: string
          nullable: true
          description: تلفن ثابت
        postalCode:
          type: string
          nullable: true
          description: کد پستی
        address:
          type: string
          nullable: true
          description: آدرس
        status:
          allOf:
            - $ref: '#/components/schemas/Api.AccountStatus'
          description: وضعیت حساب
        accountVerifiedAt:
          type: string
          nullable: true
          description: زمان تأیید حساب (ISO 8601)
          example: '2026-04-25T20:08:59+03:30'
      description: اطلاعات بخش حساب کاربر (نام، موبایل، وضعیت و ...)
    Api.AccountInfoPartWithPlan:
      type: object
      properties:
        plan:
          type: object
          allOf:
            - $ref: '#/components/schemas/Api.AccountPlan'
          nullable: true
          description: پلن فعلی کاربر (در صورت وجود)
      allOf:
        - $ref: '#/components/schemas/Api.AccountInfoPart'
      description: اطلاعات حساب به‌همراه پلن تودرتو
    Api.AccountInfoResponse:
      type: object
      required:
        - accountInfo
        - wallet
      properties:
        accountInfo:
          allOf:
            - $ref: '#/components/schemas/Api.AccountInfoPartWithPlan'
          description: اطلاعات حساب (شامل پلن در صورت وجود)
        wallet:
          allOf:
            - $ref: '#/components/schemas/Api.AccountWallet'
          description: کیف پول
      description: 'پاسخ کامل اطلاعات حساب: accountInfo (شامل plan) + wallet'
    Api.AccountLegalType:
      type: string
      enum:
        - INDIVIDUAL
        - LEGAL
    Api.AccountPlan:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: integer
          format: int32
          description: شناسه پلن
        title:
          type: string
          description: عنوان پلن
      description: پلن فعلی کاربر
    Api.AccountStatus:
      type: string
      enum:
        - REGISTERED
        - PENDING
        - REJECTED
        - ACTIVE
        - SMS_BLOCKED
    Api.AccountWallet:
      type: object
      required:
        - lockedBalance
        - availableBalance
        - totalBalance
        - unit
      properties:
        lockedBalance:
          type: string
          description: موجودی قفل‌شده (واحد SMS)
          example: '2.00'
        availableBalance:
          type: string
          description: موجودی قابل استفاده
          example: '49.20'
        totalBalance:
          type: string
          description: جمع موجودی
          example: '51.20'
        unit:
          allOf:
            - $ref: '#/components/schemas/Api.WalletUnit'
          description: واحد
          example: SMS_UNIT
      description: موجودی کیف پول
    Api.CoefficientRow:
      type: object
      required:
        - title
        - PERSIAN
        - ENGLISH
        - MTN
        - MCI
        - WEBSERVICE
        - PATTERN
        - total
      properties:
        title:
          type: string
          example: '10001'
        PERSIAN:
          type: string
          example: '1.00'
        ENGLISH:
          type: string
          example: '2.00'
        MTN:
          type: string
          example: '1.10'
        MCI:
          type: string
          example: '1.00'
        WEBSERVICE:
          type: string
          example: '1.00'
        PATTERN:
          type: string
          example: '1.00'
        total:
          type: integer
          format: int32
          example: 1400
      description: یک ردیف ضریب؛ کلیدها و مقادیر بسته به نوع تعرفه متغیرند (مثلاً slug، price، title و ...)
    Api.GetSmsDeliveryResponse:
      type: object
      required:
        - uid
        - mobile
        - status
        - message
        - cost
        - created_at
      properties:
        uid:
          type: string
          example: A17765023114814282
        mobile:
          type: string
          example: '+989000000000'
        status:
          allOf:
            - $ref: '#/components/schemas/Api.SmsDeliveryStatus'
          example: CREATED
        message:
          type: string
          description: متن نهایی پیام ارسال‌شده
          example: |-
            کد تایید شما: 12345
            لغو11
        cost:
          type: string
          description: هزینهٔ پیامک (واحد SMS)
          example: '1.10'
        created_at:
          allOf:
            - $ref: '#/components/schemas/Api.unixTimestamp'
          example: 1776849736
        sent_at:
          type: integer
          allOf:
            - $ref: '#/components/schemas/Api.unixTimestamp'
          nullable: true
          example: 1776849738
        delivered_at:
          type: integer
          allOf:
            - $ref: '#/components/schemas/Api.unixTimestamp'
          nullable: true
          example: null
    Api.PatternSendRequest:
      type: object
      required:
        - pattern
        - variables
        - recipient
        - sourceNumber
      properties:
        pattern:
          type: string
          description: اسلاگ پترن
          example: otp-code
        variables:
          allOf:
            - $ref: '#/components/schemas/Api.PatternVariables'
          description: مقدار هر متغیر پترن
        recipient:
          type: string
          description: شماره گیرنده (یک شماره موبایل معتبر ایران)
          example: '+989000000000'
        sourceNumber:
          type: string
          description: سرشماره (شمارهٔ خط ارسال)
      description: بدنهٔ درخواست ارسال پیامک با پترن
    Api.PatternVariables:
      type: object
      description: 'شیء با کلیدهای داینامیک: نام متغیر پترن: مقدار (رشته). مثال: { "name": "علی", "code": "123" }'
    Api.PlanSummary:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: integer
          format: int32
          description: شناسه پلن
        title:
          type: string
          description: عنوان پلن
      description: خلاصهٔ پلن کاربر
    Api.PlanTariffResponse:
      type: object
      required:
        - tariff
        - textsCoefficients
      properties:
        plan:
          type: object
          allOf:
            - $ref: '#/components/schemas/Api.PlanSummary'
          nullable: true
          description: پلن فعلی (در صورت وجود)
        tariff:
          allOf:
            - $ref: '#/components/schemas/Api.TariffInfo'
          description: تعرفه
        textsCoefficients:
          type: array
          items:
            $ref: '#/components/schemas/Api.CoefficientRow'
          description: ضرایب پیامک متنی
      description: پاسخ تعرفه و پلن کاربر به‌همراه ضرایب متن، صدا و سایر
    Api.SendSimpleRequest:
      type: object
      required:
        - message
        - recipients
        - sourceNumber
      properties:
        message:
          type: string
          example: متن تستی
        recipients:
          type: array
          items:
            type: string
          description: شماره‌های گیرنده (شماره موبایل معتبر ایران)
          example:
            - '09000000000'
            - '09000000001'
        sourceNumber:
          type: string
          description: سرشماره (شمارهٔ خط ارسال)
          example: '10001'
        scheduledAt:
          type: integer
          allOf:
            - $ref: '#/components/schemas/Api.unixTimestamp'
          nullable: true
          description: زمان ارسال پیامک بصورت تایم استمپ (ثانیه) (* حداقل ۱۵ دقیقه بعد از لحظه ارسال درخواست)
          example: 1776601215
      description: بدنهٔ درخواست ارسال پیامک ساده
    Api.SendSmsResponse:
      type: object
      required:
        - cost
        - message
        - uid
        - status
        - recipients
      properties:
        cost:
          type: string
          description: هزینهٔ پیامک (واحد SMS)
          example: '1540.00'
        message:
          type: string
          description: متن نهایی پیام ارسال‌شده
          example: |-
            کد تایید شما: 12345
            لغو11
        uid:
          type: string
          description: شناسهٔ یکتای درخواست (برای پیگیری در پنل کاربری)
          example: '17765023114093517'
        status:
          allOf:
            - $ref: '#/components/schemas/Api.SendSmsStatus'
          description: وضعیت درخواست
          example: CREATED
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Api.SendSmsResponseRecipient'
      description: پاسخ ارسال پیامک
    Api.SendSmsResponseRecipient:
      type: object
      required:
        - recipient
        - uid
      properties:
        recipient:
          type: string
          example: '+989000000000'
        uid:
          type: string
          example: A17765023114814282
    Api.SendSmsStatus:
      type: string
      enum:
        - CREATED
        - ACCEPTING
        - ACCEPTED
        - SENDING
        - FINISHED
        - REJECTED
        - CANCELED
        - FAILED
        - REPORTING
        - NO_BALANCE
    Api.SmsDeliveryStatus:
      type: string
      enum:
        - CREATED
        - SENDING
        - SENT
        - FAILED
        - REJECTED
        - CANCELED
        - SENDING_ERROR
        - NOT_DELIVERED_TO_MOBILE
        - DELIVERED_TO_MOBILE
        - DELIVERED_TO_TELE
        - SEND_TO_TELE
        - BLOCKED_LIST
    Api.TariffInfo:
      type: object
      required:
        - title
        - price
        - slug
      properties:
        title:
          type: string
          description: عنوان تعرفه
        price:
          type: string
          description: قیمت واحد
        slug:
          type: string
          description: اسلاگ تعرفه
      description: تعرفه (عنوان، قیمت، اسلاگ)
    Api.WalletUnit:
      type: string
      enum:
        - SMS_UNIT
        - IR
    Api.unixTimestamp:
      type: integer
      format: int64
      description: تایم استمپ (ثانیه)
    Common.ProblemResponseBody:
      type: object
      properties:
        type:
          type: string
          nullable: true
          description: نوع URI خطا
        title:
          type: string
          nullable: true
          description: عنوان کوتاه
        code:
          type: integer
          format: int32
          nullable: true
          description: کد وضعیت خطا
        detail:
          type: string
          nullable: true
          description: توضیح جزئیات
        instance:
          type: string
          nullable: true
          description: شناسه نمونه درخواست
    Common.ValidationResponseBody:
      type: object
      required:
        - extra
      properties:
        extra:
          type: array
          items:
            type: string
      allOf:
        - $ref: '#/components/schemas/Common.ProblemResponseBody'
    StatusCode:
      type: number
      enum:
        - 100
        - 101
        - 102
        - 103
        - 200
        - 201
        - 202
        - 203
        - 204
        - 205
        - 206
        - 207
        - 208
        - 226
        - 300
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
        - 308
        - 400
        - 401
        - 402
        - 403
        - 404
        - 405
        - 406
        - 407
        - 408
        - 409
        - 410
        - 411
        - 412
        - 413
        - 414
        - 415
        - 416
        - 417
        - 418
        - 421
        - 422
        - 423
        - 424
        - 425
        - 426
        - 428
        - 429
        - 431
        - 451
        - 500
        - 501
        - 502
        - 503
        - 504
        - 505
        - 506
        - 507
        - 508
        - 510
        - 511
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer
servers:
  - url: https://api.panelchi.com
    description: production
    variables: {}
