{
  "openapi": "3.1.0",
  "info": {
    "title": "Her Şey Pazar Public API",
    "version": "2.0.0",
    "description": "Her Şey Pazar Marketplace public API (v2). Her ilan, sipariş, ödeme ve webhook işlemini yönetir. KVKK 6698 + ISO 27001:2022 uyumlu, argon2id key_hash + HMAC SHA-256 webhook imzası ile korunur.",
    "termsOfService": "https://herseypazar.com/sozlesmeler/api-kullanim",
    "contact": {
      "name": "API Destek",
      "url": "https://developers.herseypazar.com",
      "email": "developers@herseypazar.com"
    },
    "license": { "name": "Proprietary", "url": "https://herseypazar.com/sozlesmeler/api-kullanim" }
  },
  "servers": [
    { "url": "https://api.herseypazar.com/v2", "description": "Production" },
    { "url": "https://api-sandbox.herseypazar.com/v2", "description": "Sandbox" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "auth", "description": "Token ve OAuth akışları" },
    { "name": "sellers", "description": "Satıcı yönetimi" },
    { "name": "listings", "description": "İlan oluşturma/güncelleme" },
    { "name": "orders", "description": "Sipariş yaşam döngüsü" },
    { "name": "payments", "description": "Ödeme + iade" },
    { "name": "search", "description": "Arama + öneri" },
    { "name": "webhooks", "description": "Olay abonelikleri" },
    { "name": "categories", "description": "Kategori ağacı" },
    { "name": "shipping", "description": "Kargo + takip" }
  ],
  "paths": {
    "/auth/token": {
      "post": {
        "tags": ["auth"],
        "summary": "API anahtarından erişim token üret",
        "operationId": "createAccessToken",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } }
        },
        "responses": {
          "200": { "description": "Token üretildi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/auth/whoami": {
      "get": {
        "tags": ["auth"],
        "summary": "Aktif API anahtarının yetki ve tier bilgisi",
        "operationId": "getCurrentIdentity",
        "responses": {
          "200": { "description": "Identity döndü", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }
        }
      }
    },
    "/sellers": {
      "get": {
        "tags": ["sellers"],
        "summary": "Satıcı arama / listeleme",
        "operationId": "listSellers",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Görünür isimde arama" },
          { "name": "tier", "in": "query", "schema": { "type": "string", "enum": ["bronze", "silver", "gold", "platinum"] } },
          { "name": "city_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Sayfalı satıcı listesi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerListResponse" } } } }
        }
      }
    },
    "/sellers/{id}": {
      "get": {
        "tags": ["sellers"],
        "summary": "Satıcı detayı (KYC + rating + politikalar)",
        "operationId": "getSellerById",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Detay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seller" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/listings": {
      "get": {
        "tags": ["listings"],
        "summary": "İlan arama (kategori, fiyat, şehir, marka)",
        "operationId": "searchListings",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Kategori slug — örn. elektronik/telefon" },
          { "name": "min_price", "in": "query", "schema": { "type": "number" } },
          { "name": "max_price", "in": "query", "schema": { "type": "number" } },
          { "name": "city_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "condition", "in": "query", "schema": { "type": "string", "enum": ["new", "used", "refurbished"] } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "price_asc", "price_desc", "popular"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Sayfalı ilan listesi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingListResponse" } } } }
        }
      },
      "post": {
        "tags": ["listings"],
        "summary": "Yeni ilan yayınla",
        "operationId": "createListing",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingCreate" } } } },
        "responses": {
          "201": { "description": "Yayınlandı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "description": "İlan kredisi yetersiz" }
        }
      }
    },
    "/listings/{id}": {
      "get": {
        "tags": ["listings"],
        "summary": "İlan detayı",
        "operationId": "getListingById",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Detay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "patch": {
        "tags": ["listings"],
        "summary": "İlan güncelle",
        "operationId": "updateListing",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingUpdate" } } } },
        "responses": {
          "200": { "description": "Güncellendi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }
        }
      },
      "delete": {
        "tags": ["listings"],
        "summary": "İlan kaldır (soft-delete)",
        "operationId": "deleteListing",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Silindi" } }
      }
    },
    "/orders": {
      "get": {
        "tags": ["orders"],
        "summary": "Sipariş listele (filtrele)",
        "operationId": "listOrders",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "paid", "processing", "shipped", "delivered", "cancelled", "refunded"] } },
          { "name": "buyer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          { "name": "seller_id", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Sayfalı sipariş listesi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "tags": ["orders"],
        "summary": "Sipariş detayı (kalemler + kargo + ödeme)",
        "operationId": "getOrderById",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Detay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }
        }
      }
    },
    "/orders/{id}/cancel": {
      "post": {
        "tags": ["orders"],
        "summary": "Siparişi iptal et",
        "operationId": "cancelOrder",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": ["reason"] } } } },
        "responses": { "200": { "description": "İptal edildi" }, "409": { "description": "İptal edilemez aşamada" } }
      }
    },
    "/orders/{id}/ship": {
      "post": {
        "tags": ["orders"],
        "summary": "Kargoya ver (takip kodu kaydet)",
        "operationId": "shipOrder",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentCreate" } } } },
        "responses": { "200": { "description": "Kargoda" } }
      }
    },
    "/payments/{id}/refund": {
      "post": {
        "tags": ["payments"],
        "summary": "Ödemeyi iade et",
        "operationId": "refundPayment",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "reason": { "type": "string" } } } } } },
        "responses": { "200": { "description": "İade kuyruklandı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } } }
      }
    },
    "/categories": {
      "get": {
        "tags": ["categories"],
        "summary": "Kategori ağacı (ana + alt)",
        "operationId": "listCategories",
        "security": [],
        "responses": {
          "200": { "description": "Hiyerarşik kategori listesi", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } }
        }
      }
    },
    "/search/suggest": {
      "get": {
        "tags": ["search"],
        "summary": "Arama önerileri (auto-complete)",
        "operationId": "suggestSearch",
        "security": [],
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 8 } }
        ],
        "responses": {
          "200": { "description": "Öneri listesi", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "category": { "type": "string" } } } } } } } } }
        }
      }
    },
    "/shipping/rates": {
      "post": {
        "tags": ["shipping"],
        "summary": "Kargo ücreti hesapla (çoklu carrier)",
        "operationId": "calculateShippingRates",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateRequest" } } } },
        "responses": {
          "200": { "description": "Kargo seçenekleri", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingRate" } } } } }
        }
      }
    },
    "/shipping/track/{tracking_number}": {
      "get": {
        "tags": ["shipping"],
        "summary": "Kargo takip",
        "operationId": "trackShipment",
        "parameters": [{ "name": "tracking_number", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Takip eventleri", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResult" } } } }
        }
      }
    },
    "/webhooks": {
      "get": {
        "tags": ["webhooks"],
        "summary": "Aboneliklerimi listele",
        "operationId": "listWebhooks",
        "responses": {
          "200": { "description": "Liste", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } }
        }
      },
      "post": {
        "tags": ["webhooks"],
        "summary": "Yeni webhook aboneliği oluştur",
        "operationId": "createWebhook",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } },
        "responses": {
          "201": { "description": "Oluşturuldu (signing secret tek seferlik döner)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }
        }
      }
    },
    "/webhooks/{id}": {
      "delete": {
        "tags": ["webhooks"],
        "summary": "Webhook aboneliğini sil",
        "operationId": "deleteWebhook",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Silindi" } }
      }
    },
    "/webhooks/{id}/redeliver/{event_id}": {
      "post": {
        "tags": ["webhooks"],
        "summary": "Başarısız teslimatı yeniden dene",
        "operationId": "redeliverWebhook",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "202": { "description": "Kuyruğa eklendi" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API anahtarınızdan üretilen kısa ömürlü JWT (1 saat). `POST /auth/token` ile alın."
      }
    },
    "responses": {
      "Unauthorized": { "description": "Geçersiz veya eksik token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Kayıt bulunamadı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "BadRequest": { "description": "Form veya parametre hatası", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "message", "trace_id"],
        "properties": {
          "error": { "type": "string", "example": "validation_failed" },
          "message": { "type": "string" },
          "trace_id": { "type": "string", "description": "Audit korelasyon ID" }
        }
      },
      "TokenRequest": {
        "type": "object",
        "required": ["api_key", "api_secret"],
        "properties": {
          "api_key": { "type": "string", "example": "hsp_pk_live_..." },
          "api_secret": { "type": "string", "example": "hsp_sk_live_..." }
        }
      },
      "TokenResponse": {
        "type": "object",
        "properties": {
          "access_token": { "type": "string" },
          "token_type": { "type": "string", "example": "Bearer" },
          "expires_in": { "type": "integer", "example": 3600 },
          "scope": { "type": "string", "example": "listings:read orders:write" }
        }
      },
      "Identity": {
        "type": "object",
        "properties": {
          "api_key_id": { "type": "string", "format": "uuid" },
          "tier": { "type": "string", "enum": ["free", "starter", "growth", "enterprise"] },
          "rate_limit_per_minute": { "type": "integer" },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "owner_seller_id": { "type": "string", "format": "uuid", "nullable": true }
        }
      },
      "Seller": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "display_name": { "type": "string" },
          "slug": { "type": "string" },
          "tier": { "type": "string" },
          "rating": { "type": "number" },
          "rating_count": { "type": "integer" },
          "kyc_status": { "type": "string" },
          "city": { "type": "string" }
        }
      },
      "SellerListResponse": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Seller" } },
          "next_cursor": { "type": "string", "nullable": true }
        }
      },
      "Listing": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "slug": { "type": "string" },
          "price": { "type": "number" },
          "currency": { "type": "string", "example": "TRY" },
          "stock": { "type": "integer" },
          "category_id": { "type": "string", "format": "uuid" },
          "seller_id": { "type": "string", "format": "uuid" },
          "condition": { "type": "string" },
          "images": { "type": "array", "items": { "type": "string", "format": "uri" } },
          "status": { "type": "string", "enum": ["draft", "active", "paused", "sold_out", "removed"] }
        }
      },
      "ListingCreate": {
        "type": "object",
        "required": ["title", "price", "category_id", "stock"],
        "properties": {
          "title": { "type": "string", "minLength": 8, "maxLength": 200 },
          "description": { "type": "string", "maxLength": 8000 },
          "price": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "default": "TRY" },
          "stock": { "type": "integer", "minimum": 0 },
          "category_id": { "type": "string", "format": "uuid" },
          "condition": { "type": "string", "enum": ["new", "used", "refurbished"] },
          "images": { "type": "array", "items": { "type": "string", "format": "uri" } }
        }
      },
      "ListingUpdate": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "price": { "type": "number" },
          "stock": { "type": "integer" },
          "status": { "type": "string", "enum": ["draft", "active", "paused", "sold_out", "removed"] }
        }
      },
      "ListingListResponse": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } },
          "total": { "type": "integer" },
          "next_cursor": { "type": "string", "nullable": true }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "order_number": { "type": "string" },
          "status": { "type": "string" },
          "total": { "type": "number" },
          "currency": { "type": "string" },
          "buyer_id": { "type": "string", "format": "uuid" },
          "seller_id": { "type": "string", "format": "uuid" },
          "items": { "type": "array", "items": { "type": "object", "properties": { "listing_id": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" } } } },
          "placed_at": { "type": "string", "format": "date-time" }
        }
      },
      "OrderListResponse": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } },
          "next_cursor": { "type": "string", "nullable": true }
        }
      },
      "ShipmentCreate": {
        "type": "object",
        "required": ["carrier", "tracking_number"],
        "properties": {
          "carrier": { "type": "string", "enum": ["yurtici", "aras", "mng", "ptt", "ups", "dhl"] },
          "tracking_number": { "type": "string" },
          "shipped_at": { "type": "string", "format": "date-time" }
        }
      },
      "Refund": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "payment_id": { "type": "string", "format": "uuid" },
          "amount": { "type": "number" },
          "status": { "type": "string", "enum": ["queued", "processing", "succeeded", "failed"] },
          "reason": { "type": "string" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "parent_id": { "type": "string", "format": "uuid", "nullable": true },
          "children": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }
        }
      },
      "ShippingRateRequest": {
        "type": "object",
        "required": ["from_city_id", "to_city_id", "weight_kg"],
        "properties": {
          "from_city_id": { "type": "integer" },
          "to_city_id": { "type": "integer" },
          "weight_kg": { "type": "number" },
          "dimensions_cm": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } } }
        }
      },
      "ShippingRate": {
        "type": "object",
        "properties": {
          "carrier": { "type": "string" },
          "service": { "type": "string" },
          "price": { "type": "number" },
          "currency": { "type": "string" },
          "estimated_days": { "type": "integer" }
        }
      },
      "TrackingResult": {
        "type": "object",
        "properties": {
          "tracking_number": { "type": "string" },
          "carrier": { "type": "string" },
          "status": { "type": "string" },
          "events": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "location": { "type": "string" }, "description": { "type": "string" } } } }
        }
      },
      "WebhookSubscription": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string" } },
          "is_active": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "WebhookCreate": {
        "type": "object",
        "required": ["url", "events"],
        "properties": {
          "url": { "type": "string", "format": "uri", "example": "https://magaza.example.com/webhooks/hsp" },
          "events": { "type": "array", "items": { "type": "string", "enum": ["order.placed", "order.paid", "order.shipped", "order.delivered", "order.cancelled", "payment.refunded", "listing.sold_out"] } },
          "description": { "type": "string" }
        }
      },
      "WebhookCreated": {
        "allOf": [
          { "$ref": "#/components/schemas/WebhookSubscription" },
          { "type": "object", "properties": { "signing_secret": { "type": "string", "description": "Sadece bu cevapta görünür. Tekrar alınamaz." } } }
        ]
      }
    }
  }
}