openapi: 3.1.0
info:
  title: Sen de Koş API
  version: 1.0.0
  description: |
    Sen de Koş kişisel ve kurumsal koşu antrenörlüğü web sitesi herkese açık form ve içerik uç noktaları.

    ## Versioning & Deprecation Policy
    - **URL Path Versioning:** Versiyonlu yazma uç noktaları `/api/v1/lead` ve `/api/v1/contact` yolları altında sunulur (`/api/lead` ve `/api/contact` geriye dönük uyumlu v1 takma adlarıdır).
    - **Header Versioning:** Her API yanıtı `X-API-Version: v1` başlığını döndürür; istemciler isteklerinde isteğe bağlı `X-API-Version: v1` (veya tarih sürümü `2026-11-15`) gönderebilir.
    - **Deprecation & Sunset Policy:** Geriye dönük uyumsuz değişiklik veya sürüm kaldırma işleminden en az 90 gün önce RFC 8594 uyumlu `Deprecation: true`, `Sunset: <HTTP-date>` ve `Link: <https://www.sendekos.com.tr/docs#deprecation>; rel="deprecation"` başlıkları yayımlanır; ayrıntılar `/docs#deprecation` ve `/llms.txt` üzerinde duyurulur.
  contact:
    name: Ercan Balioğlu — Sen de Koş
    email: ercan@sendekos.com.tr
    url: https://www.sendekos.com.tr/docs
externalDocs:
  description: Sen de Koş API Documentation & Developer Guide
  url: https://www.sendekos.com.tr/docs
servers:
  - url: https://www.sendekos.com.tr
    description: Production server (v1)
x-api-versioning:
  currentVersion: v1
  strategy:
    - url-path
    - header
  pathPrefix: /api/v1
  headerName: X-API-Version
  supportedVersions:
    - v1
    - "2026-11-15"
x-deprecation-policy:
  noticeWindowDays: 90
  headers:
    - Deprecation
    - Sunset
    - Link
  documentationUrl: https://www.sendekos.com.tr/docs#deprecation
paths:
  /api/v1/lead:
    post:
      operationId: submitGuideLeadV1
      summary: Başlangıç rehberi PDF talebi oluştur (v1)
      description: Kullanıcının mevcut koşu durumu ve hedeflerine göre Brevo listesine ekler ve 16 sayfalık başlangıç rehberi PDF bağlantısını e-posta ile gönderir.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LeadRequest"
      responses:
        "200":
          description: Rehber e-postası başarıyla gönderildi
          headers:
            X-API-Version:
              $ref: "#/components/headers/XApiVersion"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Sunset:
              $ref: "#/components/headers/Sunset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Geçersiz veya eksik alan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "405":
          description: Desteklenmeyen HTTP metodu (yalnız POST)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Sunucu yapılandırma hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Harici e-posta servisi hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/contact:
    post:
      operationId: submitContactFormV1
      summary: Bireysel veya kurumsal iletişim mesajı gönder (v1)
      description: Ön görüşme veya kurumsal koşu programı talebini Ercan Balioğlu'na iletir.
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactRequest"
      responses:
        "200":
          description: Mesaj başarıyla iletildi
          headers:
            X-API-Version:
              $ref: "#/components/headers/XApiVersion"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Sunset:
              $ref: "#/components/headers/Sunset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Geçersiz veya eksik alan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "405":
          description: Desteklenmeyen HTTP metodu (yalnız POST)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Sunucu yapılandırma hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Harici e-posta servisi hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/lead:
    post:
      operationId: submitGuideLead
      summary: Başlangıç rehberi PDF talebi oluştur (v1 takma ad)
      description: "`/api/v1/lead` ile aynı v1 sözleşmesini sunar. Kullanıcının mevcut koşu durumu ve hedeflerine göre Brevo listesine ekler ve 16 sayfalık başlangıç rehberi PDF bağlantısını e-posta ile gönderir."
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LeadRequest"
      responses:
        "200":
          description: Rehber e-postası başarıyla gönderildi
          headers:
            X-API-Version:
              $ref: "#/components/headers/XApiVersion"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Sunset:
              $ref: "#/components/headers/Sunset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Geçersiz veya eksik alan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "405":
          description: Desteklenmeyen HTTP metodu (yalnız POST)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Sunucu yapılandırma hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Harici e-posta servisi hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/contact:
    post:
      operationId: submitContactForm
      summary: Bireysel veya kurumsal iletişim mesajı gönder (v1 takma ad)
      description: "`/api/v1/contact` ile aynı v1 sözleşmesini sunar. Ön görüşme veya kurumsal koşu programı talebini Ercan Balioğlu'na iletir."
      parameters:
        - $ref: "#/components/parameters/ApiVersionHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactRequest"
      responses:
        "200":
          description: Mesaj başarıyla iletildi
          headers:
            X-API-Version:
              $ref: "#/components/headers/XApiVersion"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Sunset:
              $ref: "#/components/headers/Sunset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Geçersiz veya eksik alan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "405":
          description: Desteklenmeyen HTTP metodu (yalnız POST)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Sunucu yapılandırma hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Harici e-posta servisi hatası
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /blog/posts.json:
    get:
      operationId: listBlogPosts
      summary: Yayınlanan blog yazılarının dizinini listele
      description: Tarihe göre sıralanmış blog yazılarının başlık, özet, tarih, etiket ve dosya yollarını döndürür.
      responses:
        "200":
          description: Blog yazıları listesi
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BlogPostSummary"
components:
  parameters:
    ApiVersionHeader:
      name: X-API-Version
      in: header
      required: false
      description: İsteğe bağlı API sürüm seçicisi. Varsayılan sürüm v1'dir.
      schema:
        type: string
        default: v1
        enum: [v1, "2026-11-15"]
  headers:
    XApiVersion:
      description: Yanıtı üreten aktif API sürümü.
      schema:
        type: string
        example: v1
    Deprecation:
      description: RFC 8594 kullanımdan kaldırma bildirimi (kullanımdan kaldırılan sürümlerde 'true' olarak döner).
      schema:
        type: string
        example: "true"
    Sunset:
      description: RFC 8594 uyarınca uç noktanın kapatılacağı en erken tarih (en az 90 gün sonra, HTTP-date biçiminde).
      schema:
        type: string
        format: date-time
  schemas:
    LeadRequest:
      type: object
      required: [name, email, consent, durum, hedefler]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        phone:
          type: string
        consent:
          type: boolean
          const: true
        durum:
          type: string
          enum: [sifirdan, duzensiz, yuruyus, performans]
        hedefler:
          type: array
          minItems: 1
          items:
            type: string
            enum: [kilo, mesafe, stres, hiz]
        website:
          type: string
    ContactRequest:
      type: object
      required: [name, email, message]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        phone:
          type: string
        type:
          type: string
          enum: [bireysel, kurumsal]
          default: bireysel
        message:
          type: string
          minLength: 1
        website:
          type: string
    BlogPostSummary:
      type: object
      required: [slug, title, date, excerpt, author, tags, readingTime, file]
      properties:
        slug:
          type: string
        title:
          type: string
        date:
          type: string
          format: date
        excerpt:
          type: string
        author:
          type: string
        tags:
          type: array
          items:
            type: string
        coverImage:
          type: [string, "null"]
        readingTime:
          type: integer
        file:
          type: string
    SuccessResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
          const: true
    ErrorResponse:
      type: object
      required: [error, code, message, hint]
      properties:
        error:
          type: string
        code:
          type: string
        message:
          type: string
        hint:
          type: string
