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

Создать транзакцию виртуальной валюты

Copy as Markdown

Начисляет или списывает одну или несколько виртуальных валют для профиля в рамках одной атомарной транзакции. Используйте положительное значение 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

Уникальный идентификатор созданной транзакции.

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
}

Необрабатываемая сущность. Тело запроса не прошло валидацию схемы — например, 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-код статуса

Внутренняя ошибка сервера