RevenueCat Kredi Paketleri Entegrasyonu

Migration rehberi

Yapılandırma sırası için Migration şablonu. Yeni düzenlemelerde Amaç → Önkoşullar → Endpoint → Request/Response → Hata kodları → Client adımları → İlgili sayfalar bölümlerini tercih edin.

Bu dokümantasyon, Allmine API'de RevenueCat kullanarak kredi paketleri sisteminin nasıl kurulacağını ve kullanılacağını açıklar.

📘 Konfigürasyon detayları için: RevenueCat ve Credit Packages Konfigürasyon Rehberi

Environment Variables
API Endpoint'leri
Webhook Kurulumu
Kredi Paketleri Oluşturma
Test Senaryoları
Troubleshooting

Sistem, RevenueCat API v2 kullanarak kredi paketleri (10, 100, 250, 500, 1000, 10000) yönetimini sağlar. Kullanıcılar bu paketleri satın alabilir ve satın alma sonrası krediler otomatik olarak hesaplarına eklenir.

Özellikler

✅ Tüm store'ları destekler (Apple App Store, Google Play Store, Test Store)
✅ Consumable product tipi (tekrar satın alınabilir)
✅ Webhook entegrasyonu ile otomatik kredi ekleme
✅ Transaction logging ile audit trail
✅ Admin endpoint'leri ile paket yönetimi
✅ Public endpoint'ler ile paket listeleme

RevenueCat Kurulumu

1. RevenueCat Hesabı Oluşturma

RevenueCat web sitesine gidin ve hesap oluşturun
Yeni bir proje oluşturun
Uygulamanızı ekleyin (iOS ve Android için ayrı app'ler)

2. API Key Oluşturma

RevenueCat Dashboard -> Project Settings -> API Keys
"New" butonuna tıklayın
Key adı verin (örn: "Allmine Backend API Key")
Version: V2 seçin
Permissions:
- project_configuration:products:read_write
- project_configuration:apps:read
- customer_information:customers:read
"Generate" butonuna tıklayın
Secret Key'i kopyalayın (sadece bir kez gösterilir!)

3. Project ID Bulma

RevenueCat Dashboard -> Project Settings
Project ID'yi kopyalayın (format: proj_xxxxxxxxxxxxx)

4. App ID Bulma

RevenueCat Dashboard -> Apps
İlgili app'i seçin
App ID'yi kopyalayın (format: app_xxxxxxxxxxxxx)

5. Store Ürünlerini Oluşturma

Apple App Store

App Store Connect -> Your App -> Features -> In-App Purchases
Her kredi paketi için "Consumable" tipinde ürün oluşturun:
- 10 Credits: com.allmine.credits.10
- 100 Credits: com.allmine.credits.100
- 250 Credits: com.allmine.credits.250
- 500 Credits: com.allmine.credits.500
- 1000 Credits: com.allmine.credits.1000
- 10000 Credits: com.allmine.credits.10000

Google Play Store

Google Play Console -> Your App -> Monetize -> Products -> In-app products
Her kredi paketi için ürün oluşturun:
- 10 Credits: credits_10
- 100 Credits: credits_100
- 250 Credits: credits_250
- 500 Credits: credits_500
- 1000 Credits: credits_1000
- 10000 Credits: credits_10000

Test Store (Development)

Test Store için özel store identifier'lar kullanılabilir:

test_credits_10
test_credits_100
vb.

Environment Variables

Aşağıdaki environment variable'ları .env dosyanıza ekleyin:

# RevenueCat Configuration
REVENUECAT_SECRET_KEY=sk_xxxxxxxxxxxxx
REVENUECAT_PROJECT_ID=proj_xxxxxxxxxxxxx
REVENUECAT_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx  # Opsiyonel, webhook signature doğrulama için
REVENUECAT_BASE_URL=https://api.revenuecat.com/v2  # Opsiyonel, varsayılan değer

# RevenueCat App IDs (Store bazlı)
REVENUECAT_APP_ID_TEST=appae0e1f5439  # Test Store App ID
REVENUECAT_APP_ID_APPLE=appd24d573b8b  # Apple App Store App ID
REVENUECAT_APP_ID_GOOGLE=app_xxxxxxxxxxxxx  # Google Play Store App ID (İleride eklenecek, opsiyonel)
REVENUECAT_APP_ID_WEB=app_xxxxxxxxxxxxx  # Web App ID (İleride eklenecek, opsiyonel)

Environment Variable Açıklamaları

REVENUECAT_SECRET_KEY: RevenueCat API v2 Secret Key (zorunlu)
REVENUECAT_PROJECT_ID: RevenueCat Project ID (zorunlu)
REVENUECAT_WEBHOOK_SECRET: Webhook signature doğrulama için secret (opsiyonel)
REVENUECAT_BASE_URL: RevenueCat API base URL (opsiyonel, varsayılan: https://api.revenuecat.com/v2)
REVENUECAT_APP_ID_TEST: Test Store App ID (zorunlu)
REVENUECAT_APP_ID_APPLE: Apple App Store App ID (zorunlu)
REVENUECAT_APP_ID_GOOGLE: Google Play Store App ID (opsiyonel, ileride eklenecek)
REVENUECAT_APP_ID_WEB: Web App ID (opsiyonel, ileride eklenecek)

GET /api/credit-packages
GET /api/credit-packages?activeOnly=true

Response:

[
  {
    "id": "65a1234bcde5678f90123456",
    "creditAmount": 100,
    "revenuecatProductId": "prod1a2b3c4d5",
    "storeIdentifier": "com.allmine.credits.100",
    "displayName": "100 Credits",
    "isActive": true,
    "price": 9.99,
    "storeType": "apple",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

2. Kredi Paketi Detayı

GET /api/credit-packages/:id

Admin Endpoints

Tüm admin endpoint'leri Role.ADMIN yetkisi gerektirir.

1. Kredi Paketi Oluştur

POST /api/credit-packages
Authorization: Bearer <JWT_TOKEN>
Content-Type: multipart/form-data

Request Body (multipart/form-data):

creditAmount: 100
storeIdentifier: com.allmine.credits.100
displayName: 100 Credits
storeType: apple
isActive: true
price: 9.99

cURL Örneği:

curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -F "creditAmount=100" \
  -F "storeIdentifier=com.allmine.credits.100" \
  -F "displayName=100 Credits" \
  -F "storeType=apple" \
  -F "isActive=true" \
  -F "price=9.99"

Not:

Endpoint multipart/form-data formatında veri bekler
appId artık gerekli değil. storeType'a göre otomatik olarak doğru App ID seçilir:
- test → REVENUECAT_APP_ID_TEST
- apple → REVENUECAT_APP_ID_APPLE
- google → REVENUECAT_APP_ID_GOOGLE (ileride)
- web → REVENUECAT_APP_ID_WEB (ileride)

Response:

{
  "id": "65a1234bcde5678f90123456",
  "creditAmount": 100,
  "revenuecatProductId": "prod1a2b3c4d5",
  "storeIdentifier": "com.allmine.credits.100",
  "displayName": "100 Credits",
  "isActive": true,
  "price": 9.99,
  "storeType": "apple",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

2. Kredi Paketi Güncelle

PATCH /api/credit-packages/:id
Authorization: Bearer <JWT_TOKEN>

Request Body:

{
  "displayName": "100 Credits Package",
  "isActive": true,
  "price": 8.99
}

3. Kredi Paketi Sil

DELETE /api/credit-packages/:id
Authorization: Bearer <JWT_TOKEN>

Webhook Kurulumu

1. RevenueCat Dashboard'da Webhook Ayarlama

RevenueCat Dashboard -> Project Settings -> Webhooks
"Add Webhook" butonuna tıklayın
Webhook URL'ini girin: https://your-domain.com/api/revenuecat/webhook
Events seçin:
- INITIAL_PURCHASE (zorunlu)
- RENEWAL (opsiyonel, consumable için gerekli değil)
- CANCELLATION (opsiyonel)
- BILLING_ISSUE (opsiyonel)
Webhook Secret'i kopyalayın ve REVENUECAT_WEBHOOK_SECRET environment variable'ına ekleyin

2. Webhook Endpoint

POST /api/revenuecat/webhook

Request Headers:

Content-Type: application/json
X-RevenueCat-Signature: <signature>  # Opsiyonel, webhook secret varsa

Request Body (Örnek):

{
  "event": "INITIAL_PURCHASE",
  "app_user_id": "user-123",
  "product_id": "prod1a2b3c4d5",
  "transaction_id": "trans_1234567890",
  "store": "APP_STORE",
  "purchased_at_ms": 1234567890000
}

Response:

{
  "received": true
}

3. Webhook İşleme Akışı

Kullanıcı kredi paketi satın alır (mobil uygulama üzerinden)
RevenueCat satın alma işlemini doğrular
RevenueCat webhook gönderir
Backend webhook'u alır ve signature doğrular (eğer secret varsa)
INITIAL_PURCHASE event'i için:
- Product ID'ye göre credit package bulunur
- Kullanıcının creditBalance'ına kredi eklenir
- Transaction log kaydedilir

Kredi Paketleri Oluşturma

Örnek: 100 Kredi Paketi Oluşturma

curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "creditAmount": 100,
    "storeIdentifier": "com.allmine.credits.100",
    "appId": "app1a2b3c4",
    "displayName": "100 Credits",
    "storeType": "apple",
    "isActive": true,
    "price": 9.99
  }'

Tüm Paketleri Oluşturma

Aşağıdaki script ile tüm kredi paketlerini oluşturabilirsiniz:

# 10 Credits (Apple)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=10" \
  -F "storeIdentifier=com.allmine.credits.10" \
  -F "displayName=10 Credits" \
  -F "storeType=apple" \
  -F "isActive=true"

# 100 Credits (Apple)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=100" \
  -F "storeIdentifier=com.allmine.credits.100" \
  -F "displayName=100 Credits" \
  -F "storeType=apple" \
  -F "isActive=true"

# 250 Credits (Apple)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=250" \
  -F "storeIdentifier=com.allmine.credits.250" \
  -F "displayName=250 Credits" \
  -F "storeType=apple" \
  -F "isActive=true"

# 500 Credits (Apple)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=500" \
  -F "storeIdentifier=com.allmine.credits.500" \
  -F "displayName=500 Credits" \
  -F "storeType=apple" \
  -F "isActive=true"

# 1000 Credits (Apple)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=1000" \
  -F "storeIdentifier=com.allmine.credits.1000" \
  -F "displayName=1000 Credits" \
  -F "storeType=apple" \
  -F "isActive=true"

# 10000 Credits (Apple)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=10000" \
  -F "storeIdentifier=com.allmine.credits.10000" \
  -F "displayName=10000 Credits" \
  -F "storeType=apple" \
  -F "isActive=true"

# Test Store için örnek (10 Credits)
curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>" \
  -F "creditAmount=10" \
  -F "storeIdentifier=test_credits_10" \
  -F "displayName=10 Test Credits" \
  -F "storeType=test" \
  -F "isActive=true"

Test Senaryoları

1. Kredi Paketi Oluşturma Testi

# Test: 100 kredi paketi oluştur (Test Store)
curl -X POST http://localhost:3000/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -F "creditAmount=100" \
  -F "storeIdentifier=test_credits_100" \
  -F "displayName=100 Test Credits" \
  -F "storeType=test" \
  -F "isActive=true"

2. Kredi Paketlerini Listeleme Testi

# Tüm paketleri listele
curl http://localhost:3000/api/credit-packages

# Sadece aktif paketleri listele
curl http://localhost:3000/api/credit-packages?activeOnly=true

3. Webhook Testi

# Test webhook event gönder
curl -X POST http://localhost:3000/api/revenuecat/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "event": "INITIAL_PURCHASE",
    "app_user_id": "test-user-123",
    "product_id": "prod_test_100",
    "transaction_id": "trans_test_123",
    "store": "TEST_STORE",
    "purchased_at_ms": 1234567890000
  }'

4. Kullanıcı Kredi Bakiyesi Kontrolü

# Kullanıcı bilgilerini getir (kredi bakiyesi dahil)
curl http://localhost:3000/api/users/me \
  -H "Authorization: Bearer <USER_TOKEN>"

Troubleshooting

Problem: "RevenueCat configuration is missing"

Çözüm:

Environment variable'ların doğru ayarlandığından emin olun
.env dosyasını kontrol edin
Uygulamayı yeniden başlatın

Problem: "Product with this store identifier already exists"

Çözüm:

RevenueCat'te aynı store identifier'a sahip bir product zaten var
Farklı bir store identifier kullanın veya mevcut product'ı silin

Problem: "Webhook signature verification failed"

Çözüm:

REVENUECAT_WEBHOOK_SECRET environment variable'ının doğru olduğundan emin olun
RevenueCat Dashboard'dan webhook secret'ı tekrar kopyalayın
Webhook secret'ı RevenueCat Dashboard'da yeniden oluşturun

Problem: "Credit package not found for product ID"

Çözüm:

Product ID'nin doğru olduğundan emin olun
Credit package'ın veritabanında mevcut olduğunu kontrol edin
RevenueCat'te product'ın oluşturulduğundan emin olun

Problem: "User not found"

Çözüm:

app_user_id'nin doğru olduğundan emin olun
Kullanıcının veritabanında mevcut olduğunu kontrol edin
RevenueCat'te customer'ın oluşturulduğundan emin olun

Problem: Transaction duplicate processing

Çözüm:

Sistem otomatik olarak duplicate transaction'ları kontrol eder
Aynı transaction_id ile birden fazla işlem yapılmaz
Transaction log'ları kontrol edin

Güvenlik Notları

API Keys: Secret key'leri asla public repository'lere commit etmeyin
Webhook Secret: Webhook signature doğrulamasını production'da mutlaka aktif edin
Admin Endpoints: Admin endpoint'leri sadece güvenilir kullanıcılara açın
Transaction Logging: Tüm transaction'lar loglanır, audit trail için kullanılabilir

Ek Kaynaklar

Destek

Sorularınız için:

RevenueCat Support: https://www.revenuecat.com/support
Allmine API Documentation: /api/docs (Swagger UI)

RevenueCat credit packages entegrasyonu

On this page