# Hızlı sorgu ve form doldurma

`GET /api/v1/ara/?q=…` Ulawk'ın **zaten işlediği** şirketlerden anında aday döner: unvan, müdürlük, sicil no, hukuki biçim, durum, il, adres, kuruluş ve son ilan tarihi. Müşteri kayıt formunu doldurmak, yazarken öneri göstermek ve takibe almadan önce doğru şirketi seçmek için.

- Canlı sicil sorgusu yapılmaz, takip eklenmez, paket hakkı harcanmaz.
- Yanıt kaynaklı değildir (`kaynak: ulawk_dizini`); `guncellik_tarihi` bilginin Ulawk'ta son gözlendiği gündür. Kaynaklı profil ve ilan alıntıları için şirketi [takibe alın](/gelistirici/api/sirket-ekle/).
- Kişi adı (yetkili, ortak) dönmez. Başka müşterilerin listesi, notu ya da etiketi hiçbir zaman dönmez; `takipte` yalnız **sizin** listenizi söyler.
- Dizinde olmayan şirket için `bulunamadi: true` döner. "Türkiye'deki her şirket" değil, yalnız dizindekiler.

## Eşleşme

| `eslesme` | Ne zaman |
|---|---|
| `tam` | Sicil numarası ya da yurt dışı kimlik birebir; ya da hukuki biçim eki atılmış unvan aynı |
| `yakin` | Unvan sorguyla başlıyor ya da çok benzer |
| `kismi` | Sorgudaki her sözcük unvanda geçiyor |

Türkçe harf (İ/ı, ş, ğ, ü, ö, ç), büyük/küçük harf, noktalama ve "A.Ş.", "Ltd. Şti.", "San. ve Tic.", "GmbH" gibi ekler önemsizdir: `ornek deneme san tic` ile `ÖRNEK DENEME SANAYİ VE TİCARET ANONİM ŞİRKETİ` aynı aranır.

```bash
curl "https://ulawk.com/api/v1/ara/?q=örnek%20deneme&ulke=TR&adet=5" \
  -H "X-API-Key: ulk_DENEME_ANAHTARINIZ" -H "X-API-Secret: ulsk_DENEME_GIZLI_ANAHTARINIZ"
```

Süzgeçler: `ulke=TR`, `mudurluk=İSTANBUL`, `faal=1` (yalnız faal şirketler).

## Form bileşeni: sunucudan sunucuya

API anahtarı tarayıcıya **konmaz** ve herkese açık, anahtarsız bir uç yoktur. Müşteri formunuzdaki öneri kutusu kendi sunucunuza sorar; sunucunuz Ulawk'a anahtarla sorar ve yalnız formun ihtiyaç duyduğu alanları geri verir:

```text
tarayıcı (formunuz) → sizin sunucunuz /sirket-oner?q=… → Ulawk /api/v1/ara/ (X-API-Key + X-API-Secret)
```

```python
# Sunucunuz (ör. Flask): anahtar ortam değişkeninde, tarayıcıya hiç gitmez
import os

import requests
from flask import Flask, jsonify, request

app = Flask(__name__)
BASLIK = {"X-API-Key": os.environ["ULAWK_ANAHTAR"], "X-API-Secret": os.environ["ULAWK_GIZLI"]}


@app.get("/sirket-oner")
def sirket_oner():
    r = requests.get("https://ulawk.com/api/v1/ara/", headers=BASLIK, timeout=5,
                     params={"q": request.args.get("q", ""), "ulke": "TR", "adet": 5})
    if not r.ok:
        return jsonify([]), 200
    return jsonify([{"unvan": a["unvan"], "mudurluk": a["mudurluk"], "sicil_no": a["sicil_no"],
                      "adres": a["adres"], "durum": a["durum"]["kod"]} for a in r.json()["adaylar"]])
```

```javascript
// Formunuz: yazdıkça kendi sunucunuza sorar (300 ms bekleme), seçilen aday alanları doldurur
let zamanlayici;
document.querySelector("#unvan").addEventListener("input", (e) => {
  clearTimeout(zamanlayici);
  const q = e.target.value.trim();
  if (q.length < 3) return;
  zamanlayici = setTimeout(async () => {
    const adaylar = await (await fetch("/sirket-oner?q=" + encodeURIComponent(q))).json();
    gosterOneriler(adaylar, (a) => {
      document.querySelector("#mudurluk").value = a.mudurluk;
      document.querySelector("#sicil_no").value = a.sicil_no;
      document.querySelector("#adres").value = a.adres || "";
    });
  }, 300);
});
```

> Doldurulan alanlar müşterinin onayıyla kesinleşmeli: dizin yanıtı kaynaklı değildir. Karar vermeden önce kaynaklı profil ya da doğrulama raporu kullanın.

## Sınırlar

- Genel saatlik sınıra ek olarak bu uçta anahtar başına saatte **300** sorgu; aşılınca `429 hiz_siniri` ve `Retry-After`.
- `q` en az 3 harf ya da rakam; `adet` en çok 20.
- Dizini toplu çekmek (sistematik sorgularla kopyalamak) kullanım şartlarına aykırıdır.
- Deneme anahtarıyla DENEME-… şirketleri aranır (ör. `q=örnek deneme`, `q=100001`).