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

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

{"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}'

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

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