# Platform API referansı

> Çok işletmeli partner API: işletme aç, misafir kaydet, sayaç yaz, QR üret, hepsini geri oku. İzole kiracılar, idempotent yazma, bütçe korumaları.

Taban adres: `https://api.sadakio.com/platform/v1`
Kimlik: `Authorization: Bearer pk_ANAHTARINIZ` — anahtar [öz kayıtla](https://app.sadakio.com/gelistirici/kayit) alınır, kapsamları `read` ve `write`.
Makine kontratı: [platform/v1/openapi.yaml](https://api.sadakio.com/platform/v1/openapi.yaml)

Üç kural her uç noktada geçerlidir:

- Yabancı id **404** döner, asla 403 değil. API bir varlık kahini değildir: başka partnerin işletmesi sizin için yok hükmündedir.
- Hatalar `{"error": {"code", "message", "fix"}}` biçimindedir ve `fix` ne YAPACAĞINIZI söyler.
- Her yazma `Idempotency-Key` kabul eder (başlık veya gövde). Aynı anahtarla tekrar eden istek özgün sonucu `replayed: true` ile aynen döndürür, hiçbir şey iki kez işlenmez.

## İşletmeler

### GET /businesses

Açtığınız tüm işletmeler, yeniden eskiye.

```
curl https://api.sadakio.com/platform/v1/businesses \
  -H "Authorization: Bearer pk_ANAHTARINIZ"
```

```json
{"data": [{"id": 42, "name": "Kahve Dünyası", "slug": "kahve-dunyasi",
           "managed": true, "join_url": "https://app.sadakio.com/join/kahve-dunyasi",
           "created_at": "2026-09-22T10:00:00Z"}]}
```

### POST /businesses

Gerçek, izole bir kiracı açar. `program` sadakat ön ayarını seçer, `managed` kipte ne kazanılacağına motor karar verir.

```
curl -X POST https://api.sadakio.com/platform/v1/businesses \
  -H "Authorization: Bearer pk_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kahve Dünyası", "sector": "kafe", "program": "damga"}'
```

Yanıt `201` ve işletme nesnesidir.

### GET /businesses/{id}

Tek işletme, `join_url` ile birlikte. Misafirleriniz bu sayfadan kendileri kaydolur.

### GET /businesses/{id}/qr.png

İşletmenin misafir kayıt QR kodu, baskıya hazır markalı PNG. «Kafeleriniz için QR üretici» tam olarak bu çağrıdır.

```
curl https://api.sadakio.com/platform/v1/businesses/42/qr.png \
  -H "Authorization: Bearer pk_ANAHTARINIZ" -o kafe-qr.png
```

## Misafirler

### GET /businesses/{id}/guests

Sayfalı misafir listesi. `q` ad süzer, `cursor` ve `limit` İşletme API ile birebir aynı sözleşmedir, telefonlar KVKK maskeli döner.

```json
{"data": [{"id": 184, "name": "Elif", "masked_phone": "+•••••••4579",
           "joined_at": "2026-09-16T08:31:00Z"}],
 "next_cursor": 184}
```

### POST /businesses/{id}/guests

Telefonla kayıt. Yeni misafir `201`, aynı telefonla ikinci deneme `200` ve `created: false` döner: tekrar eden bir kayıt formu «zaten var» ile «şimdi oluştu» ayrımını tahmin etmeden yapar.

### DELETE /businesses/{id}/guests/{guest_id}

KVKK silme. Partner kendi işletmelerinin veri sorumlusudur: misafiriniz silinmek istediğinde bunu siz yerine getirirsiniz. Misafir anonimleşir, sayaçlar sıfırlanır, denetim defterinde yalnızca id ve sayılar kalır.

## Sayaçlar ve olaylar

### POST /businesses/{id}/guests/{gid}/adjust

Adlı bir sayaca `delta` ekler. Ham ve doğrudan: damga, puan, jeton, ne isterseniz.

```
curl -X POST .../guests/184/adjust \
  -H "Authorization: Bearer pk_ANAHTARINIZ" \
  -H "Idempotency-Key: ziyaret-2026-09-22-184" \
  -H "Content-Type: application/json" \
  -d '{"counter": "damga", "delta": 1}'
```

```json
{"data": {"counter": "damga", "value": 5, "entry_id": 901, "replayed": false}}
```

### POST /businesses/{id}/guests/{gid}/events

Yönetilen kip: «bir ziyaret oldu» dersiniz, işletmenin kendi programına göre ne kazanılacağına motor karar verir. `amount` ciroyu, `stamps` damga sayısını taşır.

### GET /businesses/{id}/guests/{gid}/counters

Misafirin tüm sayaçları tek düz nesnede: `{"damga": 5, "puan": 120}`. Bilinmeyen misafir id 404 döner, adjust ve events ile aynı.

## Korumalar

| Koruma | Değer | Aşılınca |
|---|---|---|
| Hız | saniyede 30 istek, günde 50.000 | `429` ve `Retry-After` |
| Yazma başına büyüklük | 1.000 | `422 validation_failed` |
| Günlük toplam büyüklük | 100.000 | `429 budget_exceeded`, gece UTC sıfırlanır |

Bütçeler partneri kendi hatasından da korur: sonsuz döngüye giren bir kod sınırsız bakiye basamaz. Limit hesabınıza dar geliyorsa [biz@sadakio.com](mailto:biz@sadakio.com) ile artırılmasını isteyin.