openapi: 3.1.0
info:
  title: Sözleşme Cepte API
  description: |
    Türkiye'nin en büyük açık hukuki veri sağlayıcısı.
    273 sözleşme şablonu + 315 hesaplama aracı + AI sözleşme analizi.

    Authentication: Bearer scp_YOUR_KEY (https://sozlesmecepte.com/hesabim/api-keys)
    Rate limit: 60/dk · 1.000/gün (Free), Startup'tan itibaren artar.

    Docs: https://sozlesmecepte.com/dokumentasyon
  version: 1.0.0
  contact:
    email: destek@sozlesmecepte.com
    url: https://sozlesmecepte.com/iletisim
  license:
    name: API Terms — see /kullanim-kosullari
    url: https://sozlesmecepte.com/kullanim-kosullari

servers:
  - url: https://sozlesmecepte.com
    description: Production

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: scp_<32-char-base62>
  responses:
    Unauthorized:
      description: API key eksik veya geçersiz
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimit:
      description: Rate limit aşıldı (per minute veya per day)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_api_key
            message:
              type: string
    Template:
      type: object
      properties:
        slug: { type: string, example: konut-kira-sozlesmesi }
        name: { type: string }
        category: { type: string }
        estimated_minutes: { type: integer }
        question_count: { type: integer }
        version: { type: string }
        url: { type: string, format: uri }
    Calculation:
      type: object
      properties:
        slug: { type: string, example: kidem-tazminati }
        name: { type: string }
        category: { type: string }
        description: { type: string }
        url: { type: string, format: uri }

paths:
  /api/v1/templates:
    get:
      summary: Tüm sözleşme şablonlarını listele
      tags: [Templates]
      parameters:
        - { name: category, in: query, schema: { type: string }, description: "Kategori filtresi" }
        - { name: limit, in: query, schema: { type: integer, default: 50, maximum: 200 } }
        - { name: offset, in: query, schema: { type: integer, default: 0 } }
      responses:
        "200":
          description: Şablon listesi
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Template" }
                  meta: { type: object }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimit" }

  /api/v1/templates/{slug}:
    get:
      summary: Şablon detayı (soru/alan listesi)
      tags: [Templates]
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Detay }
        "404": { description: Şablon bulunamadı }

  /api/v1/templates/{slug}/generate:
    post:
      summary: Sözleşme oluştur (placeholder'lar dolu content/DOCX)
      tags: [Templates]
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  description: "question_id → answer dict"
                  additionalProperties: { type: string }
                format:
                  type: string
                  enum: [text, html, docx]
                  default: text
      responses:
        "200":
          description: Üretilen sözleşme (format'a göre JSON veya binary DOCX)
        "404": { description: Şablon bulunamadı }
      security:
        - bearerAuth: [write]

  /api/v1/calculations:
    get:
      summary: Tüm hesaplama araçlarını listele
      tags: [Calculations]
      parameters:
        - { name: category, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 100, maximum: 500 } }
      responses:
        "200":
          description: Araç listesi
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Calculation" }

  /api/v1/calculations/{slug}:
    get:
      summary: Hesaplama aracı detayı (input/output şeması)
      tags: [Calculations]
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Detay }
        "404": { description: Araç bulunamadı }

  /api/v1/calculations/{slug}/compute:
    post:
      summary: Hesaplama yap (input → result)
      tags: [Calculations]
      parameters:
        - { name: slug, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [inputs]
              properties:
                inputs:
                  type: object
                  example:
                    son_brut_maas: 35000
                    ise_baslangic: "2020-01-15"
                    is_son: "2026-05-19"
      responses:
        "200": { description: Hesap sonucu }
        "422": { description: Input hatası veya formula hatası }
