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:

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.