/api/v2/server-side-api/vc/transactions/ Sanal para birimi işlemi oluştur
Tek bir atomik işlemde bir profil için bir veya daha fazla sanal para birimini alacaklandırır veya borçlandırır. Alacaklandırmak (vermek) için pozitif amount, borçlandırmak (harcamak) için negatif amount kullanın. Tüm öğeler birlikte uygulanır — herhangi bir öğe başarısız olursa, hiçbiri uygulanmaz.
Her para birimi kodu istek başına yalnızca bir kez görünebilir. Bu uç nokta aracılığıyla yapılan bir alacaklandırma her zaman süresi dolmayan bir bakiye oluşturur.
İşlemi sanal para birimi analizlerinde kullanılabilir hale getirmek için operation ve feature ile etiketleyin. Tüm etiketleme alanları isteğe bağlıdır: yalnızca items ve metadata içeren bir istek operation: null ile kaydedilir.
Header parameters
Sisteminizdeki müşterinin benzersiz kimliği. adapty-customer-user-id veya adapty-profile-id'den biri zorunludur.
Sisteminizdeki profilin benzersiz kimliği. Anonim profillerle çalışıyorsanız en iyi seçeneğinizdir. adapty-customer-user-id veya adapty-profile-id'den biri zorunludur.
İsteği idempotent yapan bir UUID v4. Aynı anahtarla bir isteği yeniden denerseniz, Adapty bakiyeleri tekrar değiştirmeden orijinal işlemin sonucunu döndürür. Geçerli bir UUID v4 olmalıdır.
Anahtarlar tek bir profile kapsamlı olarak bir saate kadar hatırlanır. Bu süre dolduktan sonra, aynı anahtara sahip bir istek yeni bir işlem olarak uygulanır — dolayısıyla anahtarı bir çağrıyı güvenli şekilde yeniden denemek için kullanın, uzun vadede bir vermeyi tekilleştirmek için değil.
Request body
Sanal para birimi işlemi oluşturmak için istek gövdesi.
Atomik olarak uygulanacak bakiye düzenlemeleri. Her para birimi kodu yalnızca bir kez görünebilir.
Düzenlenecek sanal para birimi kodu.
Uygulanacak miktar. Pozitif bir değer para birimini alacaklandırır (ekler); negatif bir değer ise borçlandırır (harcar). Sıfır olamaz.
İşlemle birlikte saklanan isteğe bağlı anahtar-değer çiftleri. En fazla 5 anahtar. Her anahtar ^[a-z0-9_]{1,30}$ kalıbıyla eşleşmeli, her değer en fazla 200 karakter olmalıdır.
İşlemin ne anlama geldiği. Çoğu entegrasyon dört değere ihtiyaç duyar: spend, spend_reversal, reward, reward_reversal. Belirtilmezse işlem kaydedilir ve operation: null ile döndürülür.
Değerler: top_up — bir satın alma, abonelik veya deneme için yüklenen jetonlar; refund — para iade edildiği için geri alınan jetonlar; spend — bir özellik veya içerik için harcanan jetonlar; spend_reversal — başarısız bir işlem (örneğin başarısız bir üretim) nedeniyle iade edilen jetonlar; reward — bonus, ödül veya destek tazminatı; reward_reversal — geri alınan bir ödül; exchange — tek bir işlemde zıt işaretli kalemlerle para birimleri arasında dönüşüm; expiry — süresi dolan jetonlar; migration — kendi sisteminizden taşınan bakiyeler; adjustment — uygulama içi ekonominin dışında teknik bir bakiye düzeltmesi.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
Jetonların ne için harcandığı veya ne karşılığında verildiği. Bir kelime, isteğe bağlı olarak noktalı bir alt tür içerebilir: ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$ kalıbıyla eşleşmelidir. Gönderildiği şekilde saklanır, büyük/küçük harf duyarlıdır. Fiyat, katman, sürüm veya varyant kodlamayın. Örnek: power_up.extra_life.
Uygulamanızda işlemin gerçekleştiği ekran veya placement'ın kimliği. Bu sizin kendi kimliğinizdir, bir Adapty placement kimliği değildir. ^[a-zA-Z0-9_.-]{1,128}$ kalıbıyla eşleşmelidir. Gönderildiği şekilde saklanır. Örnek: onboarding-step-3.
Sisteminizdeki ilgili nesnenin kimliği; örneğin bir üretim, ödül veya destek talebi. 1–128 karakter; kontrol, BIDI ve sıfır genişlikli karakterler reddedilir. Buraya kişisel veri koymayın. Örnek: ticket_48213.
Test sırasında verdiğiniz jetonlar için true olarak ayarlayın.
Bu işlemin atıfta bulunduğu satın almanın mağazası: app_store, play_store, stripe, paddle veya uygulamada yapılandırılmış özel bir mağazanın kimliği. En fazla 30 karakter. Satın alma mağazada iade edilirse, bu referansla yüklenen jetonlar geri alınır. store_transaction_id ile birlikte gönderin.
İlgili satın almanın mağaza işlem kimliği. En fazla 50 karakter. Yalnızca bir referanstır: Adapty bunun var olup olmadığını veya benzersiz olup olmadığını kontrol etmez. store ile birlikte gönderin.
Responses
İşlem oluşturuldu. Gövde, işlem geçmişinin bir öğesiyle aynı biçimde oluşturulan işlemi ve işlem sonrası bakiyeleri içerir.
Schema
Oluşturulan işlem, işlem geçmişinin bir öğesiyle aynı biçimde, artı işlem sonrası bakiyeler.
İşlemin benzersiz kimliği.
İşlemin kaynağı. store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund veya expiry değerlerinden biri.
Bu işlemde kaydedilen para birimi başına bakiye değişiklikleri.
Sanal para birimi kodu.
Bakiyeye uygulanan işaretli değişim. Pozitif bir değer alacak, negatif bir değer borçtur.
Bu işlem uygulandıktan sonraki para birimi bakiyesi.
İşlemle birlikte saklanan anahtar-değer çiftleri (varsa).
İşlemin ne anlama geldiği. Adapty bunu kendi işlemlerinde otomatik olarak belirler: store_purchase, subscription_renewal ve trial_start için top_up, refund için refund, expiry için expiry atanır. Bir dashboard_transaction söz konusu olduğunda, bir ekip üyesinin Adapty Kontrol Paneli'nde bakiyeyi ayarlarken seçtiği işlemdir. Bir api_transaction söz konusu olduğunda ise sizin gönderdiğiniz değerdir; hiçbir değer göndermemişseniz null olur.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
Coinlerin ne için harcandığı veya ne karşılığında verildiği; sizin gönderdiğiniz değerdir. Adapty tarafından oluşturulan işlemlerde null olur.
Uygulamanızdaki ekran veya placement kimliği; sizin gönderdiğiniz değerdir. Adapty tarafından oluşturulan işlemlerde null olur.
Kendi sisteminizdeki ilgili nesnenin kimliği; sizin gönderdiğiniz değerdir. Adapty tarafından oluşturulan işlemlerde null olur.
İşlemin test işlemi olup olmadığı. Adapty tarafından oluşturulan işlemlerde mağaza satın alımının ortamını izler. Bir api_transaction söz konusu olduğunda ise sizin gönderdiğiniz değerdir; varsayılan olarak false kabul edilir.
İlgili satın alımın mağazası. Adapty tarafından mağaza olaylarından (satın alma, yenileme, deneme, iade) oluşturulan işlemlerde ve bir satın alma referansıyla gönderilen api_transaction işlemlerinde doldurulur.
İlgili satın alımın mağaza işlem kimliği. store ile aynı işlemlerde doldurulur.
İşlemin kaydedildiği zaman.
Yanıtın oluşturulduğu zaman, milisaniye cinsinden Unix zaman damgası olarak.
Bu istek tarafından etkilenen her para birimi için işlem sonrası bakiye (items içindeki her öğe için bir giriş). Profil için tam bakiye listesini okumak üzere GET /api/v2/server-side-api/vc/balances/ kullanın.
Sanal para birimi kodu.
Sanal para biriminin görünen adı.
Şu anda beklemede tutulan miktarlar dahil toplam bakiye.
Tüm aktif beklemelerin toplamı (rezerve edilmiş miktarlar). Şu anda her zaman 0'dır.
Harcanabilir bakiye; balance - held olarak hesaplanır.
Example
{
"transaction_id": "019a7c3e-5b2a-7c1d-9e4f-0a1b2c3d4e5f",
"transaction_type": "api_transaction",
"items": [
{
"currency_code": "COINS",
"amount": -10,
"balance_after": 90
}
],
"metadata": null,
"operation": "spend",
"feature": "power_up.extra_life",
"customer_placement_id": "level-complete",
"reference_id": "session_7781",
"is_sandbox": false,
"store": null,
"store_transaction_id": null,
"created_at": "2026-11-12T10:00:00.123Z",
"response_created_at": 1794477600123,
"balances": [
{
"code": "COINS",
"name": "Coins",
"balance": 90,
"held": 0,
"available": 90
}
]
} Hatalı istek. error_code alanı nedeni tanımlar:
validation_error— gövde veya başlıklar geçersiz. Örneğin, bir etiketleme alanı biçimini bozuyor,itemsboş veya 20'den fazla girişe sahip, biramount0 ya da int32 aralığının dışında, bir para birimi kodu tekrarlanıyor,metadatakısıtlamalarını ihlal ediyor ya da neadapty-profile-idne deadapty-customer-user-idgönderilmiş.errors[].sourcealanı isimlendirir.store'unstore_transaction_idolmadan gönderilmesi gibi birden fazla alanı kapsayan bir kontrol içinsourceboş bir dizedir.parse_error— gövde geçerli JSON değil.idempotency_key_invalid—Idempotency-Keybir UUID v4 değil.unknown_currency— para birimi uygulamada kurulu değil.unknown_store—storeuygulamada kurulu olmayan özel bir mağaza.insufficient_balance— bir borçlandırma mevcut bakiyeyi aşıyor.balance_overflow— bir alacaklandırma bakiyeyi int32 aralığının ötesine taşıyacak.
Schema
Hatanın kaynağı
Hata mesajları dizisi
Kısa hata adı
HTTP durum kodu
Example
{
"errors": [
{
"source": "feature",
"errors": [
"String should match pattern '^[a-zA-Z0-9_]{1,32}(\\.[a-zA-Z0-9_]{1,32})?$'"
]
}
],
"error_code": "validation_error",
"status_code": 400
} Yetkisiz. API anahtarı eksik veya geçersiz (error_code değeri not_authenticated).
Schema
Hatanın kaynağı
Hata mesajları dizisi
Kısa hata adı
HTTP durum kodu
Profil bulunamadı (error_code değeri profile_does_not_exist).
Schema
Hatanın kaynağı
Hata mesajları dizisi
Kısa hata adı
HTTP durum kodu
Çakışma. Aynı Idempotency-Key ile bir istek hâlâ işleniyor (error_code değeri idempotency_in_flight). Retry-After yanıt başlığındaki aralıktan sonra yeniden deneyin.
Schema
Hatanın kaynağı
Hata mesajları dizisi
Kısa hata adı
HTTP durum kodu
Example
{
"errors": [
{
"source": null,
"errors": [
"A similar request is being processed."
]
}
],
"error_code": "idempotency_in_flight",
"status_code": 409
} Çok fazla istek. Uygulama başına veya global istek sınırı aşıldı (error_code değeri rate_limited). Varsayılan sınırlar uygulama başına dakikada 600 istek ve global olarak dakikada 6000 istektir.
Schema
Hatanın kaynağı
Hata mesajları dizisi
Kısa hata adı
HTTP durum kodu
Dahili sunucu hatası