# İşletme API referansı

> Kendi işletmenizin misafir listesi, ziyaret akışı ve geri dönüş metriklerine salt okunur REST erişimi. Anahtar panelden, telefonlar KVKK maskeli.

Taban adres: `https://api.sadakio.com/api/v1`
Kimlik: `Authorization: Bearer sk_ANAHTARINIZ` — anahtar panelde **Ayarlar → API** bölümünden alınır ve tam olarak bir işletmeye bağlıdır.
Makine kontratı: [api/v1/openapi.yaml](https://api.sadakio.com/api/v1/openapi.yaml)

Bugünkü yüzey salt okumadır: verinizi çekersiniz, hiçbir çağrı veri değiştirmez. Yazma uç noktaları [yol haritasındadır](/docs/yol-haritasi).

## GET /guests

Misafir listeniz, artan id ile cursor sayfalı.

| Parametre | Anlamı |
|---|---|
| `search` | Ad alt dizesi, 4+ rakam verilirse telefon kuyruğu |
| `updated_since` | ISO 8601: bu andan beri ziyaret eden VEYA yeni kaydolan |
| `cursor`, `limit` | Sayfalama, `limit` en çok 100 |

`updated_since` artımlı senkron için tasarlandı: yeni kaydolup henüz ziyaret etmemiş misafir de eşleşir, gece senkronunuz kimseyi kaçırmaz.

```
curl "https://api.sadakio.com/api/v1/guests?updated_since=2026-09-20T00:00:00Z" \
  -H "Authorization: Bearer sk_ANAHTARINIZ"
```

```json
{"data": [{"id": 184, "name": "Elif T.", "masked_phone": "+•••••••4579",
           "email": null, "joined_at": "2026-06-01T09:12:00Z",
           "visits_count": 12, "last_visit": "2026-09-16T08:31:00Z",
           "has_birth_date": true, "opt_in": true, "lang": "tr"}],
 "next_cursor": null}
```

## GET /guests/{id}

Tek misafir, kartlarıyla birlikte: program tipi, damga, puan, cashback bakiyesi, seviye puanı ve kazanılan ödüller.

## GET /visits

Ziyaret akışı: kazanımlar, harcamalar ve iptaller tek zaman çizgisinde. Tarih filtreleri `since` ve `until`, sayfalama `cursor` ve `limit`.

```json
{"data": [{"id": 5012, "card_id": 77, "type": "earn", "amount": 1,
           "note": null, "staff_id": 3,
           "created_at": "2026-09-16T08:31:00Z", "reversed_at": null}],
 "next_cursor": 5012}
```

## GET /stats/retention

Geri dönen misafir özeti. `period` değerleri `week`, `month`, `year`: 7, 30 ve 365 günlük kayan pencereler. Pencereden önce katılmış olup pencere içinde tekrar gelen misafir sayısını, ziyaretlerini ve isteğe bağlı `avg_ticket` ile kabaca ciroya çevrilmiş karşılığını döndürür. Bu bir geri dönüş analitiğidir, ciro garantisi değil.

```
curl "https://api.sadakio.com/api/v1/stats/retention?period=month&avg_ticket=180" \
  -H "Authorization: Bearer sk_ANAHTARINIZ"
```

## GET /openapi.yaml

Açık OpenAPI 3.0 kontratı, anahtarsız. Bir üreteç veya yapay zeka ajanı API'yi tek çekişte keşfeder.

## Veri kuralları

- Telefonlar her yanıtta `masked_phone` alanında maskelidir, yalnızca son 4 hane görünür.
- Veriler yalnızca anahtarın bağlı olduğu işletmeye aittir. Başka işletmenin misafir id'si 404 döner.
- Hız: anahtar başına saniyede 60, günde 10.000 istek. Kalan kota `X-RateLimit-Limit / Remaining / Reset` başlıklarında.