İçeriğe geç
kimbulur!

KimBulur API v1

İlan verisini kendi sistemine bağla

İlan arama, kategori şemaları ve toplu ilan aktarımı için REST API. Galeri ve emlak ofisleri ilanlarını tek tek girmek yerine mevcut yazılımlarından otomatik aktarır.

OpenAPI 3.1 (JSON)Import anahtarı için kurumsal üyelik

Özellikler

Oran sınırları

Anahtarsız 60 istek/dk, API anahtarıyla 600 istek/dk. Her yanıtta X-RateLimit-* başlıkları döner.

Kimlik doğrulama

X-Api-Key başlığı veya Authorization: Bearer <anahtar>. Anahtarlar kapsamlıdır: read, import.

Toplu ilan aktarımı

Galeri ve emlak ofisleri DMS/CRM'lerinden ilan aktarır: dry_run ile tek istekte 500 ilana kadar doğrular, 50'şer ilanlık paketlerle yükler. CSV, JSON ya da XML dosyası mağaza panelinden de yüklenebilir.

XML feed eşitlemesi

Ofis feed adresini bir kez verir; ilanlar her gün okunur. Yeni ilanlar incelemeye girer, fiyatlar güncellenir, portföyden çıkanlar yayından alınır.

Hızlı inceleme

Aktarılan ilanlar risk skoruyla incelenir. Risk sinyali olmayan ilanlar mağaza bazında toplu onaylanır; hedef 15 dakika.

Mevzuata uygun

Emlak ve vasıta ilanlarında EİDS referansı zorunlu; telefon numarası içeren açıklamalar reddedilir.

Standart hatalar

Tüm hatalar RFC 9457 application/problem+json biçiminde: type, title, status, detail.

Webhook (yakında)

İlan onay/ret, mesaj ve fiyat değişimi olayları HMAC imzalı webhook ile bildirilecek.

Hızlı başlangıç

İstanbul'daki en yeni otomobil ilanlarını getir:

curl "https://www.kimbulur.com/api/v1/listings?category=vasita/otomobil&city=istanbul&sort=newest&per_page=5" \
  -H "X-Api-Key: <ANAHTARIN>"

Galerindeki ilanları önce doğrula, sonra kuyruğa al:

curl -X POST "https://www.kimbulur.com/api/v1/listings/import?dry_run=1" \
  -H "X-Api-Key: <IMPORT_ANAHTARIN>" -H "Content-Type: application/json" \
  -d '{"listings":[{"externalId":"DMS-1042","title":"2020 Renault Clio 1.0 TCe Touch","category":"vasita/otomobil",
       "price":785000,"city":"istanbul","district":"kadikoy","images":["https://cdn.galerim.com/1042-1.jpg"],
       "attributes":{"marka":"Renault","yil":2020,"km":48000,"yakit":"Benzin","vites":"Manuel"},
       "eidsReference":"EIDS-2026-000123"}]}'

XML feed ile günlük otomatik aktarım

Emlak ofisi ve galeriler portföy yazılımlarının ürettiği feed adresini mağaza panelinde bir kez kaydeder. Adres her gün okunur; ilan numarasına göre eşitlenir. Aynı alanlar CSV (UTF-8, başlık satırlı) ve JSON feed'lerinde de geçerlidir.

<?xml version="1.0" encoding="UTF-8"?>
<ilanlar>
  <ilan>
    <ilan_no>MG-2026-101</ilan_no>
    <baslik><![CDATA[Moda'da deniz manzaralı 3+1 daire]]></baslik>
    <kategori>emlak/konut/satilik/daire</kategori>
    <fiyat>12250000</fiyat>
    <para_birimi>TRY</para_birimi>
    <il>İstanbul</il>
    <ilce>Kadıköy</ilce>
    <mahalle>Caferağa</mahalle>
    <aciklama><![CDATA[Metroya 5 dakika, asansörlü, otoparklı binada.]]></aciklama>
    <gorseller>
      <gorsel>https://cdn.ofisim.com/mg-101-1.jpg</gorsel>
      <gorsel>https://cdn.ofisim.com/mg-101-2.jpg</gorsel>
    </gorseller>
    <eids>EIDS-2026-104501</eids>
    <ozellikler>
      <ozellik ad="m2">110</ozellik>
      <ozellik ad="netM2">96</ozellik>
      <ozellik ad="oda">3+1</ozellik>
    </ozellikler>
  </ilan>
</ilanlar>

Her ilan tekrar eden bir öğedir: <ilan>, <listing>, <item>, <ad>, <property> ya da <emlak>. CDATA ve XML karakter referansları (&amp;) desteklenir.

XML feed alanları
AlanKural
ilan_noZorunlu. Eşitleme anahtarı: aynı numara güncellenir, yeni numara yeni ilan olur. Diğer adlar: externalId, referans, portfoyno.
baslik10–80 karakter.
kategoriYaprak kategori yolu, ör. emlak/konut/satilik/daire ya da vasita/otomobil. Liste: /api/v1/categories.
fiyat, para_birimiSayı (12250000 ya da 12.250.000). Para birimi TRY, USD veya EUR; boşsa TRY.
il, ilce, mahalleAd ya da slug. Emlakta mahalle zorunlu.
aciklamaEn fazla 5.000 karakter, telefon numarası içeremez.
gorseller / gorselDoğrudan https görsel bağlantısı (yönlendirmesiz). Alt öğe metni ya da url="…" özniteliği.
eidsEmlak ve vasıtada EİDS doğrulama referansı zorunlu.
ozellikler / ozellik ad="…"Kategori şemasındaki anahtar ya da etiket (ör. oda, m2, Oda Sayısı). Tanınmayan alan özellik olarak denenir.

Eşitleme kuralları

  • Adres https olmalı ve yönlendirme yapmamalı; dosya en fazla 10 MB ve 2.000 ilan.
  • Yeni ilan numaraları moderasyona girer; eşitleme başına en fazla 100 yeni ilan alınır, kalanı ertesi gün.
  • Mevcut ilanlarda fiyat hemen güncellenir; feed'de iki kez üst üste olmayan ilan yayından alınır, geri gelince yeniden yayınlanır.
  • Elle yayından kaldırdığın ilanlara feed dokunmaz. Hatalı satırlar son eşitleme raporunda ilan ya da satır numarasıyla gösterilir.

Sık sorulanlar

XML feed ne sıklıkla okunur?

Her gün 05:30'da (Türkiye saati) okunur. Mağaza panelindeki "Şimdi eşitle" düğmesiyle saatte 4 kez elle de eşitlenebilir.

Feed'den çıkan ilan ne olur?

İlan numarası art arda iki eşitlemede feed'de yoksa ilan yayından alınır; numara geri gelirse ilan yeniden yayına girer. Feed yayındaki ilanların yarısından azını içeriyorsa (bozuk ya da eksik dosya) toplu kapatma yapılmaz.

Fiyat değişikliği ne zaman yansır?

Eşitlemede hemen yansır, ilan yeniden incelemeye girmez. Fiyat ilk fiyatın 0,3 ile 3 katı arasında olmalıdır; fiyat düşüşü ilanı takip edenlere bildirilir.

Başlık, açıklama ya da görsel değişikliği feed'le güncellenir mi?

Hayır. Bu değişiklikler yeniden inceleme gerektirdiği için mağaza panelinden yapılır. Feed yeni ilanları, fiyatları ve yayın durumunu eşitler.

Uç noktalar

get
/api/v1/listings

İlan ara ve listele

get
/api/v1/listings/{id}

İlan detayı

post
/api/v1/listings/importanahtar gerekli

Toplu ilan aktarımı (galeri / emlak ofisi)

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.

get
/api/v1/categories

Kategori ağacı, filtre şemaları ve ilan politikaları

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.

get
/api/v1/categories/{path}

Tek kategori: miras alınmış filtreler, zorunlu alanlar, EİDS gereksinimi

get
/api/v1/locations

81 il (plaka, bölge, nüfus, koordinat, ilçe sayısı)

get
/api/v1/locations/{il}

Tek il ve ilçeleri

get
/api/v1/locations/{il}/{ilce}

Tek ilçe ve mahalleleri (posta kodu, nüfus)

Kullanım kuralları

  • Veriler yalnızca KimBulur'a bağlantı veren (atıflı) gösterimlerde kullanılabilir; ilan URL'si korunmalıdır.
  • Satıcı telefon numarası ve kişisel veriler API ile paylaşılmaz (KVKK).
  • Toplu kazıma (scraping) yerine API kullanılmalıdır; kötüye kullanımda anahtar iptal edilir.
  • Destek ve kurumsal kota talepleri için: destek@kimbulur.com