Platform API referansı
Taban adres: https://api.sadakio.com/platform/v1
Kimlik: Authorization: Bearer pk_ANAHTARINIZ — anahtar öz kayıtla alınır, kapsamları read ve write.
Makine kontratı: 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 vefixne YAPACAĞINIZI söyler. - Her yazma
Idempotency-Keykabul eder (başlık veya gövde). Aynı anahtarla tekrar eden istek özgün sonucureplayed: trueile aynen döndürür, hiçbir şey iki kez işlenmez.
Sistem bu kuralları altyapı düzeyinde uygular, entegrasyon kodunuzun doğruluğuna güvenmez.
İş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"
{"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 verirseniz işletme managed olur: bir olayın ne kazandıracağına motor karar verir. Vermezseniz kuralları siz koyarsınız ve sayaçları /adjust ile oynatırsınız. white_label: true misafirin gördüğü her sayfada Sadakio markasını gizler.
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", "white_label": true,
"program": {"type": "damga",
"rules": {"stamps_required": 8, "reward": "Bedava kahve"}}}'
Yanıt 201 ve program ile white_label dahil işletme nesnesidir.
program kısaca bir tür adı ("damga", "puan", "nakit", "damga_puan") ya da yukarıdaki nesnedir. Her kural isteğe bağlıdır ve doğrulanır. Bilinmeyen bir anahtar izin verilenlerin listesiyle reddedilir, yani gönderdiğiniz her ayar motorun gerçekten okuduğu bir ayardır:
| Kural | Aralık | Anlamı |
|---|---|---|
stamps_required |
1–100, varsayılan 10 | Bir ödül için damga sayısı |
reward |
metin, varsayılan «Ücretsiz ürün» | Misafirin kazandığı, kartta görünür |
points_per_stamp |
0–1000 | Her damgayla eklenen puan |
tl_per_point |
0,01–100000 | Puan programları: puan başına harcanan TL |
cashback_percent |
0,01–100 | Nakit iade programları |
welcome_stamp |
true / false | Kayıtta bir hediye damga |
PUT /businesses/{id}/program
Bir işletmeye sonradan program verir ya da mevcut programın kurallarını değiştirir. Kayıtta açılan test işletmesinin siz verene kadar programı yoktur. Canlı bir programın TÜRÜNÜ değiştirmek her misafirin bakiyesini yeni kurallarla yeniden okur. Bu yüzden gövdede "confirm_type_change": true yoksa yanıt 409 type_change_needs_confirm olur.
curl -X PUT https://api.sadakio.com/platform/v1/businesses/42/program \
-H "Authorization: Bearer pk_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-d '{"type": "damga", "rules": {"stamps_required": 10, "reward": "Tatlı ikram"}}'
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.
{"data": [{"id": 184, "name": "Elif", "masked_phone": "+•••••••4579",
"joined_at": "2026-09-16T08:31:00Z"}],
"next_cursor": 184}
POST /businesses/{id}/guests
Telefon ve adla kayıt, ikisi de zorunlu. +90 555…, 0555… ve 555… aynı misafirdir. 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}'
{"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ı.
Kullanım ve API tokenleri
GET /usage
Son 30 gününüz: tokens_used (her başarılı istek bir API tokeni), tüm işletmelerinizdeki active_guests ve businesses. Platform ücretsizdir, token bakiyeniz sınırsızdır ("unlimited": true). Bu uç yalnızca sayar. Aynı rakamlar geliştirici kabininizde de görünür.
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 [email protected] ile artırılmasını isteyin.
Bu sayfa .md olarak: /docs/platform.md