Loyetta

Kimlik Doğrulama

Bir kullanıcı adına herhangi bir API isteği yapmadan önce, ilk olarak bir Müşteri Token'ı oluşturmanız gerekir. Bu token, sonraki tüm API çağrılarında kullanacağınız token'dır.

Müşteri Token'ı Oluşturma

Kullanıcılarınız adına Loyetta ile etkileşim kurmak için, backend'inizin önce authenticate endpoint'ini çağırması gerekir. Bu endpoint:

  1. Müşteri Loyetta'da yoksa müşteriyi oluşturur
  2. Gelecekteki tüm API isteklerinde kullanacağınız bir Müşteri Token'ı döndürür
POST/api/v1/superuser/authenticate

Süper Kullanıcı Token'ı yalnızca müşteri girişi (auth) veya ürün kullanım kaydı oluşturma gibi yönetimsel işlemlerde gereklidir. Diğer tüm standart API istekleri için Müşteri Token'ı kullanılmalıdır.

İstek

Başlıklar (Headers)

BaşlıkDeğer
AuthorizationBearer {super-kullanici-tokeniniz}
Content-Typeapplication/json
Acceptapplication/json

Gövde Parametreleri (Body)

ParametreTürZorunluAçıklama
customer_idstringEvetBu müşteri için sizin benzersiz tanımlayıcınız (maks. 191 karakter)
device_handlestringEvetBenzersiz cihaz tanımlayıcısı (maks. 191 karakter). Detaylar için aşağıya bakın.
platformstringHayırandroid, ios veya web
osstringHayırİşletim sistemi adı (örn. "iOS", "Android")
os_versionstringHayırİşletim sistemi versiyonu (örn. "17.0", "14")
brandstringHayırCihaz üreticisi (örn. "Apple", "Samsung")
modelstringHayırCihaz modeli (örn. "iPhone 15", "Galaxy S24")
fcm_tokenstringHayırPush bildirimleri için Firebase Cloud Messaging token'ı

device_handle Hakkında

device_handle parametresi kullanıcı cihazlarını ve oturumlarını takip etmek için kullanılır. Bu parametre şu özellikleri mümkün kılar:

  • Çoklu cihaz oturum yönetimi
  • Cihaza özel push bildirimleri
  • Cihaz kullanım desenleri analitiği
  • Şüpheli giriş desenleri için güvenlik izleme

Şiddetle Önerilir: Kalıcı bir cihaz tanımlayıcısı oluşturun ve kullanıcının cihazında saklayın. O cihazdan yapılan her girişte aynı device_handle değerini gönderin.

Önerilen Yaklaşım

Uygulamanız ilk kurulduğunda bir UUID oluşturun ve yerel olarak kalıcı hale getirin:

javascript
// İlk uygulama açılışında, bir cihaz ID'si oluşturun ve saklayın
const deviceId = localStorage.getItem('device_id') || crypto.randomUUID();
localStorage.setItem('device_id', deviceId);

// Bu cihazdan yapılan tüm authenticate isteklerinde aynı ID'yi kullanın
const response = await fetch('/api/v1/superuser/authenticate', {
  body: JSON.stringify({
    customer_id: 'kullanici_12345',
    device_handle: deviceId,
    // ...
  })
});

Alternatif Yaklaşım

Sisteminiz cihaz tanımlayıcılarını kalıcı olarak saklayamıyorsa, her giriş isteğinde rastgele bir UUID oluşturabilirsiniz. Ancak bu yaklaşım:

  • Çoklu cihaz takip özelliklerini kaybettirir
  • Her girişte yeni bir "cihaz" kaydı oluşturur
  • Üretim kullanımı için önerilmez
javascript
// Alternatif: her seferinde rastgele UUID (önerilmez)
const response = await fetch('/api/v1/superuser/authenticate', {
  body: JSON.stringify({
    customer_id: 'kullanici_12345',
    device_handle: crypto.randomUUID(), // Her seferinde yeni ID
    // ...
  })
});

Örnek İstek

bash
curl -X POST https://{subdomain'iniz}.prod.loyetta.com/api/v1/superuser/authenticate \
  -H "Authorization: Bearer {super-kullanici-tokeniniz}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customer_id": "kullanici_12345",
    "device_handle": "550e8400-e29b-41d4-a716-446655440000",
    "platform": "ios",
    "os": "iOS",
    "os_version": "17.0",
    "brand": "Apple",
    "model": "iPhone 15"
  }'

Yanıt

Başarılı (200)

json
{
  "success": true,
  "token": "1|abc123def456...",
  "user": {
    "id": 42,
    "customer_id": "kullanici_12345",
    "points": 0,
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

Yanıt Alanları

AlanAçıklama
successİşlemin başarılı olduğunu belirten boolean değer
tokenMüşteri Token'ı - Sonraki tüm API isteklerinde bunu kullanın
user.idLoyetta'nın dahili kullanıcı ID'si
user.customer_idSizin müşteri tanımlayıcınız (gönderdiğiniz değerin aynısı)
user.pointsMevcut puan bakiyesi
user.created_atKullanıcının Loyetta'da ilk oluşturulduğu zaman

Önemli: user.id Loyetta'nın dahili tanımlayıcısıdır. Loyetta kullanıcılarını kendi veritabanı kayıtlarınızla eşleştirmek için user.customer_id kullanın.

Müşteri Token'ını Kullanma

Müşteri Token'ı oluşturduktan sonra, sonraki tüm API isteklerinde Authorization başlığında kullanın:

bash
curl https://{subdomain'iniz}.prod.loyetta.com/api/v1/user/profile \
  -H "Authorization: Bearer {musteri-tokeni}" \
  -H "Accept: application/json"

Müşteri Token'ı şunlara erişim sağlar:

  • Kullanıcı profili ve puanlar
  • Ödüller ve mağaza
  • Oyunlar ve kampanyalar
  • Tüm kullanıcıya özel işlemler

Hata Yanıtları

Yasak (403)

Token'ınız süper kullanıcı ayrıcalıklarına sahip değil:

json
{
  "message": "Operation not allowed."
}

Doğrulama Hatası (422)

Zorunlu alanlar eksik veya geçersiz:

json
{
  "message": "The customer_id field is required.",
  "errors": {
    "customer_id": ["The customer_id field is required."]
  }
}

Yetkisiz (401)

Authorization başlığı eksik veya token geçersiz:

json
{
  "message": "Unauthenticated."
}

Tam Entegrasyon Örneği

javascript
class LoyettaClient {
  constructor(superUserToken, baseUrl) {
    this.superUserToken = superUserToken;
    this.baseUrl = baseUrl;
  }

  // Kullanıcınız giriş yaptığında bunu çağırın
  async authenticateCustomer(customerId, deviceHandle, deviceInfo = {}) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/superuser/authenticate`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.superUserToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json',
        },
        body: JSON.stringify({
          customer_id: customerId,
          device_handle: deviceHandle,
          ...deviceInfo, // platform, os, os_version, brand, model, fcm_token
        }),
      }
    );

    const data = await response.json();

    if (!data.success) {
      throw new Error(data.message);
    }

    // Sonraki istekler için müşteri token'ını döndür
    return data.token;
  }

  // Diğer tüm API çağrıları için müşteri token'ını kullanın
  async getUserProfile(customerToken) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/user/profile`,
      {
        headers: {
          'Authorization': `Bearer ${customerToken}`,
          'Accept': 'application/json',
        },
      }
    );

    return response.json();
  }
}