> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Şehir ve İlçe

> Türkiye il ve ilçe listesi — onboarding adres formları için.

İl ve ilçe lookup'ları; merchant onboarding ve adres formlarında dropdown doldurmak için kullanılır. Sayfalama yoktur — tüm il/ilçe listesi tek seferde döner.

## Şehirler

```http theme={null}
GET /api/v1/lookups/cities
```

```bash theme={null}
curl https://identity.payven.com.tr/api/v1/lookups/cities \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

Yanıt — şehir listesi (81 il):

```json theme={null}
[
  { "id": "abc-...", "code": "34", "name": "İstanbul" },
  { "id": "def-...", "code": "06", "name": "Ankara" },
  { "id": "ghi-...", "code": "35", "name": "İzmir" }
]
```

| Alan   | Açıklama                               |
| ------ | -------------------------------------- |
| `id`   | UUID — districts sorgusunda kullanılır |
| `code` | Plaka kodu (`34`, `06`, ...)           |
| `name` | Türkçe isim                            |

## İlçeler

```http theme={null}
GET /api/v1/lookups/districts?city_id={uuid}
```

İlçeleri **şehir bazında** çekersiniz. Tüm ilçeleri tek seferde almak mümkün ama 950+ kayıt — seçilen şehre göre lazy-load önerilir.

```bash theme={null}
curl "https://identity.payven.com.tr/api/v1/lookups/districts?city_id=abc-..." \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

```json theme={null}
[
  { "id": "...", "name": "Kadıköy",   "city_id": "abc-..." },
  { "id": "...", "name": "Beşiktaş", "city_id": "abc-..." },
  { "id": "...", "name": "Şişli",     "city_id": "abc-..." }
]
```

| Query parametresi | Tip  | Açıklama                                   |
| ----------------- | ---- | ------------------------------------------ |
| `city_id`         | UUID | Filtre — boş bırakılırsa tüm ilçeler döner |

## Caching

Bu liste **çok nadir** değişir (yeni ilçe atanması nadirdir). İstemcinizde **7 günlük** cache uygulayabilirsiniz.