English 中文TürkçeРусскийFrançaisTiếng ViệtEspañol日本語
POST /api/v2/server-side-api/vc/transactions/

创建虚拟货币交易

Copy as Markdown

在单个原子事务中为用户画像充值或扣除一种或多种虚拟货币。使用正数 amount 表示充值（授予），负数 amount 表示扣除（消费）。所有条目一起应用——如果任何条目失败，则全部不应用。

每个货币代码在每次请求中只能出现一次。通过此端点进行的充值始终创建永不过期的余额。

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。

密钥的记忆时间最长为一小时，且范围限定为单个用户画像。超过该时间窗口后，使用相同密钥的请求将作为新事务应用——因此请使用该密钥安全地重试调用，而不是用于长期内的重复授予去重。

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 条目对应一条记录）。如需读取用户画像的完整余额列表，请使用 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
}

不可处理的实体。请求体未通过 schema 验证——例如，items 包含超过 20 个条目，或 metadata 的键或值违反了其约束条件。

Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

请求过多。超出了每个应用或全局速率限制（error_code 为 rate_limited）。默认限制为每个应用每分钟 600 次请求，全局每分钟 6000 次请求。

Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

内部服务器错误