{
  "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ı.\n\n## Versioning & Deprecation Policy\n- **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).\n- **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.\n- **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, "description": "Başvuranın ad soyadı" },
          "email": { "type": "string", "format": "email", "description": "Rehber PDF bağlantısının gönderileceği e-posta adresi" },
          "phone": { "type": "string", "description": "Opsiyonel telefon numarası" },
          "consent": { "type": "boolean", "const": true, "description": "Bilgilendirme ve iletişim onayı" },
          "durum": {
            "type": "string",
            "enum": ["sifirdan", "duzensiz", "yuruyus", "performans"],
            "description": "Mevcut koşu deneyimi düzeyi"
          },
          "hedefler": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": ["kilo", "mesafe", "stres", "hiz"]
            },
            "description": "Seçilen koşu hedefleri"
          },
          "website": {
            "type": "string",
            "description": "Honeypot alanı — gerçek kullanıcılar boş bırakmalıdır"
          }
        }
      },
      "ContactRequest": {
        "type": "object",
        "required": ["name", "email", "message"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "description": "Ad soyad" },
          "email": { "type": "string", "format": "email", "description": "Yanıt e-posta adresi" },
          "phone": { "type": "string", "description": "Opsiyonel telefon numarası" },
          "type": {
            "type": "string",
            "enum": ["bireysel", "kurumsal"],
            "default": "bireysel",
            "description": "Talep türü"
          },
          "message": { "type": "string", "minLength": 1, "description": "Mesaj veya ön görüşme notu" },
          "website": {
            "type": "string",
            "description": "Honeypot alanı — gerçek kullanıcılar boş bırakmalıdır"
          }
        }
      },
      "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", "description": "Kısa hata özeti" },
          "code": { "type": "string", "description": "Makine tarafından okunabilir hata kodu" },
          "message": { "type": "string", "description": "Okunabilir ayrıntılı hata açıklaması" },
          "hint": { "type": "string", "description": "Çözüm veya düzeltme önerisi" }
        }
      }
    }
  }
}
