{"openapi":"3.1.0","info":{"title":"KimBulur Public API","version":"1.0.0","description":"KimBulur ilan, kategori ve konum verilerine programatik erişim. Okuma uçları anahtarsız dakikada 60 istek, API anahtarıyla dakikada 600 istek sunar. Toplu ilan aktarımı (import) yalnızca kurumsal üyelere verilen 'import' yetkili anahtarla çalışır. Hatalar RFC 9457 problem+json biçimindedir.","contact":{"name":"KimBulur Geliştirici Desteği","email":"destek@kimbulur.com","url":"https://www.kimbulur.com/gelistirici"},"termsOfService":"https://www.kimbulur.com/kurumsal/kullanim-kosullari"},"servers":[{"url":"https://www.kimbulur.com/api/v1"}],"security":[{},{"ApiKey":[]}],"tags":[{"name":"İlanlar"},{"name":"Kategoriler"},{"name":"Konumlar"},{"name":"Kurumsal"}],"paths":{"/listings":{"get":{"tags":["İlanlar"],"summary":"İlan ara ve listele","parameters":[{"name":"category","in":"query","description":"Kategori yolu, ör. vasita/otomobil","schema":{"type":"string"}},{"name":"city","in":"query","description":"İl slug'ı, ör. istanbul","schema":{"type":"string"}},{"name":"district","in":"query","description":"İlçe slug'ı, ör. kadikoy","schema":{"type":"string"}},{"name":"q","in":"query","description":"Başlık ve açıklamada serbest metin","schema":{"type":"string"}},{"name":"min_price","in":"query","description":"En düşük fiyat","schema":{"type":"number"}},{"name":"max_price","in":"query","description":"En yüksek fiyat","schema":{"type":"number"}},{"name":"sort","in":"query","description":"Sıralama","schema":{"type":"string","enum":["recommended","newest","price_asc","price_desc"]}},{"name":"page","in":"query","description":"Sayfa (1'den başlar)","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Sayfa boyutu (en fazla 100)","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Sayfalı ilan listesi","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"422":{"description":"Geçersiz kategori","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Oran sınırı","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/listings/{id}":{"get":{"tags":["İlanlar"],"summary":"İlan detayı","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"İlan","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"404":{"description":"Bulunamadı","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/listings/import":{"post":{"tags":["Kurumsal"],"summary":"Toplu ilan aktarımı (galeri / emlak ofisi)","description":"Varsayılan olarak dry_run=1: yalnızca doğrulama raporu döner. dry_run=0 ile geçerli ilanların görselleri indirilip işlenir ve ilanlar moderasyon kuyruğuna alınır (202). Doğrulamada tek istekte en fazla 500, gerçek aktarımda 50 ilan. Aynı externalId ikinci kez aktarılmaz; il/ilçe/mahalle slug ya da adla, özellikler anahtar ya da etiketle verilebilir.","security":[{"ApiKey":[]}],"parameters":[{"name":"dry_run","in":"query","description":"1 = yalnızca doğrula, 0 = kuyruğa al","schema":{"type":"string","enum":["0","1"],"default":"1"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listings"],"properties":{"listings":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/ImportListing"}}}}}}},"responses":{"200":{"description":"Doğrulama raporu"},"202":{"description":"Kuyruğa alındı"},"401":{"description":"Anahtar gerekli","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Yetki yok","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Geçersiz gövde","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/categories":{"get":{"tags":["Kategoriler"],"summary":"Kategori ağacı, filtre şemaları ve ilan politikaları","description":"Varsayılan derinlik 1 (ana kategori + alt kategoriler). derinlik=4 tüm ağacı (~1.200 düğüm) döner; derinlik ≥ 2 sade biçimdir: filtreler yalnızca tanımlandığı düğümde, politika için /categories/{path}. İlan içe aktarımında category her zaman bir yaprağa (leaf=true) inmelidir.","parameters":[{"name":"derinlik","in":"query","description":"Gömülecek alt seviye sayısı","schema":{"type":"integer","minimum":0,"maximum":4,"default":1}}],"responses":{"200":{"description":"Kategori ağacı"}}}},"/categories/{path}":{"get":{"tags":["Kategoriler"],"summary":"Tek kategori: miras alınmış filtreler, zorunlu alanlar, EİDS gereksinimi","parameters":[{"name":"path","in":"path","required":true,"description":"ör. emlak/konut/satilik","schema":{"type":"string"}}],"responses":{"200":{"description":"Kategori"},"404":{"description":"Bulunamadı","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/locations":{"get":{"tags":["Konumlar"],"summary":"81 il (plaka, bölge, nüfus, koordinat, ilçe sayısı)","parameters":[{"name":"ilceler","in":"query","description":"1 = 973 ilçe gömülü döner","schema":{"type":"string","enum":["0","1"],"default":"0"}}],"responses":{"200":{"description":"İller"}}}},"/locations/{il}":{"get":{"tags":["Konumlar"],"summary":"Tek il ve ilçeleri","parameters":[{"name":"il","in":"path","required":true,"description":"İl slug'ı, ör. istanbul","schema":{"type":"string"}}],"responses":{"200":{"description":"İl"},"404":{"description":"İl bulunamadı","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/locations/{il}/{ilce}":{"get":{"tags":["Konumlar"],"summary":"Tek ilçe ve mahalleleri (posta kodu, nüfus)","parameters":[{"name":"il","in":"path","required":true,"schema":{"type":"string"}},{"name":"ilce","in":"path","required":true,"description":"İlçe slug'ı, ör. kadikoy","schema":{"type":"string"}}],"responses":{"200":{"description":"İlçe + mahalleler"},"404":{"description":"İl/ilçe bulunamadı","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}},"Meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"perPage":{"type":"integer"},"pages":{"type":"integer"},"hasNext":{"type":"boolean"}}},"Listing":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"category":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"url":{"type":"string"}}},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","enum":["TRY","USD","EUR"]}}},"location":{"type":"object","properties":{"city":{"type":"string"},"district":{"type":"string"},"neighborhood":{"type":["string","null"]}}},"images":{"type":"array","items":{"type":"string","format":"uri"}},"badges":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","additionalProperties":true},"seller":{"type":"object","properties":{"type":{"type":"string","enum":["bireysel","kurumsal"]},"name":{"type":"string"},"verified":{"type":"boolean"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ImportListing":{"type":"object","required":["title","category","city","district","images"],"properties":{"externalId":{"type":"string","description":"Sizin sisteminizdeki ilan kimliği"},"title":{"type":"string","minLength":10,"maxLength":80},"category":{"type":"string","description":"Yaprak kategori yolu (GET /categories?derinlik=4 → leaf=true)","example":"vasita/otomobil/bmw/3-serisi"},"price":{"type":"number"},"currency":{"type":"string","enum":["TRY","USD","EUR"],"default":"TRY"},"city":{"type":"string","example":"istanbul"},"district":{"type":"string","example":"kadikoy"},"neighborhood":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Mahalle kimliği veya adı; emlakta zorunlu","example":40512},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"attributes":{"type":"object","additionalProperties":true,"description":"Kategori şemasındaki filtre anahtarları"},"eidsReference":{"type":"string","description":"Emlak ve vasıta kategorilerinde zorunlu"}}}}}}