# Hızlı sorgu (ön doldurma) `GET https://ulawk.com/api/v1/ara/` Ulawk dizinindeki şirketlerden anında aday: unvan, müdürlük, sicil no, hukuki biçim, durum, il, adres, kuruluş ve son ilan tarihi. Yalnız Ulawk'ın zaten işlediği şirketler döner; canlı sicil sorgusu yapılmaz, takip eklenmez, paket hakkı harcanmaz. Kişi adı ve başka müşterilere ait bilgi dönmez. Unvan, sicil numarası ya da yurt dışı kimlikle arar; Türkçe harf, büyük/küçük harf ve hukuki biçim eki (A.Ş., Ltd. Şti., GmbH …) farkı önemsizdir. Bulunamazsa `bulunamadi: true`; şirketi `sirket-ekle` ile takibe alın. Bu uca ayrıca saatlik sorgu sınırı uygulanır; dizini toplu çekmek kullanım şartlarına aykırıdır. ## Kimlik doğrulama Her istekte iki başlık: `X-API-Key` ve `X-API-Secret`. ## Sorgu parametreleri - `q` (string, zorunlu) — Unvan, sicil no ya da kimlik (en az 3 harf/rakam). - `ulke` (string) — Ülke süzgeci (TR, GB …); yoksa tümü. - `adet` (integer) — En çok aday (varsayılan 10, en çok 20). - `mudurluk` (string) — Yalnız bu sicil müdürlüğü (Türkiye). - `faal` (string) — 1 → yalnız durumu FAAL olanlar. ## Yanıt ### 200 — Adaylar (boş olabilir). - `sorgu` (string, zorunlu) - `ulke` (string, null, zorunlu) — Süzülen ülke ya da null (tümü). - `adet` (integer, zorunlu) - `kaynak` (string, zorunlu) Değerler: ulawk_dizini. - `bulunamadi` (boolean, zorunlu) — Dizinde aday yok: şirketi takibe alarak kaynaklı profil oluşturun. - `aciklama` (string, zorunlu) - `takibe_al` (string (uri), zorunlu) — Takibe alma ucu (`POST`). - `adaylar[]` (HizliSorguAdayi[], zorunlu) - `adaylar[].ulke` (string, zorunlu) — ISO ülke kodu (TR; yurt dışında kaydın ülkesi, ZZ = LEI). - `adaylar[].kimlik` (string, zorunlu) — Dizin kimliği: Türkiye'de `MÜDÜRLÜK/sicil kökü` (ör. İSTANBUL/325075), yurt dışında sicil kimliği. - `adaylar[].mudurluk` (string, null, zorunlu) — Ticaret sicil müdürlüğü (yalnız Türkiye); `sirket-ekle` gövdesine aynen verilir. - `adaylar[].sicil_no` (string, null, zorunlu) — Sicil numarası (yalnız Türkiye). - `adaylar[].unvan` (string, zorunlu) — Unvan (Türkiye'de en yeni TTSG ilanındaki yazımı). - `adaylar[].hukuki_bicim` (object, zorunlu) - `adaylar[].hukuki_bicim.kod` (string, zorunlu) — Ulawk biçim kodu (TR_AS, TR_LTD, YB_GMBH …; bilinmiyorsa BILINMIYOR). - `adaylar[].hukuki_bicim.yerel` (string, null, zorunlu) — Yerel ad. - `adaylar[].hukuki_bicim.en` (string, null, zorunlu) — İngilizce ad. - `adaylar[].hukuki_bicim.iso` (string, null, zorunlu) — ISO 20275 (ELF) kodu; listede birebir karşılığı yoksa null. - `adaylar[].hukuki_bicim.kategori` (string, zorunlu) — Standart kategori: ANONIM, LIMITED, SAHIS_SIRKETI, KOOPERATIF, SUBE … - `adaylar[].durum` (object, zorunlu) - `adaylar[].durum.kod` (string, zorunlu) Değerler: FAAL, IFLAS_KONKORDATO, TASFIYEDE, KAPANDI, BILINMIYOR. - `adaylar[].durum.ad` (string, zorunlu) - `adaylar[].durum.yerel` (string, zorunlu) — Kaynaktaki ya da ilandaki ifade. - `adaylar[].durum.uluslararasi` (string, zorunlu) — Uluslararası karşılık (ACTIVE, PENDING_DISSOLUTION, CLOSED …). - `adaylar[].il` (string, null, zorunlu) — İl (müdürlükten; yalnız Türkiye). - `adaylar[].adres` (string, null, zorunlu) — Merkez adresi (kaynaklı profilin kimlik bölümünden; yoksa null). - `adaylar[].kurulus` (string (date), null, zorunlu) — Kuruluş tarihi (YYYY-AA-GG) ya da null. - `adaylar[].son_ilan_tarihi` (string (date), null, zorunlu) — Dizindeki en yeni ilan/olay tarihi. - `adaylar[].kaynak` (string, zorunlu) Değerler: ulawk_dizini. - `adaylar[].guncellik_tarihi` (string (date), null, zorunlu) — Bilginin Ulawk'ta son gözlendiği gün; yanıtın güncel olduğu anlamına gelmez. - `adaylar[].eslesme` (string, zorunlu) — tam: sicil no / kimlik birebir ya da sade unvan aynı · yakin: unvan sorguyla başlıyor ya da çok benzer · kismi: tüm sözcükler geçiyor. Değerler: tam, yakin, kismi. - `adaylar[].skor` (number, zorunlu) — 0–1 benzerlik. - `adaylar[].takipte` (boolean, zorunlu) — Şirket SİZİN listenizde mi (başka müşterilerin listesi hiçbir zaman söylenmez). - `adaylar[].sirket_id` (integer | string, null, zorunlu) — Takipteyse şirket kimliğiniz (`/api/v1/sirketler/{id}/`). - `adaylar[].profil` (string (uri), null, zorunlu) — Takipteyse kaynaklı profil adresi. ```json { "sorgu": "örnek deneme", "ulke": "TR", "adet": 3, "kaynak": "ulawk_dizini", "bulunamadi": false, "aciklama": "Yalnız Ulawk dizinindeki şirketler; canlı sicil sorgusu yapılmaz ve yanıt kaynaklı değildir. Kaynaklı profil için şirketi takibe alın.", "takibe_al": "https://ulawk.com/api/v1/sirket-ekle/", "adaylar": [ { "ulke": "TR", "kimlik": "DENEME-100001", "mudurluk": "İSTANBUL", "sicil_no": "DENEME-100001", "unvan": "ÖRNEK DENEME SANAYİ VE TİCARET ANONİM ŞİRKETİ", "hukuki_bicim": { "kod": "TR_AS", "yerel": "Anonim şirket", "en": "Joint-stock company", "iso": "W2SQ", "kategori": "ANONIM" }, "durum": { "kod": "FAAL", "ad": "Faal", "yerel": "Faal", "uluslararasi": "ACTIVE" }, "il": "İSTANBUL", "adres": "Örnek Mahallesi Deneme Caddesi No:1 İstanbul", "kurulus": "2015-03-02", "son_ilan_tarihi": "2026-10-16", "kaynak": "ulawk_dizini", "guncellik_tarihi": "2026-10-01", "eslesme": "tam", "skor": 1.0, "takipte": true, "sirket_id": "DENEME-100001", "profil": "https://ulawk.com/api/v1/sirketler/DENEME-100001/" }, { "ulke": "TR", "kimlik": "DENEME-TASFIYE", "mudurluk": "ANTALYA", "sicil_no": "DENEME-TASFIYE", "unvan": "ÖRNEK DENEME İNŞAAT LİMİTED ŞİRKETİ (TASFİYE HALİNDE)", "hukuki_bicim": { "kod": "TR_LTD", "yerel": "Limited şirket", "en": "Limited liability company", "iso": "R5UT", "kategori": "LIMITED" }, "durum": { "kod": "TASFIYEDE", "ad": "Tasfiye halinde", "yerel": "Tasfiye halinde", "uluslararasi": "PENDING_DISSOLUTION" }, "il": "ANTALYA", "adres": "Örnek Mahallesi Deneme Caddesi No:1 Antalya", "kurulus": "2011-02-14", "son_ilan_tarihi": "2026-10-12", "kaynak": "ulawk_dizini", "guncellik_tarihi": "2026-10-01", "eslesme": "yakin", "skor": 0.871, "takipte": false, "sirket_id": null, "profil": null } ] } ``` ### 400 — `gecersiz_parametre` (q kısa, ulke ya da adet geçersiz). ```json { "hata": "gecersiz_parametre", "detay": "q en az 3 harf ya da rakam olmalı.", "hata_ayrinti": { "kod": "gecersiz_parametre", "mesaj": "q en az 3 harf ya da rakam olmalı.", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": false, "tekrar_sn": null } } ``` ### 405 — GET bekleniyor (`yontem`). ```json { "hata": "yontem", "detay": "GET bekleniyor.", "hata_ayrinti": { "kod": "yontem", "mesaj": "GET bekleniyor.", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": false, "tekrar_sn": null } } ``` ### 401 — Anahtar yok ya da geçersiz (`yetkisiz`). ```json { "hata": "yetkisiz", "detay": "Geçerli X-API-Key başlığı gerekli (panel › API).", "hata_ayrinti": { "kod": "yetkisiz", "mesaj": "Geçerli X-API-Key başlığı gerekli (panel › API).", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": false, "tekrar_sn": null } } ``` ### 429 — Saatlik istek sınırı aşıldı (`hiz_siniri`); Retry-After başlığı sıfırlanmaya kalan saniyeyi verir. Retry-After: `2311` ```json { "hata": "hiz_siniri", "detay": "Saatlik istek sınırı aşıldı (600). Bir sonraki saatte tekrar deneyin.", "hata_ayrinti": { "kod": "hiz_siniri", "mesaj": "Saatlik istek sınırı aşıldı (600). Bir sonraki saatte tekrar deneyin.", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": true, "tekrar_sn": 2311 } } ``` ### 500 — Beklenmeyen hata (`ic_hata`, taraf ulawk); kısa süre sonra yeniden deneyin. Retry-After: `60` ```json { "hata": "ic_hata", "detay": "Beklenmeyen bir hata oluştu; kısa süre sonra yeniden deneyin.", "hata_ayrinti": { "kod": "ic_hata", "mesaj": "Beklenmeyen bir hata oluştu; kısa süre sonra yeniden deneyin.", "taraf": "ulawk", "kaynak": null, "tekrar_denenebilir": true, "tekrar_sn": 60 } } ``` ## İstek ```bash curl "https://ulawk.com/api/v1/ara/?q=%C3%B6rnek+deneme&ulke=TR&adet=3" \ -H "X-API-Key: ulk_DENEME_ANAHTARINIZ" \ -H "X-API-Secret: ulsk_DENEME_GIZLI_ANAHTARINIZ" ```