</> Geliştiriciler

Sadakio Web API — sadakat altyapını kendin kur

Q: Sadakio API’ye nasıl erişirim?

İşletme hesabınızda Ayarlar → API bölümünden sk_ anahtarınızı oluşturun ve Authorization: Bearer başlığıyla https://api.sadakio.com/api/v1 uç noktalarını çağırın.

Q: Bugün hangi uç noktalar var?

GET /guests (misafir listesi), GET /guests/{id} (tek misafir, kartlarıyla), GET /visits (ziyaret akışı) ve GET /stats/retention (geri dönen misafir özeti). Tam sözleşme /api/v1/openapi.yaml adresindedir.

Q: 429 alınca ne yapmalıyım?

Hız sınırına takıldınız. HTTP durum koduna göre dallanın: 429 gelirse bekleyip yeniden deneyin. X-RateLimit-* başlıkları kalan kotayı gösterir; Retry-After başlığı başarılı yanıtlarda da görünebilir, tek başına yavaşlama sinyali değildir.

Damga mı, puan mı, %5 cashback mi? Programını panelden tanımla, verisini API’den oku: misafir listesi, ziyaret akışı, geri dönen misafir metrikleri. POS’una bağla ya da kendi ürününü Sadakio üzerine inşa et.

Ücretsiz başla → OpenAPI’yi görüntüle

Makine tarafından okunabilir: openapi.yaml · llms.txt · dokümanlar · MCP sunucusu

api.sadakio.com

$ curl https://api.sadakio.com/api/v1/guests \
    -H "Authorization: Bearer sk_SIZIN_ANAHTARINIZ"

{
  "data": [{
    "id": 184,
    "name": "Elif T.",
    "masked_phone": "+••••••••4579",
    "visits_count": 12,
    "last_visit": "2026-09-16T08:31:00Z"
  }],
  "next_cursor": null
}

3 adımda ilk isteğin

1

Anahtarını oluştur

Sadakio hesabında Ayarlar → API bölümüne gir, saniyeler içinde sk_ anahtarını al. Ham anahtar yalnızca bir kez gösterilir — güvenli bir yere kaydet.

2

İlk isteğini at

curl ile /api/v1/guests uç noktasını çağır. Yanıtlar kendi işletmenin verisidir; telefon numaraları maskeli döner.

3

Kontratla entegre ol

Açık OpenAPI 3.0 dosyasını (openapi.yaml) aracına ya da yapay zeka ajanına ver; entegrasyonu dakikalar içinde üret.

Dilini seç ve bağlan

curl "https://api.sadakio.com/api/v1/stats/retention?period=month" \
  -H "Authorization: Bearer sk_SIZIN_ANAHTARINIZ"

const r = await fetch("https://api.sadakio.com/api/v1/stats/retention?period=month", {
  headers: { Authorization: "Bearer " + process.env.SADAKIO_API_KEY }
});
const { data } = await r.json();
console.log(data.returned_guests, data.returned_visits);

import os, requests
r = requests.get(
    "https://api.sadakio.com/api/v1/stats/retention",
    params={"period": "month"},
    headers={"Authorization": f"Bearer {os.environ['SADAKIO_API_KEY']}"},
)
data = r.json()

Anahtar başına saniyede 60, günde 10.000 istek. Kalan kota X-RateLimit-Limit / Remaining / Reset başlıklarıyla döner. HTTP durum koduna göre dallanın: 429 gelirse bekleyip yeniden deneyin — Retry-After başlığı başarılı yanıtlarda da görünebilir. Anahtarınızı yalnızca sunucu tarafında kullanın; URL’ye ya da istemci koduna koymayın.

Bugün kullanabileceğin uç noktalar

Taban adres: https://api.sadakio.com/api/v1 — hepsi okuma uç noktasıdır ve read kapsamıyla çalışır.

GET/guestsMisafir listesi — arama, updated_since, KVKK maskeli telefonlar

GET/guests/{id}Tek misafir detayı — kartları ve program tipleriyle

GET/visitsZiyaret akışı — tarih filtreleri, cursor sayfalama

GET/stats/retentionGeri dönen misafir özeti — 7 / 30 / 365 günlük pencereler

GET/openapi.yamlAçık OpenAPI 3.0 kontratı — anahtarsız erişim

Yazma uç noktaları ve webhook’lar da yayında

Artık kendi işletmenizi açabilir, misafir kaydedebilir, QR menüyü tek istekle yükleyebilirsiniz. Olaylar imzalı olarak adresinize gelir, bizi sorgulamanız gerekmez. Çalışan tüm entegrasyonlar Eklentiler sayfasındadır.

Yapay zeka ajanın doğrudan bağlansın

Sadakio MCP sunucusu yayında. Claude, Cursor veya başka bir MCP istemcisi kafenizin kendi verisini tek satırla okur. Kurulum yok, komut paketi kendisi indirir. Sunucu yalnızca okur, hiçbir şeyi değiştirmez.

npx sadakio-mcp    # Node 18 ve üzeri
uvx sadakio-mcp    # Python 3.10 ve üzeri

İstemcinin ayar dosyasına yapıştırın, anahtarınızı yazın, hazır

{
  "mcpServers": {
    "sadakio": {
      "command": "npx",
      "args": ["-y", "sadakio-mcp"],
      "env": { "SADAKIO_API_KEY": "sk_SIZIN_ANAHTARINIZ" }
    }
  }
}

MCPlist_guestsMisafir listesi — arama ve sayfalama, KVKK maskeli telefonlar

MCPget_guestTek misafir detayı — kartları ve program tipiyle

MCPlist_visitsZiyaret akışı — tarih filtreleri

MCPget_retentionGeri dönen misafir özeti — 7 / 30 / 365 günlük pencereler

Paketler: npm · PyPI · MIT

Claude kullanıyorsanız mağaza da hazır: geliştirici dokümanlarını ve API kontratlarını okuyan Sadakio Developer Docs eklentisi Claude dizininde yayında, anahtar istemez.

Ajanına yapıştır gerisini o kursun

Cursor, ChatGPT veya Claude kullanıyorsan bu hazır istemi kopyala — ajanın OpenAPI kontratını okur ve entegrasyonu senin yerine yazar.

Sadakio Web API ile entegrasyon kur. Kontrat: https://api.sadakio.com/api/v1/openapi.yaml — özet: https://sadakio.com/llms.txt
Anahtarım Ayarlar → API bölümünden alındı (Authorization: Bearer). Bana misafir listesini çekip uyuyan misafirleri raporlayan bir servis yaz.

Güvenlik & veri gizliliği

Anahtar = parmak izi

Ham anahtar bir kez gösterilir; sunucuda yalnızca sha256 özeti saklanır. İptal edilen anahtar 401 döner.

İşletme izolasyonu

Her anahtar yalnızca bağlı olduğu işletmenin verisine erişir; başka işletmeye ait misafir kimliği 404 döndürür.

Maskeli telefonlar

Telefonlar masked_phone alanında döner; yalnızca son 4 hane görünür (örn. +••••••••4579). Yanıtlar ad gibi diğer alanları içerir — anahtarını gizli tut.

Adil limitler

Anahtar başına saniyede 60, günde 10.000 istek; anahtarsız doküman erişimi ayrıca IP bazında korunur.

Sık sorulan sorular

Sadakio API’ye nasıl erişirim?

İşletme hesabınızda Ayarlar → API bölümünden sk_ anahtarınızı oluşturun ve Authorization: Bearer başlığıyla https://api.sadakio.com/api/v1 uç noktalarını çağırın.

Bugün hangi uç noktalar var?

GET /guests (misafir listesi), GET /guests/{id} (tek misafir, kartlarıyla), GET /visits (ziyaret akışı) ve GET /stats/retention (geri dönen misafir özeti). Tam sözleşme /api/v1/openapi.yaml adresindedir.

429 alınca ne yapmalıyım?

Hız sınırına takıldınız. HTTP durum koduna göre dallanın: 429 gelirse bekleyip yeniden deneyin. X-RateLimit-* başlıkları kalan kotayı gösterir; Retry-After başlığı başarılı yanıtlarda da görünebilir, tek başına yavaşlama sinyali değildir.

Misafir telefon numaraları açık mı dönüyor?

Hayır. Telefon numaraları masked_phone alanında maskeli döner; yalnızca son 4 hane görünür (örn. +••••••••4579). Yanıtlar misafir adı gibi diğer alanları içerir; veriler yalnızca anahtarın bağlı olduğu işletmeye aittir.

returned_guests ne anlama geliyor?

Seçilen pencereden önce katılmış olup pencere içinde tekrar ziyaret üreten misafir sayısıdır. week/month/year 7/30/365 günlük kayan pencerelerdir; ölçüm ciro garantisi değil, geri dönüş analitiğidir.

Yapay zeka ajanımı nasıl bağlarım?

Sadakio MCP sunucusu yayında. Claude, Cursor veya başka bir MCP istemcisinde npx sadakio-mcp ya da uvx sadakio-mcp komutunu tanımlayın, anahtarınızı ekleyin. Ajan dört aracı görür: misafir listesi, tek misafir, ziyaretler ve geri dönen misafir özeti. Sunucu yalnızca okur.

Yazma uç noktaları ve webhook’lar var mı?

Var, ikisi de yayında. Platform API ile kendi işletmenizi açar, misafir kaydeder, QR menüyü tek istekle yüklersiniz. Webhook’lar misafir, ziyaret, ödül ve menü olaylarını imzalı olarak adresinize gönderir. Çalışan tüm entegrasyonlar Eklentiler sayfasındadır.