POST /api/v2/server-side-api/vc/transactions/

仮想通貨トランザクションを作成する

1回のアトミックトランザクションで、プロファイルに対して1つ以上の仮想通貨をクレジットまたはデビットします。クレジット（付与）する場合は正の amount を、デビット（消費）する場合は負の amount を使用してください。すべての項目は一括で適用されます — いずれかの項目が失敗した場合、何も適用されません。

通貨コードはリクエストごとに1回のみ使用できます。このエンドポイントを通じたクレジットは、常に有効期限なしの残高を作成します。

Header parameters

adapty-customer-user-idstring

お客様のシステムにおける顧客の一意のID。adapty-customer-user-id または adapty-profile-id のいずれかが必須です。

adapty-profile-idstring

お客様のシステムにおけるプロファイルの一意のID。匿名プロファイルを扱う場合に最適な選択肢です。adapty-customer-user-id または adapty-profile-id のいずれかが必須です。

Idempotency-Keystring · uuid

リクエストを冪等にするUUID v4。同じキーでリクエストを再試行した場合、Adaptyは残高を再度変更することなく元のトランザクションの結果を返します。有効なUUID v4である必要があります。

キーは最大1時間、単一プロファイルのスコープで記憶されます。その期間を過ぎると、同じキーでのリクエストは新しいトランザクションとして適用されます — つまり、このキーは長期的な付与の重複排除ではなく、安全にコールを再試行するために使用してください。

Request body

バーチャル通貨トランザクションを作成するためのリクエストボディ。

itemsarray of objectrequired

アトミックに適用する残高調整。各通貨コードは一度のみ指定できます。

currency_codestringrequired

調整するバーチャル通貨コード。

amountintegerrequired

適用する金額。正の値は通貨を付与（クレジット）し、負の値は通貨を消費（デビット）します。ゼロは指定できません。

metadataobject

トランザクションとともに保存されるオプションのキーと値のペア。最大5つのキーを指定できます。各キーは ^[a-z0-9_]{1,30}$ に一致し、各値は最大200文字です。

Responses

トランザクションが正常に適用されました

Schema

バーチャル通貨トランザクションの結果。

transaction_idstringrequired

作成されたトランザクションの一意のID。

balancesarray of objectrequired

このリクエストによって影響を受けた各通貨のトランザクション後の残高（items の各アイテムにつき1エントリ）。プロファイルの残高一覧全体を取得するには、GET /api/v2/server-side-api/vc/balances/ を使用してください。

codestringrequired

仮想通貨コード。

namestringrequired

仮想通貨の表示名。

balanceintegerrequired

現在保留中の金額を含む合計残高。

heldintegerrequired

すべてのアクティブな保留（予約済み金額）の合計。現在は常に 0。

availableintegerrequired

使用可能な残高。balance - held として計算されます。

Example

{
  "transaction_id": "0190e8a4-1c2b-7def-8abc-2c1a4b6d8e90",
  "balances": [
    {
      "code": "COINS",
      "name": "Gold Coins",
      "balance": 12950,
      "held": 0,
      "available": 12950
    }
  ]
}

不正なリクエスト。error_code フィールドが原因を示します: insufficient_balance、unknown_currency、duplicate_currency、amount_zero、balance_overflow、empty_items、または idempotency_key_invalid。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

Example

{
  "errors": [
    {
      "source": "currency_code",
      "errors": [
        "Insufficient balance for currency COINS"
      ]
    }
  ],
  "error_code": "insufficient_balance",
  "status_code": 400
}

認証エラー。APIキーが見つからないか無効です。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

禁止。このアプリでは仮想通貨のServer APIが有効になっていません。アクセスをリクエストするにはAdaptyサポートにお問い合わせください。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

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
}

プロファイルが見つかりません。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

競合。error_code フィールドが原因を示します:

idempotency_in_flight — 同じ Idempotency-Key を持つリクエストがまだ処理中です。Retry-After レスポンスヘッダーの間隔後に再試行してください。
duplicate_source_transaction — 基となるストアトランザクションはすでにクレジット済みのため、再度適用されません。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

Example

{
  "errors": [
    {
      "source": null,
      "errors": [
        "A similar request is being processed."
      ]
    }
  ],
  "error_code": "idempotency_in_flight",
  "status_code": 409
}

処理不可能なエンティティ。リクエストボディがスキーマバリデーションに失敗しました — たとえば、items に20件を超えるエントリが含まれているか、metadata のキーまたは値が制約に違反している場合などです。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

リクエスト過多。アプリごとまたはグローバルのレート制限を超えました（error_code は rate_limited）。デフォルトの制限は、アプリごとに1分あたり600リクエスト、グローバルで1分あたり6000リクエストです。

Schema

errorsarray of objectrequired

sourcestring

エラーの発生源

errorsarray of string

エラーメッセージの配列

error_codestringrequired

エラーの短い名称

status_codeintegerrequired

HTTPステータスコード

内部サーバーエラー

Try it

Authorization

Header parameters

adapty-customer-user-id

adapty-profile-id

Idempotency-Key

Body

curl --request POST \
  --url 'https://api.adapty.io/api/v2/server-side-api/vc/transactions/' \
  --header 'Authorization: Api-Key YOUR_SECRET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "currency_code": "COINS",
        "amount": -10
      }
    ]
  }'

const response = await fetch('https://api.adapty.io/api/v2/server-side-api/vc/transactions/', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key YOUR_SECRET_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "items": [
      {
        "currency_code": "COINS",
        "amount": -10
      }
    ]
  }),
});
const data = await response.json();

import requests

response = requests.post('https://api.adapty.io/api/v2/server-side-api/vc/transactions/', headers={
    'Authorization': 'Api-Key YOUR_SECRET_API_KEY',
    'Content-Type': 'application/json',
}, json={
      "items": [
        {
          "currency_code": "COINS",
          "amount": -10
        }
      ]
    })
data = response.json()