# Müşterileri bulmak

> **Ne yaparsınız:** Müşterileri listeler, e-posta veya telefonla doğru kartı bulur, kartı ve müşterinin siparişlerini okursunuz.
> **Hangi uçlar:** [Müşterileri listele](https://developer.siparis.app/uc/musterileri-listele), [Müşteriyi getir](https://developer.siparis.app/uc/musteriyi-getir), [Siparişleri listele](https://developer.siparis.app/uc/siparisleri-listele)
> **Gereken izin:** `customers:read`; e-posta/telefon araması için ayrıca `personal_data:read`, siparişler için `orders:read`.

API temel adresi `https://api.siparis.app/v1`. Önce [Başlarken](https://developer.siparis.app/baslarken) sayfasından anahtar oluşturup sunucunuzda `SIPARIS_API_KEY` değişkenine kaydedin. Komutlar `curl` ve `python3` kullanır; yerelde `SIPARIS_API_URL` ile `/v1` içeren adresi değiştirebilirsiniz. `personal_data:read` kapsamını (kişisel veri okuma izni) işletme sahibi açıkça seçmelidir. Kart eklemek ve değiştirmek için [Müşteri eklemek ve güncellemek](https://developer.siparis.app/musteri-eklemek) rehberine bakın.

## 1. Müşteri listesini alın

```bash
curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'limit=50' \
  --output /tmp/siparis-musteriler.json && \
python3 -m json.tool /tmp/siparis-musteriler.json
```

Örnek HTTP 200 yanıtı (uydurma veri):

```json
{
  "data": [
    {
      "archived": false,
      "created_at": "2026-10-16T09:00:00Z",
      "id": "cus_1234567890abcdef1234567890abcdef",
      "revision": 1,
      "store": "sto_1234567890abcdef1234567890abcdef",
      "updated_at": "2026-10-16T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```



Liste son değişiklik zamanı ve kimliğe göre eskiden yeniye sıralanır. `data=[]` görünür müşteri olmadığını gösterir. Arşivdeki müşteriler listelenmez. `has_more=true` ise yanıttaki `next_cursor` değerini (sonraki sayfanın yer imi) aynı isteğe `cursor` olarak ekleyin; [listeleme](https://developer.siparis.app/listeleme) sayfasında ayrıntılar var. Marka sınırlı anahtar yalnız kendi markasının müşterilerini görür.

`personal_data:read` olmadan `name`, `email`, `phone`, `instagram`, `address`, `invoice`, `marketing_consent` ve `note` alanları yanıtta bulunmaz. Bunlar boş metin veya `null` olarak gönderilmez. `id`, `store`, `created_at`, `updated_at`, `archived` kalır. `note` için kişisel veri izninin yanında `internal_notes:read` da gerekir. Kişisel veri izni varken boş bir alanın `null` gelmesi ise o bilginin bulunmadığını gösterir.

## 2. E-postayla veya telefonla bulun

Değeri olduğu gibi gönderin; harf büyüklüğü ve baştaki/sondaki boşluklar sunucuda kaldırılır. Telefon son 10 hanesine çevrilir: `+90 500 000 00 00`, `05000000000` ve `5000000000` aynı telefonla eşleşir. Örnek değerleri kendi aradığınızla değiştirin.

```bash
curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'email=  Ornek@Example.com  '
```

Örnek HTTP 200 yanıtı (uydurma veri; yalnız ilgili alanlar):

```json
{
  "data": [
    {
      "id": "cus_1234567890abcdef1234567890abcdef",
      "store": "sto_1234567890abcdef1234567890abcdef"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```



```bash
curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'phone=+90 (000) 000 00 00'
```

Örnek HTTP 200 yanıtı (uydurma veri; yalnız ilgili alanlar):

```json
{
  "data": [
    {
      "id": "cus_1234567890abcdef1234567890abcdef",
      "store": "sto_1234567890abcdef1234567890abcdef"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```



Arama kısmi değildir. `email` ve `phone` birlikte verilirse **ikisi de** eşleşmelidir; önce e-posta, bulunmazsa telefonla aramak için iki ayrı istek gönderin. Eşleşme yoksa HTTP 200 ve `data=[]` gelir; izin yoksa `403 insufficient_scope`. Birden fazla müşteri veya marka eşleşebilir; ilk sonucu tek kişi kabul etmeyin, dönen `id` ve `store` değerlerini kullanın.

## 3. En yeni kartları alın

Liste varsayılan olarak son değişikliğe göre eskiden yeniye gelir. En yeni kartlar için `sort=-created_at` ekleyin; sıralamayı değiştirince ilk sayfadan başlayın.

```bash
curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'sort=-created_at' \
  --data-urlencode 'limit=20'
```

Örnek HTTP 200 yanıtı (uydurma veri; yalnız ilgili alanlar):

```json
{
  "data": [
    {
      "id": "cus_1234567890abcdef1234567890abcdef",
      "created_at": "2026-10-16T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```



Eski entegrasyonlar `email_key` (küçük harf, baş/son boşluksuz e-posta) ve `phone_key` (son 10 hane) göndermeyi sürdürebilir; yeni bağlantılarda `email` ve `phone` kullanın.

## 4. Tek müşteriyi açın

İlk adımdaki liste boş değilse bu örnek ilk müşteriyi açar. Arama sonucundaki başka bir `cus_…` kimliğini de kullanabilirsiniz.

```bash
SIPARIS_CUSTOMER_ID=$(python3 -c 'import json; print(json.load(open("/tmp/siparis-musteriler.json"))["data"][0]["id"])')
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/customers/$SIPARIS_CUSTOMER_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"
```

Örnek HTTP 200 yanıtı (uydurma veri):

```json
{
  "archived": false,
  "created_at": "2026-10-16T09:00:00Z",
  "id": "cus_1234567890abcdef1234567890abcdef",
  "revision": 1,
  "store": "sto_1234567890abcdef1234567890abcdef",
  "updated_at": "2026-10-16T09:00:00Z"
}
```



## Bir müşterinin siparişlerine nasıl ulaşırım?

`orders:read` kapsamıyla `customer` süzgecini yalnız `sort=-created_at` ile kullanın; başka sıra veya `sort` alanının atlanması `422 validation_error` döndürür; `SIPARIS_CUSTOMER_ID` arama sonucundaki `cus_…` kimliğidir.

```bash
curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode "customer=$SIPARIS_CUSTOMER_ID" \
  --data-urlencode 'sort=-created_at'
```

Örnek HTTP 200 yanıtı (uydurma veri; yalnız ilgili alanlar):

```json
{
  "data": [
    {
      "id": "ord_1234567890abcdef1234567890abcdef",
      "number": "48273910",
      "customer": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```



Bu istek yalnız o karta bağlı siparişleri getirir; aynı iletişim bilgisine sahip başka bir kartın siparişlerini birleştirmez. Marka sınırlı anahtar başka markanın müşteri kimliğinde `404` alır. Devam sayfasında `customer` ve `sort` değerlerini koruyun.

## Sık hata ve çözümü

| Yanıt | Ne yapmalıyım? |
| --- | --- |
| `403 insufficient_scope` | Liste için `customers:read`, e-posta/telefon araması için ayrıca `personal_data:read` gerekir. |
| `422 validation_error` | Telefon en az 10 haneli olmalı; desteklenmeyen süzgeç göndermeyin. |
| HTTP 200, `data=[]` | Yazımı ve marka yetkisini kontrol edin. İki süzgeç varsa ikisinin de eşleşmesi gerekir. |
| `404 not_found` | `cus_…` kimliğini liste/arama sonucundan alın; başka markanın veya işletmenin müşterisi görünmez. |
| `400 invalid_cursor` | Aynı arama değerleri ve anahtarla devam edin; yeni aramada eski imleci kullanmayın. |

Ortak hatalar her ucun sayfasında; ayrıca [kapsamlar](https://developer.siparis.app/kapsamlar) ve [hatalar](https://developer.siparis.app/hatalar).