Yeti API (v1)

Ekosistem uygulamaları (Yetiverse, Yeduty, Vayyn, Yetita, oyunlar...) kullanıcıyı Yeti hesabıyla tanımak, Yeti ile ödeme almak, Yeti kazandırmak ve Yeti'yi kendi bakiyelerine çevirtmek için bu API'yi kullanır.

Kimlik doğrulama

Her uygulama için yönetimden bir API anahtarı alınır. Anahtar yalnızca sunucu tarafında saklanmalı; tarayıcıya ya da mobil uygulamaya konmamalıdır.

Authorization: Bearer yck_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Yeti hareketi yapan her istekte Idempotency-Key başlığı zorunludur. Ağ hatasında aynı anahtarla tekrar denediğinizde işlem ikinci kez yapılmaz.

1. Yeti ile giriş

Kullanıcıyı ayrı şifreyle uğraştırmadan tanımanın yolu. Bir yetkilendirme kodu akışıdır:

1. Rastgele bir durum değeri üretip oturumda saklayın, kullanıcıyı yönlendirin:
   https://yeticuzdan.com/baglan/{uygulama-kodu}?donus=https://uygulamaniz.com/yeti/donus&durum=…
2. Kullanıcı giriş yapar ve ilk seferde onaylar (sonraki girişlerde ekran gösterilmez). Cüzdan donus?kod=…&durum=… adresine döner; reddederse ?hata=reddedildi.
3. durum'u oturumdakiyle karşılaştırın, kodu sunucunuzdan çözün:

POST /api/v1/baglanti
{ "kod": "ydb_…" }

→ 200
{
  "yeti_kodu": "YETI-7K3P9Q",
  "ad": "Ayşe Yılmaz",
  "izin": { "izin_var": false, "gunluk_limit": "0", "kalan": "0", "izin_url": "https://yeticuzdan.com/izin/{uygulama-kodu}" }
}

Kod tek kullanımlıktır, 5 dakika geçerlidir ve yalnızca onu isteyen uygulamanın anahtarıyla çözülür. donus adresi yönetimde kayıtlı uygulama adresinizin alan adında olmalıdır. Kullanıcıyı yeti_kodu ile eşleştirin; kullanıcı bağlantıyı kaldırırsa baglanti.kaldirildi bildirimi gelir.

Kod doğrulayıcı (PKCE, önerilir): Her girişte rastgele bir kod_dogrulayici (43-128 karakter: harf, rakam, - . _ ~) üretip durum ile birlikte oturumda saklayın; yönlendirmeye özetini ekleyin, kodu çözerken doğrulayıcının kendisini gönderin. Kod çalınsa bile isteği başlatan oturum dışında çözülemez.

kod_ozeti = base64url( sha256(kod_dogrulayici) )      (43 karakter, "=" olmadan)

https://yeticuzdan.com/baglan/{uygulama-kodu}?donus=…&durum=…&kod_ozeti=…
POST /api/v1/baglanti   { "kod": "ydb_…", "kod_dogrulayici": "…" }

Mobil uygulamanıza dönüş: Uygulamanız kendi şemasıyla (ör. uygulamaniz://yeti/donus) dönmek istiyorsa bu adresi yönetimde uygulamanızın "mobil dönüş adresleri" listesine kaydettirin. Böyle dönüşlerde kod_ozeti zorunludur (başka bir uygulama aynı şemayı kaydedip kodu yakalayabilir; doğrulayıcıyı bilmediği için çözemez). Kodu yine yalnızca sunucunuz API anahtarıyla çözer.

2. Yeti ile öde

Kullanıcı ödemeyi cüzdanda kendisi onaylar. Sipariş, paket, abonelik gibi tek seferlik tutarlar için.

POST /api/v1/odeme-talepleri
Idempotency-Key: siparis-10045

{
  "tutar": "12000",
  "aciklama": "Galata'da 3 arsa",
  "siparis_no": "10045",
  "donus_url": "https://uygulamaniz.com/yeti/odeme-donus",
  "iptal_url": "https://uygulamaniz.com/sepet"
}

→ 201 { "id": "9b1c…", "durum": "bekliyor", "tutar": "12000", "odeme_url": "https://yeticuzdan.com/ode/9b1c…", "son_gecerlilik": "…" }

Kullanıcıyı odeme_url'e yönlendirin. Onaydan sonra donus_url?yeti_odeme=…&durum=odendi adresine döner. Siparişi yalnızca webhook ile ya da GET /odeme-talepleri/{id} ile durumu doğruladıktan sonra onaylayın; dönüş adresine tek başına güvenmeyin.

• GET /api/v1/odeme-talepleri/{id}: durum (bekliyor | odendi | iptal | suresi_doldu | iade) ve ödeyenin yeti_kodu
• POST /api/v1/odeme-talepleri/{id}/iade: {"tutar": "2000"} (boşsa kalan tutarın tamamı)

Telefondan onay: Ödeyecek kişiyi biliyorsanız (size "Yeti ile giriş" ile bağlanmış bir kullanıcı) talebe "yeti_kodu": "YETI-7K3P9Q" ekleyin. Kullanıcının telefonuna "ödeme onayı bekliyor" bildirimi gider; masaüstünde sizin sitenizdeyken ödemeyi Yeti Cüzdan uygulamasından onaylayabilir. Böyle bir talebi yalnızca o kullanıcı görür ve öder. Bağlı olmayan bir kullanıcıya talep gönderilemez (422 baglanti_yok). Yanıtta "hedef": {"yeti_kodu": …} döner.

3. Otomatik harcama izni

Oyun içi küçük alımlar, dizi bölümü gibi sık harcamalar için. Kullanıcı bir kez günlük limitli izin verir, sonraki harcamalar yönlendirmesiz yapılır.

1. Kullanıcıyı https://yeticuzdan.com/izin/{uygulama-kodu}?gunluk_limit=5000&donus=https://uygulamaniz.com/… adresine yönlendirin; onaydan sonra donus?izin=verildi ile döner.
2. İzin durumunu sorgulayın: GET /api/v1/izinler/{yeti_kodu}
3. Harcayın:

POST /api/v1/harcamalar
Idempotency-Key: arsa-77812

{ "yeti_kodu": "YETI-7K3P9Q", "tutar": "2500", "aciklama": "Galata · arsa 19/302114/197532" }

→ 201 { "islem_id": "…", "tutar": "2500", "gunluk_kalan": "2500" }

Olası hatalar: 403 izin_yok, 422 limit_asildi, 422 yetersiz_bakiye, 404 kullanici_bulunamadi, 503 hizmet_kapali.

4. Kazandırma (ödül)

Uygulamanın cüzdandaki ödül bütçesinden kullanıcıya Yeti verir. Bütçe yönetimden yüklenir; uygulama kendi başına Yeti üretemez.

POST /api/v1/oduller
Idempotency-Key: haftalik-yaris-2026-42-1

{ "yeti_kodu": "YETI-7K3P9Q", "tutar": "500", "aciklama": "Haftalık yarışma birinciliği", "kova": "bonus" }

→ 201 { "islem_id": "…", "tutar": "500", "kalan_butce": "4999500" }

kova: bonus (varsayılan; kampanya ve hediye) ya da kazanilan (görev, başarı gibi emek karşılığı). İkisi de harcanır, hiçbiri TL'ye çevrilmez.

5. Çevirici (Yeti → uygulama bakiyesi)

Kendi bakiyesi olan uygulamalar (reklam bakiyesi, oyun kredisi, coin) yönetimden çevirici oranı tanımlar (ör. 100 Yeti = 1 ₺ reklam bakiyesi). Kullanıcı çevirmeyi cüzdanda başlatır; Yeti uygulamanın gelir hesabına geçer ve size bildirim gelir:

Yeti-Olay: cevirme.odendi

{
  "id": "5f0e…",
  "durum": "odendi",
  "yeti_kodu": "YETI-7K3P9Q",
  "birim_miktari": "25",
  "birim": "₺ reklam bakiyesi",
  "yeti": "2500",
  "son_teslim": "…"
}

Bakiyeyi kullanıcınıza yükleyin (tekrar gelirse id ile ayıklayın), sonra teslimi onaylayın:

POST /api/v1/cevirmeler/{id}/teslim          → { …, "durum": "teslim" }
POST /api/v1/cevirmeler/{id}/iade            (Idempotency-Key; kullanıcı bulunamadıysa)
GET  /api/v1/cevirmeler?durum=odendi         (bildirimi kaçırdıysanız bekleyenler)

Süresinde (varsayılan 24 saat) teslim onaylanmazsa Yeti kullanıcıya otomatik iade edilir ve cevirme.iade_edildi bildirimi gelir. Uygulama bakiyesi Yeti'ye geri çevrilmez.

6. Kullanıcıya bildirim

Size bağlı kullanıcıya Yeti Cüzdan üzerinden hizmet bildirimi gönderebilirsiniz (telefonuna ve cüzdandaki bildirim kutusuna gider). Örnek: "Gönderin reddedildi", "Siparişin kargoya verildi". Yönetimin uygulamanıza bildirim izni vermesi gerekir.

POST /api/v1/bildirimler        (Idempotency-Key zorunlu)
{
  "yeti_kodu": "YETI-7K3P9Q",
  "baslik": "Gönderin reddedildi",                         (en çok 80 karakter; başına uygulamanızın adı eklenir)
  "govde": "Uygulama testi: ekran görüntüsü okunmuyor",    (en çok 240 karakter)
  "baglanti": "https://uygulamaniz.com/panel/gorevlerim"  (isteğe bağlı; dokununca açılır, alan adınızda https)
}
→ 201 { "bildirim_id": 42, "iletildi": true }
→ 200 { "bildirim_id": null, "iletildi": false }          (kullanıcı uygulama bildirimlerini kapatmış)

Kurallar: reklam ve kampanya bildirimi yasaktır (ticari ileti onayı gerektirir). Metinde e-posta adresi ya da telefon numarası olamaz (422 kisisel_veri). Kullanıcı başına günde en çok 10 bildirim (429 sinir_asildi). Bağlı olmayan kullanıcıya gönderilemez (422 baglanti_yok). Aynı Idempotency-Key ikinci bildirim üretmez. Kullanıcı "Uygulama bildirimleri"ni istediği zaman kapatabilir.

Yeti Cüzdan mobil uygulaması

Entegrasyonunuz için ayrıca bir şey yapmanız gerekmez. Kullanıcıyı her zamanki gibi cüzdan adresine (/baglan, /ode, /izin) yönlendirin:

• Telefonda Yeti Cüzdan uygulaması yüklüyse bu adresler doğrudan uygulamada açılır; kullanıcı orada parmak izi ya da ekran kilidiyle onaylar.
• Android tarayıcısında kalan kullanıcıya cüzdan sayfasında "Yeti Cüzdan uygulamasında aç" düğmesi gösterilir.
• Kendi yerel (Android/iOS) uygulamanız varsa aynı yolu uygulama şemasıyla da açabilirsiniz:

yeticuzdan://baglan/{uygulama}?donus=…&durum=…&kod_ozeti=…
yeticuzdan://ode/{talep_id}
yeticuzdan://izin/{uygulama}?gunluk_limit=5000&donus=…

Onaydan sonra kullanıcı yine sizin donus / donus_url adresinize döner (kendi alan adınızda https ya da "Yeti ile giriş" için kayıtlı mobil dönüş adresiniz). Sonucu her zaman sunucunuzdan API ile doğrulayın.

Uygulamanız tarayıcı kabuğuysa (WebView): cüzdan sayfasını kendi WebView'ınızda açmayın (kullanıcı adres çubuğunu göremez). Önce yeticuzdan://baglan/… adresini açmayı deneyin; Yeti Cüzdan uygulaması yoksa cüzdan adresini sistemin uygulama içi tarayıcısında (Android Custom Tabs / iOS ASWebAuthenticationSession) açın. Mobil dönüş adresinize gelen kod ve durum'u WebView'ınızdaki dönüş sayfanıza aktarın (oturum çerezi oradadır).

Masaüstü: Kullanıcı bilgisayarda "Yeti ile giriş"e tıkladığında Yeti Cüzdan giriş sayfası şifre formunun yanında bir QR gösterir; kullanıcı telefonundaki Yeti Cüzdan uygulamasıyla okutup onaylar ve akış kaldığı yerden size döner. Bunun için ayrıca bir şey yapmanız gerekmez.

Webhook

Olaylar: odeme.tamamlandi, odeme.iade_edildi, izin.kaldirildi, baglanti.kaldirildi, cevirme.odendi, cevirme.iade_edildi. Her istek imzalıdır:

Yeti-Imza: t=1760025600,v1=<hex HMAC-SHA256("t.gövde", webhook_sırrı)>

// PHP doğrulama örneği
[$t, $v1] = sscanf($_SERVER['HTTP_YETI_IMZA'], 't=%d,v1=%s');
$beklenen = hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $sir);
if (!hash_equals($beklenen, $v1) || abs(time() - $t) > 300) { http_response_code(400); exit; }

2xx dönmeyen teslimler artan aralıklarla 8 kez yeniden denenir. Aynı olay birden fazla gelebilir; tekrarları ayıklayın.

Kurallar

• Yeti yalnızca ekosistemin kendi ürün ve hizmetlerinde harcanır; bağımsız satıcılara ödeme olarak geçirilmez.
• Kullanıcıdan kullanıcıya Yeti aktaran bir özellik (hediye, transfer, Yeti karşılığı eşya/arsa satışı) yapılmaz.
• Kolayca paraya dönen şeyler (hediye kartı, e-pin, altın, kontör) Yeti ile satılmaz.
• Şans oyunlarında (çark, kutu, piyango) Yeti ile giriş ya da Yeti ödülü kullanılmaz.

Hazırlık aşaması

GET /api/v1/durum → {"hizmet_acik": false, …}. Hizmet kapalıyken entegrasyonunuzu geliştirebilirsiniz: Yeti ile giriş, talep oluşturma ve sorgulama çalışır; Yeti hareketi yapan istekler 503 hizmet_kapali döner.