İşletme API referansı

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

Bugünkü yüzey salt okumadır: verinizi çekersiniz, hiçbir çağrı veri değiştirmez. Yazma uç noktaları yol haritasındadır.

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"

{"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.

{"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.

Bu sayfa .md olarak: /docs/api.md