# 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 alacak her zaman süresi dolmayan bir bakiye oluşturur.

## OpenAPI

```yaml
/api-specs/adapty-api.yaml post /api/v2/server-side-api/vc/transactions/
openapi: 3.1.0
info:
  title: Adapty sunucu taraflı API
  version: 1.0.0
servers:
  - url: https://api.adapty.io
    description: Üretim sunucusu
paths:
  /api/v2/server-side-api/vc/transactions/:
    post:
      summary: Sanal para birimi işlemi oluştur
      description: |
        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 alacak her zaman süresi dolmayan bir bakiye oluşturur.
      operationId: createVirtualCurrencyTransaction
      tags:
        - Virtual Currency
      security:
        - apikeyAuth: []
      parameters:
        - name: adapty-customer-user-id
          in: header
          required: false
          schema:
            type: string
          description: Sisteminizdeki müşterinin benzersiz kimliği. `adapty-customer-user-id` veya `adapty-profile-id` alanlarından biri zorunludur.
        - name: adapty-profile-id
          in: header
          required: false
          schema:
            type: string
          description: Sisteminizdeki profilin benzersiz kimliği. Anonim profillerle çalışıyorsanız en iyi seçeneğinizdir. `adapty-customer-user-id` veya `adapty-profile-id` alanlarından biri zorunludur.
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            format: uuid
          description: |
            İsteği idempotent yapan bir UUID v4 değeri. 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 profil kapsamında en fazla bir saat boyunca hatırlanır. Bu süre geçtikten sonra aynı anahtarla yapılan bir istek yeni bir işlem olarak uygulanır — dolayısıyla anahtarı uzun vadede tekrarlı bir vermeyi önlemek için değil, bir çağrıyı güvenli şekilde yeniden denemek için kullanın.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VirtualCurrencyTransactionRequest"
            examples:
              debit:
                summary: Bir para birimini harca (borçlandır)
                value:
                  items:
                    - currency_code: COINS
                      amount: -10
              credit:
                summary: Bir para birimini ver (alacaklandır)
                value:
                  items:
                    - currency_code: COINS
                      amount: 500
              multi_currency:
                summary: İki para birimini aynı anda borçlandır
                value:
                  items:
                    - currency_code: GOLD
                      amount: -50
                    - currency_code: SILVER
                      amount: -200
              conversion:
                summary: Bir para birimini diğerine dönüştür
                value:
                  items:
                    - currency_code: SILVER
                      amount: -100
                    - currency_code: GOLD
                      amount: 10
                  metadata:
                    reason: exchange
      responses:
        "200":
          description: İşlem başarıyla uygulandı
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VirtualCurrencyTransactionResponse"
              example:
                transaction_id: 0190e8a4-1c2b-7def-8abc-2c1a4b6d8e90
                balances:
                  - code: COINS
                    name: Gold Coins
                    balance: 12950
                    held: 0
                    available: 12950
        "400":
          description: |
            Hatalı istek. `error_code` alanı nedeni belirtir: `insufficient_balance`, `unknown_currency`, `duplicate_currency`, `amount_zero`, `balance_overflow`, `empty_items` veya `idempotency_key_invalid`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - source: currency_code
                    errors:
                      - Insufficient balance for currency COINS
                error_code: insufficient_balance
                status_code: 400
        "401":
          description: Yetkisiz. API anahtarı eksik veya geçersiz.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Erişim reddedildi. Bu uygulama için sanal para birimleri Sunucu API'si etkin değil. Erişim talep etmek için Adapty destek ekibiyle iletişime geçin.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - source: null
                    errors:
                      - Server API for virtual currencies is not enabled for this app. Contact Adapty support to request access.
                error_code: feature_not_enabled
                status_code: 403
        "404":
          description: Profil bulunamadı.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: |
            Çakışma. `error_code` alanı nedeni belirtir:

            - `idempotency_in_flight` — aynı `Idempotency-Key` değerine sahip bir istek hâlâ işleniyor. `Retry-After` yanıt başlığındaki aralıktan sonra yeniden deneyin.
            - `duplicate_source_transaction` — temel mağaza işlemi zaten alacaklandırıldığından tekrar uygulanmaz.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - source: null
                    errors:
                      - A similar request is being processed.
                error_code: idempotency_in_flight
                status_code: 409
        "422":
          description: |
            İşlenemeyen varlık. İstek gövdesi şema doğrulamasından geçemedi — örneğin `items` 20'den fazla giriş içeriyor ya da bir `metadata` anahtarı veya değeri kısıtlamalarını ihlal ediyor.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: |
            Çok fazla istek. Uygulama başına veya global hız 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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Dahili sunucu hatası
components:
  schemas:
    VirtualCurrencyTransactionRequest:
      type: object
      description: Sanal para birimi işlemi oluşturmak için istek gövdesi.
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 20
          description: Atomik olarak uygulanacak bakiye ayarlamaları. Her para birimi kodu yalnızca bir kez görünebilir.
          items:
            $ref: "#/components/schemas/VirtualCurrencyBalanceAdjustment"
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: |
            İşlemle birlikte depolanan isteğe bağlı anahtar-değer çiftleri. En fazla 5 anahtar. Her anahtar `^[a-z0-9_]{1,30}$` ile eşleşmeli, her değer en fazla 200 karakter olmalıdır.
      required:
        - items
    VirtualCurrencyTransactionResponse:
      type: object
      description: Sanal para birimi işleminin sonucu.
      properties:
        transaction_id:
          type: string
          format: uuid
          description: Oluşturulan işlemin benzersiz kimliği.
        balances:
          type: array
          description: |
            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.
          items:
            $ref: "#/components/schemas/VirtualCurrencyBalanceSnapshot"
      required:
        - transaction_id
        - balances
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                nullable: true
                description: Hatanın kaynağı
              errors:
                type: array
                items:
                  type: string
                description: Hata mesajları dizisi
        error_code:
          type: string
          description: Kısa hata adı
        status_code:
          type: integer
          description: HTTP durum kodu
      required:
        - errors
        - error_code
        - status_code
    VirtualCurrencyBalanceAdjustment:
      type: object
      properties:
        currency_code:
          type: string
          description: Düzenlenecek sanal para birimi kodu.
        amount:
          type: integer
          format: int32
          description: |
            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.
      required:
        - currency_code
        - amount
    VirtualCurrencyBalanceSnapshot:
      type: object
      properties:
        code:
          type: string
          description: Sanal para birimi kodu.
        name:
          type: string
          description: Sanal para biriminin görünen adı.
        balance:
          type: integer
          format: int32
          minimum: 0
          description: Şu anda beklemede tutulan miktarlar dahil toplam bakiye.
        held:
          type: integer
          format: int32
          minimum: 0
          description: Tüm aktif beklemelerin toplamı (rezerve edilmiş miktarlar). Şu anda her zaman 0'dır.
        available:
          type: integer
          format: int32
          description: Harcanabilir bakiye; `balance - held` olarak hesaplanır.
      required:
        - code
        - name
        - balance
        - held
        - available
  securitySchemes:
    apikeyAuth:
      type: apiKey
      name: Authorization
      in: header
      default: Api-Key {Your secret API key}
      description: |
        API istekleri, gizli API anahtarınız tarafından **Authorization** başlığı olarak
        `Api-Key {your_secret_api_key}` değeriyle doğrulanmalıdır; örneğin,
        `Api-Key secret_live_...`. Bu anahtarı Adapty Kontrol Paneli ->
        **Uygulama Ayarları** -> **Genel** sekmesi -> **API anahtarları** bölümünde bulabilirsiniz.
```