openapi: 3.0.3
info:
  title: Quiksa Merchant API
  version: "1.0.0"
  description: |
    Quiksa Merchant REST API (v1). Her istekte Client ID + Client Secret ile kimlik doğrulama.
    Access token / OAuth yoktur.

    Header'lar:
    - `X-Quiksa-Client-Id`
    - `X-Quiksa-Client-Secret`

    Alternatif: `Authorization: Basic base64(client_id:client_secret)`
servers:
  - url: /api/v1
    description: Relative base path
tags:
  - name: Meta
  - name: Products
  - name: Categories
  - name: Brands
  - name: Orders
  - name: Customers
  - name: Conversations
paths:
  /me:
    get:
      tags: [Meta]
      summary: İşletme ve istemci bilgisi
      security:
        - ClientCredentials: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /products:
    get:
      tags: [Products]
      summary: Ürün listesi
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - name: q
          in: query
          schema:
            type: string
        - name: is_active
          in: query
          schema:
            type: boolean
      responses:
        "200":
          description: Paginated products
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Products]
      summary: Ürün oluştur
      security:
        - ClientCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, price]
              properties:
                name:
                  type: string
                price:
                  type: number
                sku:
                  type: string
                barcode:
                  type: string
                category_id:
                  type: integer
                brand_id:
                  type: integer
                stock_quantity:
                  type: integer
                is_active:
                  type: boolean
      responses:
        "201":
          description: Created
        "403":
          $ref: "#/components/responses/Forbidden"
  /products/{id}:
    get:
      tags: [Products]
      summary: Ürün detayı
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: OK
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags: [Products]
      summary: Ürün güncelle
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                price:
                  type: number
                is_active:
                  type: boolean
      responses:
        "200":
          description: OK
        "403":
          $ref: "#/components/responses/Forbidden"
  /categories:
    get:
      tags: [Categories]
      summary: Kategori listesi
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: OK
    post:
      tags: [Categories]
      summary: Kategori oluştur
      security:
        - ClientCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Created
  /categories/{id}:
    get:
      tags: [Categories]
      summary: Kategori detayı
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: OK
    patch:
      tags: [Categories]
      summary: Kategori güncelle
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "200":
          description: OK
  /brands:
    get:
      tags: [Brands]
      summary: Marka listesi
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: OK
    post:
      tags: [Brands]
      summary: Marka oluştur
      security:
        - ClientCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Created
  /brands/{id}:
    get:
      tags: [Brands]
      summary: Marka detayı
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: OK
    patch:
      tags: [Brands]
      summary: Marka güncelle
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "200":
          description: OK
  /orders:
    get:
      tags: [Orders]
      summary: Sipariş listesi
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - name: status
          in: query
          schema:
            type: string
        - name: q
          in: query
          schema:
            type: string
      responses:
        "200":
          description: OK
  /orders/{id}:
    get:
      tags: [Orders]
      summary: Sipariş detayı
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: OK
    patch:
      tags: [Orders]
      summary: Sipariş durumu / takip güncelle
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                tracking_number:
                  type: string
                shipping_carrier:
                  type: string
      responses:
        "200":
          description: OK
  /customers:
    get:
      tags: [Customers]
      summary: Müşteri listesi
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: OK
  /customers/{id}:
    get:
      tags: [Customers]
      summary: Müşteri detayı
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: OK
  /conversations:
    get:
      tags: [Conversations]
      summary: Konuşma listesi
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: OK
  /conversations/{id}:
    get:
      tags: [Conversations]
      summary: Konuşma detayı (mesajlar dahil)
      security:
        - ClientCredentials: []
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: OK
components:
  securitySchemes:
    ClientCredentials:
      type: apiKey
      in: header
      name: X-Quiksa-Client-Id
      description: |
        Ayrıca `X-Quiksa-Client-Secret` header'ı zorunludur.
        Alternatif: Basic auth ile `client_id:client_secret`.
  parameters:
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Kimlik doğrulama başarısız
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Plan veya scope yetersiz
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Kaynak bulunamadı
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        errors:
          type: object
          additionalProperties: true
security:
  - ClientCredentials: []
