due-financials:
  get:
    tags: [Provider Settlements]
    summary: Get provider due financials
    description: |
      Returns only eligible financial transactions owned by the authenticated provider.
      Eligibility follows the existing backend rule: the related order must be finished,
      the transaction must be pending or rejected, and it must not already be held by a
      settlement.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28134&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10763-107621&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: &due-financials-figma
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28134&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      appNodeId: "9967:28134"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10763-107621&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10763:107621"
    operationId: getProviderDueFinancials
    security: &provider-security
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Provider due-financial summary and eligible transaction page.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/DueFinancialsResponse'
            examples:
              available:
                summary: Provider has eligible dues
                value:
                  key: success
                  message: "المعاملات المالية"
                  status: 200
                  data:
                    id: ""
                    totalPriceTranslated: "إجمالي الطلبات"
                    totalPriceText: "300 ر.س"
                    totalPrice: 300
                    totalAppCommissionTranslated: "إجمالي العمولة"
                    totalAppCommissionText: "50 ر.س"
                    totalAppCommission: 50
                    totalVatPriceTranslated: "إجمالي القيمة المضافة"
                    totalVatPriceText: "0 ر.س"
                    totalVatPrice: 0
                    totalTranslated: "إجمالي المستحق"
                    totalText: "250 ر.س"
                    total: 250
                    currency: "ر.س"
                    financials: []
                    settelmentDebitBtn: true
                  paginate:
                    currentPage: 1
                    lastPage: 1
                    perPage: 20
                    total: 1
      '401': { $ref: '#/shared-unauthorized-standard' }
      '419': { $ref: '#/shared-unauthorized-legacy' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

settlements:
  get:
    tags: [Provider Settlements]
    summary: List provider settlements
    description: |
      Returns only settlement requests owned by the authenticated provider, newest first.
      `pending` filters pending requests. `finished` maps to accepted and rejected requests.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28457&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-83084&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28457&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      appNodeId: "9967:28457"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-83084&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10764:83084"
    operationId: listProviderSettlements
    security: *provider-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: status
        in: query
        required: true
        schema:
          type: string
          enum: [pending, finished]
        description: Required status filter. `pending` = awaiting admin action. `finished` = accepted or rejected.
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    responses:
      '200':
        description: Paginated settlement requests owned by the provider.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/SettlementListResponse'
            example:
              key: success
              message: "التسويات"
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34d0"
                  orderNumberTranslated: "رقم الطلب"
                  orderNumber: "#15"
                  settlementNumber: 15
                  orderTimeTranslated: "وقت الطلب"
                  orderTime: "20:00"
                  priceText: "قيمة الطلب"
                  price: "300 ر.س"
                  priceNum: 300
                  appCommissionTextTranslated: "العمولة"
                  appCommissionText: "50 ر.س"
                  appCommission: 50
                  vatPriceTextTranslated: "القيمة المضافة"
                  vatPriceText: "0 ر.س"
                  vatPrice: 0
                  totalTranslated: "إجمالي المستحق"
                  totalText: "250 ر.س"
                  total: 250
                  amount: 250
                  status: pending
                  statusText: "قيد المراجعة"
                  createdAt: "منذ دقيقة"
                  createdAtIso: "2026-07-23T10:44:37.414Z"
                  processedAt: null
              paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Settlement status filter or pagination validation failed.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'
            examples:
              missingStatus:
                value: { key: fail, message: "حالة مطلوب يرجي ادخال البيانات", status: 400 }
              invalidStatus:
                value: { key: fail, message: "حالة التسوية يجب أن تكون من بين القيم التالية [pending, finished]", status: 400 }
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '401': { $ref: '#/shared-unauthorized-standard' }
      '419': { $ref: '#/shared-unauthorized-legacy' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

settlement-details:
  post:
    tags: [Provider Settlements]
    summary: Request settlement of all available dues
    description: |
      Creates one pending settlement for all currently eligible provider transactions.
      The existing backend settles the complete available amount; no `amount`, `userId`,
      or `providerId` field is accepted. Eligible transactions are held before the
      settlement is created so they cannot be requested again.
      Bank account fields (`bankName`, `accountName`, `accountNumber`, `iban`) are
      required in the body and persisted on the provider profile.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28134&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10763-107621&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma:
      <<: *due-financials-figma
    operationId: requestProviderSettlement
    security: *provider-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../openapi.yaml#/components/schemas/SettlementRequest'
          examples:
            online:
              summary: Request full settlement by bank transfer
              value:
                bankName: "الراجحي"
                accountName: "متجر زفييرا"
                accountNumber: "1234567890"
                iban: "SA0380000000608010167519"
            wallet:
              summary: Request full settlement with bank details
              value:
                bankName: "الراجحي"
                accountName: "متجر زفييرا"
                accountNumber: "1234567890"
                iban: "SA0380000000608010167519"
        application/json:
          schema:
            $ref: '../openapi.yaml#/components/schemas/SettlementRequest'
    responses:
      '200':
        description: Settlement request created with pending status.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/SettlementCreatedResponse'
            example:
              key: success
              message: "تم إرسال طلب التسوية بنجاح"
              status: 200
              data:
                id: "665f1c2a9b4e1d0012ab34d0"
                settlementNumber: 15
                amount: 250
                totalTranslated: "المستحق"
                totalText: "250 ر.س"
                total: 250
                status: pending
                statusText: "قيد الانتظار"
                createdAt: "منذ دقيقة"
                createdAtIso: "2026-07-23T10:44:37.414Z"
                processedAt: null
      '400':
        description: Validation failed for payment method or bank fields.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'
            examples:
              incompleteBankInformation:
                value: { key: fail, message: "يرجى استكمال بيانات الحساب البنكي قبل طلب التسوية", status: 400 }
      '401': { $ref: '#/shared-unauthorized-standard' }
      '409':
        description: Settlement creation is currently blocked by a business rule.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/SettlementConflictResponse'
            examples:
              pending:
                value:
                  key: fail
                  message: "لا يمكن إرسال طلب تسوية حاليًا"
                  status: 409
                  data:
                    reason: pending_settlement_exists
              noEligibleTransactions:
                value:
                  key: fail
                  message: "لا يمكن إرسال طلب تسوية حاليًا"
                  status: 409
                  data:
                    reason: no_eligible_financial_transactions
      '419': { $ref: '#/shared-unauthorized-legacy' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }
  get:
    tags: [Provider Settlements]
    summary: Get provider settlement details
    description: |
      Resolves the settlement by the required query parameter `id` and returns it only
      when it belongs to the authenticated provider.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9967-28216&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Provider Mobile</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9967-28216&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      appNodeId: "9967:28216"
    operationId: getProviderSettlementDetails
    security: *provider-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: id
        in: query
        required: true
        schema:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        description: Settlement Mongo ObjectId.
        example: "665f1c2a9b4e1d0012ab34d0"
    responses:
      '200':
        description: Settlement details owned by the authenticated provider.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/SettlementDetailsResponse'
            example:
              key: success
              message: "تفاصيل التسوية"
              status: 200
              data:
                id: "665f1c2a9b4e1d0012ab34d0"
                totalPrice: 300
                totalAppCommission: 50
                totalVatPrice: 0
                total: 250
                currency: "ر.س"
                financials:
                  - id: "665f1c2a9b4e1d0012ab34d1"
                    orderNumber: "#1201"
                    price: "300 ر.س"
                    priceNum: 300
                    vatPrice: 0
                    appCommission: 50
                    total: 250
                settelmentDebitBtn: true
                status: pending
                statusText: "قيد الانتظار"
                settlementNumber: 15
                amount: 250
                createdAt: "منذ دقيقة"
                createdAtIso: "2026-07-23T10:44:37.414Z"
                processedAt: null
                adminNote: null
                paymentMethod: online
      '400':
        description: Settlement id is missing or malformed.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'
            examples:
              missingId:
                value: { key: fail, message: "id مطلوب يرجي ادخال البيانات", status: 400 }
              invalidId:
                value: { key: fail, message: "بالشكل الصحيح id يرجي ادخال", status: 400 }
      '401': { $ref: '#/shared-unauthorized-standard' }
      '404':
        description: Settlement was not found or is not owned by the authenticated provider.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
            example:
              key: fail
              message: "التسوية غير متاحة"
              status: 404
      '419': { $ref: '#/shared-unauthorized-legacy' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

shared-validation:
  description: Request validation failed.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'

shared-unauthorized-standard:
  description: Standard unauthorized response for clients that normalize the legacy auth status to HTTP 401.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 401 }

shared-unauthorized-legacy:
  description: The current authentication middleware returns HTTP 419 for a missing, invalid, expired, or wrong-account-type token.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }

shared-blocked:
  description: The authenticated provider account is blocked.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: blocked, message: "حسابك موقوف حالياً", status: 423 }

shared-server-error:
  description: Unexpected server error without a stack trace.
  content:
    application/json:
      schema:
        $ref: '../openapi.yaml#/components/schemas/ErrorResponse'
      example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }
