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

Tạo giao dịch tiền tệ ảo

Ghi có hoặc ghi nợ một hoặc nhiều loại tiền tệ ảo cho một hồ sơ người dùng trong một giao dịch nguyên tử duy nhất. Sử dụng amount dương để ghi có (cấp) và amount âm để ghi nợ (tiêu). Tất cả các mục được áp dụng cùng nhau — nếu bất kỳ mục nào thất bại, không có mục nào được áp dụng.

Mỗi mã tiền tệ chỉ được xuất hiện một lần trong mỗi yêu cầu. Việc ghi có thông qua endpoint này luôn tạo ra số dư không hết hạn.

Header parameters

adapty-customer-user-idstring

ID duy nhất của khách hàng trong hệ thống của bạn. Cần có adapty-customer-user-id hoặc adapty-profile-id.

adapty-profile-idstring

ID duy nhất của hồ sơ người dùng trong hệ thống của bạn. Lựa chọn tốt nhất nếu bạn đang làm việc với các hồ sơ ẩn danh. Cần có adapty-customer-user-id hoặc adapty-profile-id.

Idempotency-Keystring · uuid

Một UUID v4 giúp yêu cầu trở nên idempotent. Nếu bạn thử lại yêu cầu với cùng một key, Adapty sẽ trả về kết quả của giao dịch gốc mà không thay đổi số dư lần nữa. Phải là UUID v4 hợp lệ.

Các key được ghi nhớ trong tối đa một giờ, giới hạn trong phạm vi một hồ sơ người dùng duy nhất. Sau khoảng thời gian đó, yêu cầu với cùng key sẽ được áp dụng như một giao dịch mới — vì vậy hãy sử dụng key để thử lại lệnh gọi một cách an toàn, không phải để loại trừ trùng lặp việc cấp phép trong dài hạn.

Request body

Nội dung yêu cầu để tạo giao dịch tiền tệ ảo.

itemsarray of objectrequired

Các điều chỉnh số dư được áp dụng theo kiểu nguyên tử. Mỗi mã tiền tệ chỉ được xuất hiện một lần.

currency_codestringrequired

Mã tiền tệ ảo cần điều chỉnh.

amountintegerrequired

Số lượng cần áp dụng. Giá trị dương sẽ cộng thêm (cấp) tiền tệ; giá trị âm sẽ trừ đi (tiêu dùng) tiền tệ. Không được bằng không.

metadataobject

Các cặp khóa-giá trị tùy chọn được lưu cùng với giao dịch. Tối đa 5 khóa. Mỗi khóa phải khớp với ^[a-z0-9_]{1,30}$, và mỗi giá trị có độ dài tối đa 200 ký tự.

Responses

Giao dịch được áp dụng thành công

Schema

Kết quả của một giao dịch tiền tệ ảo.

transaction_idstringrequired

ID duy nhất của giao dịch đã được tạo.

balancesarray of objectrequired

Số dư sau giao dịch cho mỗi loại tiền tệ bị ảnh hưởng bởi yêu cầu này (một mục cho mỗi phần tử trong items). Để đọc toàn bộ danh sách số dư của hồ sơ người dùng, hãy sử dụng GET /api/v2/server-side-api/vc/balances/.

codestringrequired

Mã tiền tệ ảo.

namestringrequired

Tên hiển thị của tiền tệ ảo.

balanceintegerrequired

Tổng số dư, bao gồm các khoản đang được giữ.

heldintegerrequired

Tổng của tất cả các khoản giữ đang hoạt động (số tiền đã đặt trước). Hiện tại luôn là 0.

availableintegerrequired

Số dư có thể sử dụng, được tính bằng balance - held.

Example

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

Yêu cầu không hợp lệ. Trường error_code xác định nguyên nhân: insufficient_balance, unknown_currency, duplicate_currency, amount_zero, balance_overflow, empty_items, hoặc idempotency_key_invalid.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Example

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

Không được phép. API key bị thiếu hoặc không hợp lệ.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Bị từ chối. Server API cho tiền tệ ảo chưa được kích hoạt cho ứng dụng này. Liên hệ bộ phận hỗ trợ Adapty để yêu cầu quyền truy cập.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái 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
}

Không tìm thấy hồ sơ người dùng.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Xung đột. Trường error_code xác định nguyên nhân:

idempotency_in_flight — một yêu cầu với cùng Idempotency-Key vẫn đang được xử lý. Thử lại sau khoảng thời gian trong response header Retry-After.
duplicate_source_transaction — giao dịch của cửa hàng cơ bản đã được ghi có, do đó không được áp dụng lại.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Example

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

Thực thể không thể xử lý. Nội dung yêu cầu không vượt qua xác thực schema — ví dụ: items chứa hơn 20 mục, hoặc một key hay giá trị trong metadata vi phạm các ràng buộc của nó.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Quá nhiều yêu cầu. Đã vượt quá giới hạn tốc độ trên mỗi ứng dụng hoặc giới hạn toàn cục (error_code là rate_limited). Giới hạn mặc định là 600 yêu cầu mỗi phút cho mỗi ứng dụng và 6000 yêu cầu mỗi phút trên toàn cục.

Schema

errorsarray of objectrequired

sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Lỗi máy chủ nội bộ

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()