openapi: 3.0.3
info:
  title: OAuth
  version: 1.0.0
  description: |-
    Ideasoft API'leri OAuth 2.0 authorization-code akışı ile yetkilendirilir.
    Mağaza yöneticisi `/panel/auth` adresinde uygulamanıza yetki verir; dönen `code`
    ile `/oauth/v2/token` endpoint'inden access token alırsınız.
    Adım adım anlatım için [Kimlik Doğrulama](/getting-started/authentication) rehberine bakın.
servers:
  - url: https://{host}
    description: Mağazanızın alan adı
    variables:
      host:
        default: magaza-adiniz.myideasoft.com
        description: >-
          Mağazanızın alan adı: myideasoft alt alan adınız
          (magaza-adiniz.myideasoft.com) veya mağazanıza bağlı kendi alan
          adınız (www.magaza-adiniz.com)
tags:
  - name: OAuth
    description: OAuth 2.0 authorization-code akışı endpoint'leri.
paths:
  /panel/auth:
    get:
      operationId: oauth_authorize
      security: []
      tags: [OAuth]
      x-zudoku-playground-enabled: false
      summary: Yetkilendirme (authorize)
      description: |-
        Mağaza yöneticisini uygulamanızın yetki sayfasına yönlendirir. Onay sonrası
        tarayıcı `redirect_uri?code=...&state=...` adresine döner.
        İzinler (scope) istek başına istenmez; mağaza panelindeki
        (Entegrasyonlar → API) API tanımıyla sabittir.
      parameters:
        - name: client_id
          in: query
          required: true
          schema: { type: string }
          description: Uygulamanıza verilen istemci kimliği.
        - name: redirect_uri
          in: query
          required: true
          schema: { type: string, format: uri }
          description: Yetkilendirme sonrası dönüş adresi.
        - name: response_type
          in: query
          required: true
          schema: { type: string, enum: [code] }
          description: Her zaman `code`.
        - name: state
          in: query
          required: false
          schema: { type: string }
          description: CSRF koruması için rastgele değer; geri dönüşte doğrulanmalı.
      responses:
        "302":
          description: Başarılı yetkilendirme; `redirect_uri?code=...&state=...` adresine yönlendirme.
  /oauth/v2/token:
    post:
      operationId: oauth_token
      security: []
      tags: [OAuth]
      x-zudoku-playground-enabled: false
      summary: Token alma / yenileme
      description: |-
        `authorization_code` grant'i ile ilk token'ı, `refresh_token` grant'i ile
        yeni token alır. `client_id`/`client_secret` gövdede veya HTTP Basic
        Authorization başlığında gönderilebilir.

        Grant'e göre zorunlu parametreler:
        - `authorization_code`: `client_id`, `client_secret`, `code`, `redirect_uri`
        - `refresh_token`: `client_id`, `client_secret`, `refresh_token`
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [authorization_code, refresh_token]
                  description: Token alma yöntemi.
                client_id:
                  type: string
                  description: İstemci kimliği (Basic auth başlığı da kabul edilir).
                client_secret:
                  type: string
                  description: İstemci gizli anahtarı.
                code:
                  type: string
                  description: "`authorization_code` grant'i için zorunlu; authorize adımında dönen kod."
                redirect_uri:
                  type: string
                  format: uri
                  description: "`authorization_code` grant'i için zorunlu; authorize adımındaki adres ile aynı olmalı."
                refresh_token:
                  type: string
                  description: "`refresh_token` grant'i için zorunlu; önceki yanıttaki yenileme anahtarı."
      responses:
        "200":
          description: Token başarıyla üretildi.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: { type: string }
                  expires_in: { type: integer, description: Token ömrü (saniye). }
                  token_type: { type: string, enum: [bearer] }
                  scope: { type: string, description: Boşlukla ayrılmış scope listesi. }
                  refresh_token: { type: string }
              example:
                access_token: MmQyYzA0Zjc4YzA0OWY...
                expires_in: 3600
                token_type: bearer
                scope: catalog_read order_read
                refresh_token: NzQx...
        "400":
          description: Hatalı istek; standart OAuth2 hata gövdesi döner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  error_description: { type: string }
              example:
                error: invalid_grant
                error_description: Code doesn't exist or is invalid for the client
