# Support paths use the existing project route names: /contact and /complaint.

contact:
  post:
    tags: [Common]
    summary: Send a contact message
    description: |
      Accepts messages from guests, authenticated clients, and authenticated providers.
      Guest requests must include `name`, `countryCode`, and `phone`; authenticated users
      may omit profile fields. A supplied bearer token must be valid and is never ignored.

      <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=9462-8846&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">Client 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=10411-116620&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27183&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=10411-116620&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:
      clientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8846&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      clientMobileNodeId: "9462:8846"
      clientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116620&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      clientWebNodeId: "10411:116620"
      providerMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27183&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      providerMobileNodeId: "9967:27183"
      providerWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116620&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      providerWebNodeId: "10411:116620"
    operationId: createContactMessage
    security:
      - SecretKeyAuth: []
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [message]
            additionalProperties: false
            properties:
              name:
                type: string
                minLength: 2
                maxLength: 80
                description: Required for guests unless available on the authenticated profile.
                example: "Example User"
              countryCode:
                type: string
                maxLength: 10
                description: Required for guests unless available on the authenticated profile.
                example: "+966"
              phone:
                type: string
                description: Required for guests unless available on the authenticated profile.
                example: "0500000000"
              message:
                type: string
                minLength: 5
                maxLength: 2000
                example: "أرغب في معرفة المزيد عن الخدمة."
          examples:
            guest:
              summary: Guest contact message
              value:
                name: "Example User"
                countryCode: "+966"
                phone: "0500000000"
                message: "أرغب في معرفة المزيد عن الخدمة."
            authenticated:
              summary: Client/provider using profile contact fields
              value:
                message: "أحتاج مساعدة بخصوص حسابي."
    responses:
      '200':
        description: Contact message saved.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ContactMessageCreatedResponse' }
            example:
              key: success
              message: "تم إرسال رسالتك بنجاح"
              status: 200
              data: { id: "665f1c2a9b4e1d0012ab34d1", status: new }
      '400':
        description: Contact message validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              missingMessage:
                value: { key: fail, message: "نص الرسالة مطلوب", status: 400 }
              invalidName:
                value: { key: fail, message: "الاسم يجب أن يكون من 2 إلى 80 حرفًا", status: 400 }
              missingGuestPhone:
                value: { key: fail, message: "رقم الجوال مطلوب", status: 400 }
      '419':
        description: A bearer token was supplied but is missing, invalid, expired, or revoked.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

complaint:
  post:
    tags: [Common]
    summary: Create a complaint or suggestion
    description: |
      Creates a complaint/suggestion for the authenticated client or provider. Ownership
      is always taken from the bearer token; `userId` and `userType` are not accepted.

      <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=9474-6355&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">Client 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=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&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=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma: &complaints-figma
      clientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9474-6355&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      clientMobileNodeId: "9474:6355"
      clientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      clientWebNodeId: "10257:123105"
      providerMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      providerMobileNodeId: "9967:27568"
      providerWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      providerWebNodeId: "10762:101717"
    operationId: createComplaint
    security: &complaints-security
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [title, message]
            additionalProperties: false
            properties:
              title:
                type: string
                minLength: 3
                maxLength: 120
                example: "عنوان الشكوى / المقترح"
              message:
                type: string
                minLength: 5
                maxLength: 3000
                example: "نص الشكوى / المقترح"
          example:
            title: "عنوان الشكوى / المقترح"
            message: "نص الشكوى / المقترح"
    responses:
      '200':
        description: Complaint/suggestion saved with pending status.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ComplaintCreatedResponse' }
            example:
              key: success
              message: "تم إرسال الشكوى/المقترح بنجاح"
              status: 200
              data: { id: "665f1c2a9b4e1d0012ab34d2", number: "12315", status: pending }
      '400':
        description: Complaint title or message validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              missingTitle:
                value: { key: fail, message: "عنوان الشكوى/المقترح مطلوب", status: 400 }
              invalidMessageLength:
                value: { key: fail, message: "نص الشكوى/المقترح يجب أن يكون من 5 إلى 3000 حرف", status: 400 }
      '419': { $ref: '#/shared-unauthorized' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

  get:
    tags: [Common]
    summary: List my complaints and suggestions
    description: |
      Returns only records owned by the authenticated client/provider, newest first.
      Optional status filtering supports exactly `pending`, `in_progress`, and `replied`.

      <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=9474-6355&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">Client 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=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&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=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma:
      <<: *complaints-figma
    operationId: listMyComplaints
    security: *complaints-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum: [pending, in_progress, replied]
        description: Filter by complaint/suggestion status.
      - 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: 10 }
    responses:
      '200':
        description: Paginated complaints/suggestions owned by the token holder.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ComplaintListResponse' }
            example:
              key: success
              message: "قائمة الشكاوى"
              status: 200
              data:
                - { id: "665f1c2a9b4e1d0012ab34d2", title: "عنوان الشكوى / المقترح" }
              paginate: { currentPage: 1, lastPage: 1, perPage: 10, total: 1 }
      '400':
        description: Complaint filter or pagination validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              invalidStatus:
                value: { key: fail, message: "حالة الشكوى يجب أن تكون pending أو in_progress أو replied", status: 400 }
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '419': { $ref: '#/shared-unauthorized' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

complaint-details:
  get:
    tags: [Common]
    summary: Get my complaint or suggestion details
    description: |
      Resolves the record by the required query parameter `id` and returns it only when
      it belongs to the authenticated token holder. Another user's id is returned as not found.

      <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=9474-6355&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">Client 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=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&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=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Provider Web</a></div>
    x-figma:
      <<: *complaints-figma
    operationId: getMyComplaintDetails
    security: *complaints-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: id
        in: query
        required: true
        schema: { type: string }
        description: Complaint/Suggestion id.
        example: "665f1c2a9b4e1d0012ab34d2"
    responses:
      '200':
        description: Complaint/suggestion details owned by the token holder.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ComplaintDetailsResponse' }
            example:
              key: success
              message: "تفاصيل الشكوى"
              status: 200
              data:
                id: "665f1c2a9b4e1d0012ab34d2"
                number: "#12315"
                title: "عنوان الشكوى / المقترح"
                status: pending
                statusText: "في انتظار الرد"
                createdAt: "٢٠٢٦/٠٧/٢٣"
                message: "نص الشكوى / المقترح"
                adminReply: ""
      '400':
        description: Complaint id is missing/malformed, or the owned complaint was not found.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              missingId:
                value: { key: fail, message: "معرف الشكوى/المقترح مطلوب", status: 400 }
              invalidId:
                value: { key: fail, message: "معرف الشكوى/المقترح غير صالح", status: 400 }
              complaintNotFound:
                value: { key: fail, message: "الشكوى غير موجودة", status: 400 }
      '419': { $ref: '#/shared-unauthorized' }
      '423': { $ref: '#/shared-blocked' }
      '500': { $ref: '#/shared-server-error' }

attributes:
  get:
    tags: [Lookups]
    summary: List product attributes
    description: |
      Public catalogue of the active product attributes created by the administration
      (id + name only). Each attribute's selectable sizes and colors are fetched via
      the dedicated `/attributes/sizes?id=...` and `/attributes/colors?id=...` endpoints.

      Providers pick an existing attribute and its values when publishing a product;
      they never create attributes or values themselves.

      <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-23616&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">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=10767-135919&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23616&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:23616"
      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=10767-135919&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10767:135919"
    operationId: listAttributes
    security: &attributes-security
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - 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 list of active attributes.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/AttributeListResponse' }
            example:
              key: success
              message: "قائمة السمات"
              status: 200
              data:
                - { id: "665f1c2a9b4e1d0012ab34e8", name: "المقاس" }
              paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Attribute pagination validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '500': { $ref: '#/shared-server-error' }

attribute-colors:
  get:
    tags: [Lookups]
    summary: List a single attribute's colors
    description: |
      Paginated colors (`kind = color`) of one attribute, oldest first.
      Each item carries a HEX `colorCode`.

      <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-23682&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">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=10767-136553&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma: &attribute-size-color-figma
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23682&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:23682"
      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=10767-136553&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10767:136553"
    operationId: listAttributeColors
    security: *attributes-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: id
        in: query
        required: true
        schema: { type: string }
        description: Attribute id. Must reference an existing active attribute.
        example: "665f1c2a9b4e1d0012ab34e7"
      - 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 list of the attribute's active colors.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/AttributeColorListResponse' }
            example:
              key: success
              message: "قائمة ألوان السمة"
              status: 200
              data:
                - { id: "665f1c2a9b4e1d0012ab34e9", name: "أخضر", colorCode: "#00ff04" }
              paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Attribute id/pagination validation failed, or the attribute was not found.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: &attribute-values-validation-examples
              missingId:
                value: { key: fail, message: "معرف السمة مطلوب", status: 400 }
              invalidId:
                value: { key: fail, message: "معرف السمة غير صالح", status: 400 }
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              attributeNotFound:
                value: { key: fail, message: "السمة غير موجودة", status: 400 }
      '500': { $ref: '#/shared-server-error' }

attribute-sizes:
  get:
    tags: [Lookups]
    summary: List a single attribute's sizes
    description: |
      Paginated sizes (`kind = size`) of one attribute, oldest first.

      <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-23682&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">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=10767-136553&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma: *attribute-size-color-figma
    operationId: listAttributeSizes
    security: *attributes-security
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: id
        in: query
        required: true
        schema: { type: string }
        description: Attribute id. Must reference an existing active attribute.
        example: "665f1c2a9b4e1d0012ab34e7"
      - 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 list of the attribute's active sizes.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/AttributeSizeListResponse' }
            example:
              key: success
              message: "قائمة أحجام السمة"
              status: 200
              data:
                - { id: "665f1c2a9b4e1d0012ab34f1", name: "كبير" }
              paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Attribute id/pagination validation failed, or the attribute was not found.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: *attribute-values-validation-examples
      '500': { $ref: '#/shared-server-error' }

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

shared-unauthorized:
  description: Client/provider token is missing, invalid, expired, revoked, or unsupported.
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
      example: { key: unauthorized, message: "يجب تسجيل الدخول", status: 419 }

shared-blocked:
  description: The authenticated 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 }
