コンテンツへスキップ
/
ゲームを取得（管理者）

カタログAPI (2.0.0)

Overview

  • Version: 2.0.0
  • Servers: https://store.xsolla.com/api
  • Contact Us by Email
  • Contact URL: https://xsolla.com/
  • Required TLS version: 1.2

The Catalog API allows you to configure a catalog of in-game items on the Xsolla side and display the catalog to users in your store.

The API allows you to manage the following catalog entities:

  • Virtual items — in-game items such as weapons, skins, boosters.
  • Virtual currency — virtual money used to purchase virtual goods.
  • Virtual currency packages — predefined bundles of virtual currency.
  • Bundles — combined packages of virtual items, currency, or game keys sold as a single SKU.
  • Game keys — keys for games and DLCs distributed via platforms like Steam or other DRM providers.
  • Groups — logical groupings for organizing and sorting items within the catalog.

API calls

The API is divided into the following groups:

  • Admin — calls for creating, updating, deleting, and configuring catalog items and groups. Authenticated via basic access authentication with your merchant or project credentials. Not intended for storefront use.
  • Catalog — calls for retrieving items and building custom storefronts for end users. Designed to handle high-load scenarios. Support optional user JWT authorization to return personalized data such as user-specific limits and active promotions.

Authentication

API calls require authentication either on behalf of a user or on behalf of a project. The authentication scheme used is specified in the Security section in the description of each call.

Authentication using user's JWT

User's JWT authentication is used when a request is sent from a browser, mobile application, or game. By default, the XsollaLoginUserJWT scheme is applied. For details on how to create a token, see the Xsolla Login API documentation.

The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data.

別の方法として、決済UIを開くためのトークンを使用することも可能です。

Basic HTTP authentication

Basic HTTP authentication is used for server-to-server interactions, when an API call is sent directly from your server rather than from a user's browser or mobile application. HTTP Basic authentication with an API key is typically used.

Note

The API key is confidential and must not be stored or used in client applications.

With basic server-side authentication, all API requests must include the following header:

  • for basicAuth — Authorization: Basic <your_authorization_basic_key>, where your_authorization_basic_key is the project_id:api_key pair encoded in Base64
  • for basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>, where your_authorization_basic_key is the merchant_id:api_key pair encoded in Base64

You can find the parameter values in Publisher Account:

  • merchant_id is displayed:
    • In Company settings > Company.
    • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/<merchant_id>.
  • project_id is displayed:
    • Next to the project name in Publisher Account.
    • In the URL in the browser address bar when working on a project in Publisher Account. The URL has the following format: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
  • api_key is shown in Publisher Account only at the time of creation and must be stored securely on your side. You can create an API key in the following sections:
Notice

If a required API call doesn't include the project_id path parameter, use an API key that is valid across all company projects for authorization.

For more information about working with API keys, see the API references.

Authentication with guest access support

AuthForCart認証スキームはカートでの購入用であり、以下の2つのモードに対応しています：

  1. Authentication with a user's JWT. The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data. Alternatively, you can use a token for opening the payment UI.

  2. Simplified mode without Authorization header. This mode is used only for unauthorized users and can be applied only for game key sales. Instead of a token, the request must include the following headers:

    • x-unauthorized-id with a request ID
    • x-user with the user's email address encoded in Base64

Core entity structure

Items of all types (virtual items, bundles, virtual currency, and keys) use a similar data structure. Understanding the basic structure simplifies working with the API and helps you navigate the documentation more easily.

Note

Some calls may include additional fields but they don't change the basic structure.

Identification

  • merchant_id — company ID in Publisher Account
  • project_id — project ID in Publisher Account
  • sku — item SKU, unique within the project

Store display

  • name — item name
  • description — item description
  • image_url — image URL
  • is_enabled — item availability
  • is_show_in_store — whether the item is displayed in the catalog

For more information about managing item availability in the catalog, see the documentation.

Organization

  • type — item type, for example, a virtual item (virtual_item) or bundle (bundle)
  • groups — groups the item belongs to
  • order — display order in the catalog

Sale conditions

  • prices — prices in real or virtual currency
  • limits — purchase limits
  • periods — availability periods
  • regions — regional restrictions

Example of core entity structure:

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

Basic purchase flow

The Xsolla API allows you to implement in-game store logic, including retrieving the item catalog, managing the cart, creating orders, and tracking their status. Depending on the integration scenario, API calls are divided into Admin and Catalog subsections, which use different authentication schemes.

The following example shows a basic flow for setting up and operating a store, from item creation to purchase.

Create items and groups (Admin)

Create an item catalog for your store, such as virtual items, bundles, or virtual currency.

Example API calls:

Set up promotions, chains, and limits (Admin)

Configure user acquisition and monetization tools, such as discounts, bonuses, daily rewards, or offer chains.

Example API calls:

Get item information (Client)

Configure item display in your application.

Notice

Do not use API calls from the Admin subsection to build a user catalog. These API calls have rate limits and aren't intended for user traffic.

Example API calls:

Note

By default, catalog API calls return items that are currently available in the store at the time of the request. To retrieve items that are not yet available or are no longer available, include the parameter "show_inactive_time_limited_items": 1 in the catalog request.

Sell items

You can sell items using the following methods:

  • Fast purchase — sell one SKU multiple times.
  • Cart purchase — the user adds items to the cart, removes items, and updates quantities within a single order.

If an item is purchased using virtual currency instead of real money, use the Create order with specified item purchased by virtual currency API call. The payment UI is not required, as the charge is processed when the API call is executed.

For free item purchase, use the Create order with specified free item API call or the Create order with free cart API call. The payment UI is not required — the order is immediately set to the done status.

Fast purchase

Use the client-side API call to create an order with a specified item. The call returns a token used to open the payment UI.

Note

Discount information is available to the user only in the payment UI. Promo codes are not supported.

Cart purchase

Cart setup and purchase can be performed on the client or on the server side.

Set up and purchase a cart on the client

Implement the logic of adding and removing items by yourself. Before calling the API for setting up a cart, you will not have information about which promotions will be applied to the purchase. This means that the total cost and details of the added bonus items will not be known.

Implement the following cart logic:

  1. After the player has filled a cart, use the Fill cart with items API call. The call returns the current information about the selected items (prices before and after discounts, bonus items).
  2. Update the cart contents based on user actions:
Note

To get the current status of the cart, use the Get current user's cart API call.
  1. Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to new status by default.

Set up and purchase a cart on the server

This setup option may take longer for setting the cart up, since each change to the cart must be accompanied by API calls.

Implement the following cart logic:

  1. After the player has filled a cart, use the Fill cart with items API call. The call returns current information about the selected items (prices before and after discounts, bonus items).
  2. Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to new status by default.

Open payment UI

Use the returned token to open the payment UI in a new window. Other ways to open the payment UI are described in the documentation.

ActionEndpoint
Open in production environment.https://secure.xsolla.com/paystation4/?token={token}
Open in sandbox mode.https://sandbox-secure.xsolla.com/paystation4/?token={token}
Note

Use sandbox mode during development and testing. Test purchases don't charge real accounts. You can use test bank cards.

After the first real payment is made, a strict sandbox payment policy takes effect. A payment in sandbox mode is available only to users specified in Publisher Account > Company settings > Users.

Buying virtual currency and items for real currency is possible only after signing a license agreement with Xsolla. To do this, in Publisher Account, go to Agreements & Taxes > Agreements, complete the agreement form, and wait for confirmation. It may take up to 3 business days to review the agreement.

To enable or disable sandbox mode, change the value of the sandbox parameter in the request for fast purchase and cart purchase. Sandbox mode is off by default.

Possible order statuses:

  • new — order created
  • paid — payment received
  • done — item delivered
  • canceled — order canceled
  • expired — order expired

Track order status using one of the following methods:

Pagination

API calls that return large sets of records (for example, when building a catalog) return data in pages. Pagination is a mechanism that limits the number of items returned in a single API response and allows you to retrieve subsequent pages sequentially.

Use the following parameters to control the number of returned items:

  • limit — number of items per page
  • offset — index of the first item on the page (numbering starts from 0)
  • has_more — indicates whether another page is available
  • total_items_count — total number of items

Example request:

GET /items?limit=20&offset=40

Response example:

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

It is recommended to send subsequent requests until the response returns has_more = false.

Date and time format

Dates and time values are passed in the ISO 8601 format.

The following are supported:

  • UTC offset
  • null value when there is no time restriction for displaying an item
  • Unix timestamp (in seconds) used in some fields

Format: YYYY-MM-DDTHH:MM:SS±HH:MM

Example: 2026-03-16T10:00:00+03:00

Localization

Xsolla supports localization of user-facing fields such as item name and description. Localized values are passed as an object where the language code is used as the key. The full list of supported languages is available in the documentation.

Supported fields

Localization can be specified for the following parameters:

  • name
  • description
  • long_description

Locale format

The locale key can be specified in one of the following formats:

  • Two-letter language code: en, ru
  • Five-letter language code: en-US, ru-RU, de-DE

Examples

Example with a two-letter language code:

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

Example with a five-letter language code:

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

Country and currency determination

The user's country determines catalog prices, the payment currency, and available payment methods in the payment UI. Depending on the API call, the country is determined as follows:

  • In client-side API calls, the country is determined by the IP address of the request.
  • In server-side API calls, the country is determined by the value of the user.country.value parameter or by the user's IP address from the X-User-Ip header. If both are passed, the user.country.value parameter takes precedence.
Note

Only IPv4 addresses are supported for country determination. Passing an IPv6 address may result in incorrect country and currency detection. If you use the server-side API call and cannot provide the user's IPv4 address, pass the country in the user.country.value parameter.

Error response format

If an error occurs, the API returns an HTTP status and a JSON response body. The full list of store-related errors is available in the documentation.

Response example:

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode — error code.
  • errorMessage — short error description.
  • statusCode — HTTP response status.
  • transactionId — request ID. Returned only in some cases.
  • errorMessageExtended — additional error details, such as request parameters. Returned only in some cases.

Extended response example:

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

Common HTTP status codes

  • 400 — invalid request
  • 401 — authentication error
  • 403 — insufficient permissions
  • 404 — resource not found
  • 422 — validation error
  • 429 — rate limit exceeded

Recommendations

  • Handle the HTTP status and the response body together.
  • Use errorCode to process errors related to application logic.
  • Use transactionId to identify requests more quickly when analyzing errors.
OpenAPI記述をダウンロード
index.json
index.yaml
言語
サーバー
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ja/api/catalog/

概要

仮想アイテムと仮想通貨を使用してインゲームストアを構築し、ユーザーへの表示方法を設定できます。以下のアイテムタイプが利用可能です：

  • 仮想アイテム — 武器、スキン、ブースターなどのゲーム内アイテム。実際のお金または仮想通貨で販売できます。
  • 仮想通貨 — 仮想アイテムの購入に使用されるゲーム内通貨。実際のお金または仮想通貨で販売できます。
  • 仮想通貨パッケージ — 仮想通貨の固定数量パック。実際のお金または仮想通貨で販売できます。

グループは、カタログ内のアイテムを整理するために使用されます。アイテムを論理的にグループ化し、表示方法を管理することができます。

管理者サブセクションのAPIコールを使用して、アイテムの作成、更新、削除を行います。

カタログサブセクションのAPIコールを使用して、アイテムのリストを取得し、ユーザーに表示します。

注意

管理者サブセクションのAPIコールを使用してストアカタログを構築しないでください。

注意

仮想アイテムリストを取得するAPIコールは、価格や属性を含む詳細なアイテムデータを返し、ページネーションをサポートします。ストアフロントでカタログページを表示するために使用してください。

すべての仮想アイテムリストを取得するAPIコールは、ページネーションなしでアイテムSKU、名前、説明、グループIDと名前を返します。クライアント側の検索やインデックス作成に使用してください。

仮想通貨で購入する場合、仮想通貨で購入された指定アイテムで注文を作成するAPIコールを使用してください。当該APIコールの実行時に課金処理が行われるため、決済UIを表示する必要はありません。

仮想通貨での購入フローの例：

仮想通貨での購入フローの例：

管理者

操作

カタログ

操作

仮想決済

操作

概要

ゲームキーは、ユーザーがゲームプラットフォーム上でゲームやDLCにアクセスできるようにするための、使い切りのユニークな半角英数字コードです。ゲームキーは、ダイレクトリンク、ストアUI、またはウィジェットを介して販売することができます。また、特定の国でゲームキーを販売するために、地域別制限を設定することも可能です。詳細については、ゲームキーパッケージセクションを参照してください。

ゲームキーを販売する際、ユーザー認証は必須ではありません。キーは、ユーザーがチェックアウト時に指定したメールアドレス宛に送信されます。また、認証を設定することで、個人用設定、購入制限、エンタイトルメントシステムといった追加のシナリオを有効にすることも可能です。詳細については、ゲームキー販売時の認証設定方法セクションを参照してください。

ゲームキーの販売フロー：

  1. ゲームを作成するAPIコールを使用して、ゲームを作成します。
  2. 地域制限を設定します。
  3. コードをアップロードするAPIコールを使用してゲームキーパッケージにキーをアップロードし、購入可能な状態にします。
  4. ゲームリストを取得するAPIコールを使用して、ユーザーの地域に応じた価格とともにゲームカタログを表示します。
  5. 注文を作成します。素早く購入できるようにするには、ゲームキーのSKUを渡し、現在のカート内の全アイテムを含む注文を作成するAPIコールを使用できます。レスポンスとして、決済UIを開くためのトークンが返されます。
  6. 注文の支払いを行うために、決済UIを開く処理を実装します。

決済完了の通知をタイムリーに受け取り、ユーザーにアイテムを付与するには、たとえば、ウェブフックを使用して注文ステータスのトラッキングを設定してください。キーは、ユーザーがチェックアウト時に指定したメールアドレス宛に送信され、注文ステータスはdoneに移行します。

ゲームキー

カタログ

操作

資格

操作

管理者

操作

ゲームリストを取得（管理者）Server-sideAdmin

リクエスト

管理用プロジェクト内のゲームのリストを取得します。 ゲームは、ユーザーが購入可能なゲームキーで構成されています。

注

このエンドポイントは、ストアカタログの構築に使用しないでください。
セキュリティ
basicAuth
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
クエリ
limitinteger>= 1

ページでの要素数の制限。

例: limit=50
offsetinteger>= 0

リストが生成される要素番号（カウントは0から始まります）。

例: offset=0
promo_codestring[ 1 .. 128 ] characters

大文字と小文字を区別する一意のコードです。文字と数字が含まれます。

例: promo_code=WINTER2021
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/game?limit=50&offset=0&promo_code=WINTER2021'

レスポンス

ゲームのリストは正常に受信されました。

ボディapplication/json
itemsArray of objects
items[].​item_idinteger

アイテム作成時に付与される内部一意のアイテムID。

例: 1
items[].​skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "game_1"
items[].​typestring

アイテムタイプ。 この場合、それは常にunitです。

例: "unit"
items[].​name(object or null)

アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

items[].​name.​enstring or null

英語

items[].​name.​arstring or null

アラビア語

items[].​name.​bgstring or null

ブルガリア語

items[].​name.​cnstring or null

中国語（簡体字）

items[].​name.​csstring or null

チェコ語

items[].​name.​destring or null

ドイツ語

items[].​name.​esstring or null

スペイン語（スペイン）

items[].​name.​frstring or null

フランス語

items[].​name.​hestring or null

ヘブライ語

items[].​name.​itstring or null

イタリア語

items[].​name.​jastring or null

日本語

items[].​name.​kostring or null

韓国語

items[].​name.​plstring or null

ポーランド語

items[].​name.​ptstring or null

ポルトガル語

items[].​name.​rostring or null

ルーマニア語

items[].​name.​rustring or null

ロシア語

items[].​name.​thstring or null

タイ語

items[].​name.​trstring or null

トルコ語

items[].​name.​twstring or null

中国語（繁体字）

items[].​name.​vistring or null

ベトナム語

items[].​name.​kmstring or null

クメール語

items[].​name.​idstring or null

インドネシア語

items[].​name.​lostring or null

ラオス語

items[].​name.​mystring or null

ビルマ語

items[].​name.​phstring or null

フィリピン語

items[].​name.​nestring or null

ネパール語

items[].​description(object or null)

アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

items[].​description.​enstring or null

英語

items[].​description.​arstring or null

アラビア語

items[].​description.​bgstring or null

ブルガリア語

items[].​description.​cnstring or null

中国語（簡体字）

items[].​description.​csstring or null

チェコ語

items[].​description.​destring or null

ドイツ語

items[].​description.​esstring or null

スペイン語（スペイン）

items[].​description.​frstring or null

フランス語

items[].​description.​hestring or null

ヘブライ語

items[].​description.​itstring or null

イタリア語

items[].​description.​jastring or null

日本語

items[].​description.​kostring or null

韓国語

items[].​description.​plstring or null

ポーランド語

items[].​description.​ptstring or null

ポルトガル語

items[].​description.​rostring or null

ルーマニア語

items[].​description.​rustring or null

ロシア語

items[].​description.​thstring or null

タイ語

items[].​description.​trstring or null

トルコ語

items[].​description.​twstring or null

中国語（繁体字）

items[].​description.​vistring or null

ベトナム語

items[].​description.​kmstring or null

クメール語

items[].​description.​idstring or null

インドネシア語

items[].​description.​lostring or null

ラオス語

items[].​description.​mystring or null

ビルマ語

items[].​description.​phstring or null

フィリピン語

items[].​description.​nestring or null

ネパール語

items[].​long_description(object or null)

アイテムの長文説明のローカライズを含むオブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のバリアント（例：enとen-US）が提供された場合、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

items[].​long_description.​enstring or null

英語

items[].​long_description.​arstring or null

アラビア語

items[].​long_description.​bgstring or null

ブルガリア語

items[].​long_description.​cnstring or null

中国語（簡体字）

items[].​long_description.​csstring or null

チェコ語

items[].​long_description.​destring or null

ドイツ語

items[].​long_description.​esstring or null

スペイン語（スペイン）

items[].​long_description.​frstring or null

フランス語

items[].​long_description.​hestring or null

ヘブライ語

items[].​long_description.​itstring or null

イタリア語

items[].​long_description.​jastring or null

日本語

items[].​long_description.​kostring or null

韓国語

items[].​long_description.​plstring or null

ポーランド語

items[].​long_description.​ptstring or null

ポルトガル語

items[].​long_description.​rostring or null

ルーマニア語

items[].​long_description.​rustring or null

ロシア語

items[].​long_description.​thstring or null

タイ語

items[].​long_description.​trstring or null

トルコ語

items[].​long_description.​twstring or null

中国語（繁体字）

items[].​long_description.​vistring or null

ベトナム語

items[].​long_description.​kmstring or null

クメール語

items[].​long_description.​idstring or null

インドネシア語

items[].​long_description.​lostring or null

ラオス語

items[].​long_description.​mystring or null

ビルマ語

items[].​long_description.​phstring or null

フィリピン語

items[].​long_description.​nestring or null

ネパール語

items[].​image_urlstring

画像URL。

例: "https://image.example.com"
items[].​media_listArray of objects

スクリーンショット、ゲームプレイ動画などのゲーム追加アセット。

例: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
items[].​media_list[].​typestring

メディアタイプ：image/video。

Enum"image""video"
例: "image"
items[].​media_list[].​urlstring

リソースファイル。

例: "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"
items[].​is_enabledboolean

無効の場合、アイテムの購入やインベントリからのアクセスはできません。

items[].​is_show_in_storeboolean

アイテムは購入可能です。

items[].​orderinteger

リスト内のゲーム順の優先順位。

例: 1
items[].​groupsArray of objects

アイテムが所属するグループ。

例: [{"external_id":"horror","name":{"en":"Horror"}}]
items[].​groups[].​external_idstring
例: "horror"
items[].​groups[].​nameobject
例: {"en":"Horror"}
items[].​attributesArray of objects

属性リスト。

例: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$必須

一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。

例: "attribute_external_id"
items[].​attributes[].​nameobject

属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

例: {"en":"Attribute name","de":"Attributname"}
items[].​attributes[].​name.​property name*string追加プロパティ
items[].​attributes[].​valuesArray of objects必須
例: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$必須

属性の一意の値ID。external_idには、半角小文字の英数字、ハイフン、アンダースコアのみを含めることができます。

例: "value_external_id"
items[].​attributes[].​values[].​valueobject必須

値名がローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

items[].​attributes[].​values[].​value.​property name*string追加プロパティ
items[].​is_freeboolean

アイテムが無料かどうか。

items[].​unit_itemsArray of objects

異なるDRMに対応したゲームキー。

items[].​unit_items[].​item_idinteger

アイテム作成時に付与される内部一意のアイテムID。

例: 1
items[].​unit_items[].​skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "game_1"
items[].​unit_items[].​typestring

アイテムタイプ。 この場合、それは常にgame_keyです。

例: "game_key"
items[].​unit_items[].​is_freeboolean

アイテムが無料かどうか。

items[].​unit_items[].​pricesArray of objects

実際通貨建ての価格。

例: [{"amount":1299.99,"currency":"RUB","is_default":true,"is_enabled":true}]
items[].​unit_items[].​prices[].​amountnumber
例: 1299.99
items[].​unit_items[].​prices[].​currencystring

商品価格通貨。ISO 4217 による3文字コード。

例: "RUB"
items[].​unit_items[].​prices[].​is_defaultboolean

ユーザーの通貨での価格が指定されていない場合、デフォルトの価格がカタログ作成に使用されます。

items[].​unit_items[].​prices[].​is_enabledboolean
items[].​unit_items[].​prices[].​country_isostring or null

この価格が利用可能な国。ISO 3166-1 alpha 2に基づく2文字コード。

例: "US"
items[].​unit_items[].​virtual_pricesArray of objects or null
例: [{"sku":"com.xsolla.gold_1","name":{"en":"Gold"},"type":"virtual_currency","description":null,"image_url":"https://i.pinimg.com/originals/91/ae/56/91ae5683045f6dbef16b1482bade938f.png","amount":1000,"is_default":true}]
items[].​unit_items[].​virtual_prices[].​skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "gold"
items[].​unit_items[].​virtual_prices[].​nameobject

仮想通貨用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

例: {"en":"Gold"}
items[].​unit_items[].​virtual_prices[].​name.​property name*any追加プロパティ
items[].​unit_items[].​virtual_prices[].​typestring

アイテムタイプ。 この場合、それは常にvirtual_currencyです。

例: "virtual_currency"
items[].​unit_items[].​virtual_prices[].​descriptionobject or null

ゲーム説明用のローカライズを含むオブジェクト。ゲームキーは「ISO 3166-1」で指定されています。

例: {"en":"Game 1 Example"}
items[].​unit_items[].​virtual_prices[].​description.​property name*any追加プロパティ
items[].​unit_items[].​virtual_prices[].​image_urlstring

画像URL。

例: "https://image.example.com"
items[].​unit_items[].​virtual_prices[].​amountnumber
items[].​unit_items[].​virtual_prices[].​is_defaultboolean
items[].​unit_items[].​orderinteger

リスト内のゲーム順の優先順位。

例: 1
items[].​unit_items[].​is_enabledboolean

無効の場合、アイテムの購入やインベントリからのアクセスはできません。

items[].​unit_items[].​is_show_in_storeboolean

アイテムは購入可能です。

items[].​unit_items[].​drm_namestring

ゲームキーDRMの名称。

例: "Steam"
items[].​unit_items[].​drm_skustring

DRMユニークID。

例: "steam"
items[].​unit_items[].​drm_imagestring or null

ゲームキーDRMのアイコン。

例: "https://upload.wikimedia.org/wikipedia/en/4/48/Steam_Icon_2014.png"
items[].​unit_items[].​drm_idinteger

DRM内部の一意のID。

例: 1
items[].​unit_items[].​keysobject
items[].​unit_items[].​keys.​availableinteger

購入可能なキーの数。

items[].​unit_items[].​keys.​totalinteger

アップロードされたキーの合計数。

items[].​unit_items[].​keys.​usedinteger

販売されたキーの数。

items[].​unit_items[].​is_sales_existboolean

trueの場合、ユーザーがゲームキーを購入しました。

items[].​unit_items[].​pre_orderobject

先行予約の設定。

items[].​unit_items[].​pre_order.​release_datestring or null

ISO 8601形式でのゲームキーのリリース日。

items[].​unit_items[].​pre_order.​is_enabledboolean

無効の場合、アイテムは先行予約ではありません。

items[].​unit_items[].​pre_order.​descriptionstring or null

予約注文に関する追加情報は電子メールで送信されます。

items[].​unit_items[].​regionsArray of objects
items[].​unit_items[].​regions[].​idinteger
例: 1
items[].​unit_items[].​limitsobject or null

アイテム制限。

items[].​unit_items[].​limits.​per_userobject or null

別ユーザーのアイテム制限。

items[].​unit_items[].​limits.​per_user.​totalinteger

1ユーザーあたりのユーザーが購入できるアイテムの最大数。

items[].​unit_items[].​limits.​per_user.​limit_exceeded_visibilitystring

購入制限に達してから次回の制限リセットまでの間、カタログ内でのアイテムの表示・非表示を決定します。

これは、recurrent_schedule配列で定期的な制限リセットが設定されているアイテムに適用されます。

購入制限のリセットが設定されていない場合、購入制限に達した後は、limit_exceeded_visibilityの値に関わらず、そのアイテムはカタログに表示されなくなります。

指定可能な値：

  • show — 購入制限に達した後も、カタログ取得用のAPIコールに対してアイテム情報が返却されます。クライアントサイドのカタログ取得APIコールにおいては、制限に達した時点でアイテムにcan_be_bought: falseフラグが付与されて返されます。次回のリセット日時はreset_next_dateに格納されて返却されます。
  • hide — 購入制限に達した時点から、制限値がリセットされるまでの間、カタログ取得用のAPIコールにおいてアイテムは返されなくなります。
Enum"show""hide"
items[].​unit_items[].​limits.​per_itemobject or null

グローバルアイテム制限。

items[].​unit_items[].​limits.​per_item.​totalinteger

すべてのユーザーが購入できるアイテムの最大数。

items[].​unit_items[].​limits.​per_item.​availableinteger

すべてのユーザーが購入できるアイテムの残り数。

items[].​unit_items[].​limits.​per_item.​reservedinteger
items[].​unit_items[].​limits.​per_item.​soldinteger
items[].​unit_items[].​limits.​recurrent_scheduleobject or null

制限更新期間。

items[].​unit_items[].​limits.​recurrent_schedule.​per_userobject

ユーザー制限更新期間。

One of:

ユーザー制限の日次更新タイプ。

items[].​unit_items[].​limits.​recurrent_schedule.​per_user.​interval_typestring

定期更新期間のタイプ。

値"daily"
items[].​unit_items[].​limits.​recurrent_schedule.​per_user.​timestring(full-time)

希望するタイムゾーンでのリミットの更新時刻（時間単位への四捨五入）。

例: "11:00:00+03:00"
items[].​unit_items[].​limits.​recurrent_schedule.​per_user.​reset_next_dateinteger

制限が更新された日時（UNIXタイムスタンプ）。

例: 1677553200
items[].​unit_items[].​limits.​recurrent_schedule.​per_user.​displayable_reset_start_datestring(date-time)

最初の制限更新の日時（ISO 8601）。

例: "2023-02-28T11:00:00+08:00"
items[].​unit_items[].​limits.​recurrent_schedule.​per_user.​displayable_reset_next_datestring(date-time)

制限をリセットする日時（ISO 8601）。

例: "2023-02-28T11:00:00+08:00"
items[].​unit_items[].​periodsArray of objects

アイテム販売期間。

items[].​unit_items[].​periods[].​date_fromstring or null(date-time)

指定されたアイテムの販売開始日。

例: "2020-08-11T10:00:00+03:00"
items[].​unit_items[].​periods[].​date_untilstring or null(date-time)

指定されたアイテムが販売できなくなる日付。nullを指定することもできます。

例: "2020-08-11T20:00:00+03:00"
items[].​unit_items[].​name(object or null)

アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

items[].​unit_items[].​name.​enstring or null

英語

items[].​unit_items[].​name.​arstring or null

アラビア語

items[].​unit_items[].​name.​bgstring or null

ブルガリア語

items[].​unit_items[].​name.​cnstring or null

中国語（簡体字）

items[].​unit_items[].​name.​csstring or null

チェコ語

items[].​unit_items[].​name.​destring or null

ドイツ語

items[].​unit_items[].​name.​esstring or null

スペイン語（スペイン）

items[].​unit_items[].​name.​frstring or null

フランス語

items[].​unit_items[].​name.​hestring or null

ヘブライ語

items[].​unit_items[].​name.​itstring or null

イタリア語

items[].​unit_items[].​name.​jastring or null

日本語

items[].​unit_items[].​name.​kostring or null

韓国語

items[].​unit_items[].​name.​plstring or null

ポーランド語

items[].​unit_items[].​name.​ptstring or null

ポルトガル語

items[].​unit_items[].​name.​rostring or null

ルーマニア語

items[].​unit_items[].​name.​rustring or null

ロシア語

items[].​unit_items[].​name.​thstring or null

タイ語

items[].​unit_items[].​name.​trstring or null

トルコ語

items[].​unit_items[].​name.​twstring or null

中国語（繁体字）

items[].​unit_items[].​name.​vistring or null

ベトナム語

items[].​unit_items[].​name.​kmstring or null

クメール語

items[].​unit_items[].​name.​idstring or null

インドネシア語

items[].​unit_items[].​name.​lostring or null

ラオス語

items[].​unit_items[].​name.​mystring or null

ビルマ語

items[].​unit_items[].​name.​phstring or null

フィリピン語

items[].​unit_items[].​name.​nestring or null

ネパール語

items[].​unit_items[].​attributesArray of objects

属性リスト。

例: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
items[].​unit_items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$必須

一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。

例: "attribute_external_id"
items[].​unit_items[].​attributes[].​nameobject

属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

例: {"en":"Attribute name","de":"Attributname"}
items[].​unit_items[].​attributes[].​name.​property name*string追加プロパティ
items[].​unit_items[].​attributes[].​valuesArray of objects必須
例: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
items[].​unit_items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$必須

属性の一意の値ID。external_idには、半角小文字の英数字、ハイフン、アンダースコアのみを含めることができます。

例: "value_external_id"
items[].​unit_items[].​attributes[].​values[].​valueobject必須

値名がローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

items[].​unit_items[].​attributes[].​values[].​value.​property name*string追加プロパティ
items[].​unit_items[].​long_description(object or null)

アイテムの長文説明のローカライズを含むオブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のバリアント（例：enとen-US）が提供された場合、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

items[].​unit_items[].​long_description.​enstring or null

英語

items[].​unit_items[].​long_description.​arstring or null

アラビア語

items[].​unit_items[].​long_description.​bgstring or null

ブルガリア語

items[].​unit_items[].​long_description.​cnstring or null

中国語（簡体字）

items[].​unit_items[].​long_description.​csstring or null

チェコ語

items[].​unit_items[].​long_description.​destring or null

ドイツ語

items[].​unit_items[].​long_description.​esstring or null

スペイン語（スペイン）

items[].​unit_items[].​long_description.​frstring or null

フランス語

items[].​unit_items[].​long_description.​hestring or null

ヘブライ語

items[].​unit_items[].​long_description.​itstring or null

イタリア語

items[].​unit_items[].​long_description.​jastring or null

日本語

items[].​unit_items[].​long_description.​kostring or null

韓国語

items[].​unit_items[].​long_description.​plstring or null

ポーランド語

items[].​unit_items[].​long_description.​ptstring or null

ポルトガル語

items[].​unit_items[].​long_description.​rostring or null

ルーマニア語

items[].​unit_items[].​long_description.​rustring or null

ロシア語

items[].​unit_items[].​long_description.​thstring or null

タイ語

items[].​unit_items[].​long_description.​trstring or null

トルコ語

items[].​unit_items[].​long_description.​twstring or null

中国語（繁体字）

items[].​unit_items[].​long_description.​vistring or null

ベトナム語

items[].​unit_items[].​long_description.​kmstring or null

クメール語

items[].​unit_items[].​long_description.​idstring or null

インドネシア語

items[].​unit_items[].​long_description.​lostring or null

ラオス語

items[].​unit_items[].​long_description.​mystring or null

ビルマ語

items[].​unit_items[].​long_description.​phstring or null

フィリピン語

items[].​unit_items[].​long_description.​nestring or null

ネパール語

items[].​unit_items[].​groupsArray of objects

アイテムが所属するグループ。

例: [{"external_id":"horror","name":{"en":"Horror"}}]
items[].​unit_items[].​groups[].​external_idstring
例: "horror"
items[].​unit_items[].​groups[].​nameobject
例: {"en":"Horror"}
レスポンス
application/json
{
  "items": [
    { … },
    { … }
  ]
}

ゲームを取得（管理者）Server-sideAdmin

リクエスト

管理用ゲームを取得します。 ゲームは、ユーザーが購入可能なゲームキーで構成されています。

注

このエンドポイントは、ストアカタログの構築に使用しないでください。
セキュリティ
basicAuth
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
item_skustring必須

アイテムSKU。

例: booster_mega_1
クエリ
promo_codestring[ 1 .. 128 ] characters

大文字と小文字を区別する一意のコードです。文字と数字が含まれます。

例: promo_code=WINTER2021
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/game/sku/booster_mega_1?promo_code=WINTER2021'

レスポンス

ゲームは正常に受信されました。

ボディapplication/json
item_idinteger

アイテム作成時に付与される内部一意のアイテムID。

例: 1
skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "game_1"
typestring

アイテムタイプ。 この場合、それは常にunitです。

例: "unit"
name(object or null)

アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

name.​enstring or null

英語

name.​arstring or null

アラビア語

name.​bgstring or null

ブルガリア語

name.​cnstring or null

中国語（簡体字）

name.​csstring or null

チェコ語

name.​destring or null

ドイツ語

name.​esstring or null

スペイン語（スペイン）

name.​frstring or null

フランス語

name.​hestring or null

ヘブライ語

name.​itstring or null

イタリア語

name.​jastring or null

日本語

name.​kostring or null

韓国語

name.​plstring or null

ポーランド語

name.​ptstring or null

ポルトガル語

name.​rostring or null

ルーマニア語

name.​rustring or null

ロシア語

name.​thstring or null

タイ語

name.​trstring or null

トルコ語

name.​twstring or null

中国語（繁体字）

name.​vistring or null

ベトナム語

name.​kmstring or null

クメール語

name.​idstring or null

インドネシア語

name.​lostring or null

ラオス語

name.​mystring or null

ビルマ語

name.​phstring or null

フィリピン語

name.​nestring or null

ネパール語

description(object or null)

アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

description.​enstring or null

英語

description.​arstring or null

アラビア語

description.​bgstring or null

ブルガリア語

description.​cnstring or null

中国語（簡体字）

description.​csstring or null

チェコ語

description.​destring or null

ドイツ語

description.​esstring or null

スペイン語（スペイン）

description.​frstring or null

フランス語

description.​hestring or null

ヘブライ語

description.​itstring or null

イタリア語

description.​jastring or null

日本語

description.​kostring or null

韓国語

description.​plstring or null

ポーランド語

description.​ptstring or null

ポルトガル語

description.​rostring or null

ルーマニア語

description.​rustring or null

ロシア語

description.​thstring or null

タイ語

description.​trstring or null

トルコ語

description.​twstring or null

中国語（繁体字）

description.​vistring or null

ベトナム語

description.​kmstring or null

クメール語

description.​idstring or null

インドネシア語

description.​lostring or null

ラオス語

description.​mystring or null

ビルマ語

description.​phstring or null

フィリピン語

description.​nestring or null

ネパール語

long_description(object or null)

アイテムの長文説明のローカライズを含むオブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のバリアント（例：enとen-US）が提供された場合、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

long_description.​enstring or null

英語

long_description.​arstring or null

アラビア語

long_description.​bgstring or null

ブルガリア語

long_description.​cnstring or null

中国語（簡体字）

long_description.​csstring or null

チェコ語

long_description.​destring or null

ドイツ語

long_description.​esstring or null

スペイン語（スペイン）

long_description.​frstring or null

フランス語

long_description.​hestring or null

ヘブライ語

long_description.​itstring or null

イタリア語

long_description.​jastring or null

日本語

long_description.​kostring or null

韓国語

long_description.​plstring or null

ポーランド語

long_description.​ptstring or null

ポルトガル語

long_description.​rostring or null

ルーマニア語

long_description.​rustring or null

ロシア語

long_description.​thstring or null

タイ語

long_description.​trstring or null

トルコ語

long_description.​twstring or null

中国語（繁体字）

long_description.​vistring or null

ベトナム語

long_description.​kmstring or null

クメール語

long_description.​idstring or null

インドネシア語

long_description.​lostring or null

ラオス語

long_description.​mystring or null

ビルマ語

long_description.​phstring or null

フィリピン語

long_description.​nestring or null

ネパール語

image_urlstring

画像URL。

例: "https://image.example.com"
media_listArray of objects

スクリーンショット、ゲームプレイ動画などのゲーム追加アセット。

例: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
media_list[].​typestring

メディアタイプ：image/video。

Enum"image""video"
例: "image"
media_list[].​urlstring

リソースファイル。

例: "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"
orderinteger

リスト内のゲーム順の優先順位。

例: 1
groupsArray of objects

アイテムが所属するグループ。

例: [{"external_id":"horror","name":{"en":"Horror"}}]
groups[].​external_idstring
例: "horror"
groups[].​nameobject
例: {"en":"Horror"}
attributesArray of objects

属性リスト。

例: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$必須

一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。

例: "attribute_external_id"
attributes[].​nameobject

属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

例: {"en":"Attribute name","de":"Attributname"}
attributes[].​name.​property name*string追加プロパティ
attributes[].​valuesArray of objects必須
例: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$必須

属性の一意の値ID。external_idには、半角小文字の英数字、ハイフン、アンダースコアのみを含めることができます。

例: "value_external_id"
attributes[].​values[].​valueobject必須

値名がローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

attributes[].​values[].​value.​property name*string追加プロパティ
is_enabledboolean
is_freeboolean

アイテムが無料かどうか。

is_show_in_storeboolean
unit_itemsArray of objects

異なるDRMに対応したゲームキー。

unit_items[].​item_idinteger

アイテム作成時に付与される内部一意のアイテムID。

例: 1
unit_items[].​skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "game_1"
unit_items[].​typestring

アイテムタイプ。 この場合、それは常にgame_keyです。

例: "game_key"
unit_items[].​is_freeboolean

アイテムが無料かどうか。

unit_items[].​pricesArray of objects

実際通貨建ての価格。

例: [{"amount":1299.99,"currency":"RUB","is_default":true,"is_enabled":true,"country_is":"RU"}]
unit_items[].​prices[].​amountnumber
例: 1299.99
unit_items[].​prices[].​currencystring

商品価格通貨。ISO 4217 による3文字コード。

例: "RUB"
unit_items[].​prices[].​is_defaultboolean

ユーザーの通貨での価格が指定されていない場合、デフォルトの価格がカタログ作成に使用されます。

unit_items[].​prices[].​is_enabledboolean
unit_items[].​prices[].​country_isostring or null

この価格が利用可能な国。ISO 3166-1 alpha 2に基づく2文字コード。

例: "US"
unit_items[].​virtual_pricesArray of objects or null
例: [{"sku":"com.xsolla.gold_1","name":{"en":"Gold"},"type":"virtual_currency","description":null,"image_url":"https://i.pinimg.com/originals/91/ae/56/91ae5683045f6dbef16b1482bade938f.png","amount":1000,"is_default":true}]
unit_items[].​virtual_prices[].​skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "gold"
unit_items[].​virtual_prices[].​nameobject

仮想通貨用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

例: {"en":"Gold"}
unit_items[].​virtual_prices[].​name.​property name*any追加プロパティ
unit_items[].​virtual_prices[].​typestring

アイテムタイプ。 この場合、それは常にvirtual_currencyです。

例: "virtual_currency"
unit_items[].​virtual_prices[].​descriptionobject

ゲーム説明用のローカライズを含むオブジェクト。ゲームキーは「ISO 3166-1」で指定されています。

例: {"en":"Game 1 Example"}
unit_items[].​virtual_prices[].​description.​property name*any追加プロパティ
unit_items[].​virtual_prices[].​image_urlstring

画像URL。

例: "https://image.example.com"
unit_items[].​virtual_prices[].​amountnumber
unit_items[].​virtual_prices[].​is_defaultboolean
unit_items[].​orderinteger

リスト内のゲーム順の優先順位。

例: 1
unit_items[].​is_enabledboolean

無効の場合、アイテムの購入やインベントリからのアクセスはできません。

unit_items[].​is_show_in_storeboolean

アイテムは購入可能です。

unit_items[].​drm_namestring

ゲームキーDRMの名称。

例: "Steam"
unit_items[].​drm_skustring

DRMユニークID。

例: "steam"
unit_items[].​drm_imagestring or null

ゲームキーDRMのアイコン。

例: "https://upload.wikimedia.org/wikipedia/en/4/48/Steam_Icon_2014.png"
unit_items[].​drm_idinteger

DRM内部の一意のID。

例: 1
unit_items[].​keysobject
unit_items[].​keys.​availableinteger

購入可能なキーの数。

unit_items[].​keys.​totalinteger

アップロードされたキーの合計数。

unit_items[].​keys.​usedinteger

販売されたキーの数。

unit_items[].​is_sales_existboolean

trueの場合、ユーザーがゲームキーを購入しました。

unit_items[].​pre_orderobject

先行予約の設定。

unit_items[].​pre_order.​release_datestring or null

ISO 8601形式でのゲームキーのリリース日。

unit_items[].​pre_order.​is_enabledboolean

無効の場合、アイテムは先行予約ではありません。

unit_items[].​pre_order.​descriptionstring or null

予約注文に関する追加情報は電子メールで送信されます。

unit_items[].​regionsArray of objects
unit_items[].​regions[].​idinteger
例: 1
unit_items[].​limitsobject or null

アイテム制限。

unit_items[].​limits.​per_userobject or null

別ユーザーのアイテム制限。

unit_items[].​limits.​per_user.​totalinteger

1ユーザーあたりのユーザーが購入できるアイテムの最大数。

unit_items[].​limits.​per_user.​limit_exceeded_visibilitystring

購入制限に達してから次回の制限リセットまでの間、カタログ内でのアイテムの表示・非表示を決定します。

これは、recurrent_schedule配列で定期的な制限リセットが設定されているアイテムに適用されます。

購入制限のリセットが設定されていない場合、購入制限に達した後は、limit_exceeded_visibilityの値に関わらず、そのアイテムはカタログに表示されなくなります。

指定可能な値：

  • show — 購入制限に達した後も、カタログ取得用のAPIコールに対してアイテム情報が返却されます。クライアントサイドのカタログ取得APIコールにおいては、制限に達した時点でアイテムにcan_be_bought: falseフラグが付与されて返されます。次回のリセット日時はreset_next_dateに格納されて返却されます。
  • hide — 購入制限に達した時点から、制限値がリセットされるまでの間、カタログ取得用のAPIコールにおいてアイテムは返されなくなります。
Enum"show""hide"
unit_items[].​limits.​per_itemobject or null

グローバルアイテム制限。

unit_items[].​limits.​per_item.​totalinteger

すべてのユーザーが購入できるアイテムの最大数。

unit_items[].​limits.​per_item.​availableinteger

すべてのユーザーが購入できるアイテムの残り数。

unit_items[].​limits.​per_item.​reservedinteger
unit_items[].​limits.​per_item.​soldinteger
unit_items[].​limits.​recurrent_scheduleobject or null

制限更新期間。

unit_items[].​limits.​recurrent_schedule.​per_userobject

ユーザー制限更新期間。

One of:

ユーザー制限の日次更新タイプ。

unit_items[].​limits.​recurrent_schedule.​per_user.​interval_typestring

定期更新期間のタイプ。

値"daily"
unit_items[].​limits.​recurrent_schedule.​per_user.​timestring(full-time)

希望するタイムゾーンでのリミットの更新時刻（時間単位への四捨五入）。

例: "11:00:00+03:00"
unit_items[].​limits.​recurrent_schedule.​per_user.​reset_next_dateinteger

制限が更新された日時（UNIXタイムスタンプ）。

例: 1677553200
unit_items[].​limits.​recurrent_schedule.​per_user.​displayable_reset_start_datestring(date-time)

最初の制限更新の日時（ISO 8601）。

例: "2023-02-28T11:00:00+08:00"
unit_items[].​limits.​recurrent_schedule.​per_user.​displayable_reset_next_datestring(date-time)

制限をリセットする日時（ISO 8601）。

例: "2023-02-28T11:00:00+08:00"
unit_items[].​periodsArray of objects

アイテム販売期間。

unit_items[].​periods[].​date_fromstring or null(date-time)

指定されたアイテムの販売開始日。

例: "2020-08-11T10:00:00+03:00"
unit_items[].​periods[].​date_untilstring or null(date-time)

指定されたアイテムが販売できなくなる日付。nullを指定することもできます。

例: "2020-08-11T20:00:00+03:00"
レスポンス
application/json
{
  "item_id": 1,
  "sku": "com.xsolla.game_1",
  "type": "unit",
  "name": {
    "en": "Game 1"
  },
  "description": {
    "en": "Example game 1"
  },
  "long_description": {
    "en": "Example game's long description"
  },
  "image_url": "https://image.example.com",
  "media_list": [
    { … }
  ],
  "order": 1,
  "groups": [
    { … }
  ],
  "attributes": [
    { … }
  ],
  "is_free": false,
  "is_enabled": true,
  "is_show_in_store": false,
  "unit_items": [
    { … },
    { … }
  ]
}

SKUによるゲームを更新Server-sideAdmin

リクエスト

SKUによるプロジェクト内のゲームを更新します。

セキュリティ
basicAuth
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
item_skustring必須

アイテムSKU。

例: booster_mega_1
ボディapplication/json必須

ゲームデータを持つオブジェクト。

skustring[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$必須

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "com.xsolla.game_1"
name(object or null)必須

アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

例: {"en-US":"Game name","ru-RU":"Название игры"}
Any of:

2文字の小文字の言語コード。

name.​enstring or null

英語

name.​arstring or null

アラビア語

name.​bgstring or null

ブルガリア語

name.​cnstring or null

中国語（簡体字）

name.​csstring or null

チェコ語

name.​destring or null

ドイツ語

name.​esstring or null

スペイン語（スペイン）

name.​frstring or null

フランス語

name.​hestring or null

ヘブライ語

name.​itstring or null

イタリア語

name.​jastring or null

日本語

name.​kostring or null

韓国語

name.​plstring or null

ポーランド語

name.​ptstring or null

ポルトガル語

name.​rostring or null

ルーマニア語

name.​rustring or null

ロシア語

name.​thstring or null

タイ語

name.​trstring or null

トルコ語

name.​twstring or null

中国語（繁体字）

name.​vistring or null

ベトナム語

name.​kmstring or null

クメール語

name.​idstring or null

インドネシア語

name.​lostring or null

ラオス語

name.​mystring or null

ビルマ語

name.​phstring or null

フィリピン語

name.​nestring or null

ネパール語

description(object or null)

アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

例: {"en-US":"Game description","ru-RU":"Краткое описание игры"}
Any of:

2文字の小文字の言語コード。

description.​enstring or null

英語

description.​arstring or null

アラビア語

description.​bgstring or null

ブルガリア語

description.​cnstring or null

中国語（簡体字）

description.​csstring or null

チェコ語

description.​destring or null

ドイツ語

description.​esstring or null

スペイン語（スペイン）

description.​frstring or null

フランス語

description.​hestring or null

ヘブライ語

description.​itstring or null

イタリア語

description.​jastring or null

日本語

description.​kostring or null

韓国語

description.​plstring or null

ポーランド語

description.​ptstring or null

ポルトガル語

description.​rostring or null

ルーマニア語

description.​rustring or null

ロシア語

description.​thstring or null

タイ語

description.​trstring or null

トルコ語

description.​twstring or null

中国語（繁体字）

description.​vistring or null

ベトナム語

description.​kmstring or null

クメール語

description.​idstring or null

インドネシア語

description.​lostring or null

ラオス語

description.​mystring or null

ビルマ語

description.​phstring or null

フィリピン語

description.​nestring or null

ネパール語

long_description(object or null)

アイテムの長文説明のローカライズを含むオブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のバリアント（例：enとen-US）が提供された場合、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

例: {"en-US":"Game long description","ru-RU":"Полное описание игры"}
Any of:

2文字の小文字の言語コード。

long_description.​enstring or null

英語

long_description.​arstring or null

アラビア語

long_description.​bgstring or null

ブルガリア語

long_description.​cnstring or null

中国語（簡体字）

long_description.​csstring or null

チェコ語

long_description.​destring or null

ドイツ語

long_description.​esstring or null

スペイン語（スペイン）

long_description.​frstring or null

フランス語

long_description.​hestring or null

ヘブライ語

long_description.​itstring or null

イタリア語

long_description.​jastring or null

日本語

long_description.​kostring or null

韓国語

long_description.​plstring or null

ポーランド語

long_description.​ptstring or null

ポルトガル語

long_description.​rostring or null

ルーマニア語

long_description.​rustring or null

ロシア語

long_description.​thstring or null

タイ語

long_description.​trstring or null

トルコ語

long_description.​twstring or null

中国語（繁体字）

long_description.​vistring or null

ベトナム語

long_description.​kmstring or null

クメール語

long_description.​idstring or null

インドネシア語

long_description.​lostring or null

ラオス語

long_description.​mystring or null

ビルマ語

long_description.​phstring or null

フィリピン語

long_description.​nestring or null

ネパール語

image_urlstring

画像URL。

例: "http://image.png"
media_listArray of objects

スクリーンショット、ゲームプレイ動画などのゲーム追加アセット。

例: [{"type":"image","url":"http://image.png"},{"type":"video","url":"http://video.png"}]
media_list[].​typestring

メディアタイプ：image/video。

Enum"image""video"
例: "image"
media_list[].​urlstring

リソースファイル。

例: "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"
orderinteger

リスト内のゲーム順の優先順位。

例: 1
groupsArray of objects

アイテムが所属するグループ。

例: ["new_games"]
groups[].​external_idstring必須
例: "horror"
attributesArray of objects<= 20 items

属性リスト。

注意。アイテムの属性は20個以上指定することはできません。制限を超えようとすると、エラーが発生します。
attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$必須

一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。

attributes[].​nameobject

属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

attributes[].​name.​property name*string追加プロパティ
attributes[].​valuesArray of objects必須
注意。各属性に6つ以上の値を作成することはできません。制限を超えようとすると、エラーが発生します。
例: [{"external_id":"strategy","value":{"en":"Strategy","de":"Strategie"}},{"external_id":"action","value":{"en":"Action","de":"Aktion"}}]
attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$必須

属性の一意の値ID。external_idには、半角小文字の英数字、ハイフン、アンダースコアのみを含めることができます。

例: "value_external_id"
attributes[].​values[].​valueobject必須

値名がローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

attributes[].​values[].​value.​property name*string追加プロパティ
is_enabledboolean

無効の場合、アイテムの購入やインベントリからのアクセスはできません。

例: true
is_show_in_storeboolean

アイテムは購入可能です。

例: true
unit_itemsArray of objects必須

異なるDRMに対応したゲームキー。

例: [{"sku":"com.xsolla.game_key_1","name":{"en-US":"Game key name","ru-RU":"Название игрового ключа"},"drm_sku":"steam_key_1","prices":[{"amount":35.5,"currency":"USD","is_enabled":true,"is_default":true}],"vc_prices":[{"amount":35.5,"sku":"com.xsolla.gold_1","is_enabled":true,"is_default":true}],"is_enabled":true,"is_free":false,"is_show_in_store":true,"pre_order":{"release_date":"2020-08-11T10:00:00+03:00","is_enabled":true,"description":"Some description"},"regions":[{"id":12},{"id":64}],"limits":{"per_user":{"total":5},"per_item":{"total":10000,"available":5000,"reserved":500,"sold":4500}},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}]}]
unit_items[].​skustring[ 1 .. 255 ] characters必須

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "game_1"
unit_items[].​name(object or null)

アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

Any of:

2文字の小文字の言語コード。

unit_items[].​name.​enstring or null

英語

unit_items[].​name.​arstring or null

アラビア語

unit_items[].​name.​bgstring or null

ブルガリア語

unit_items[].​name.​cnstring or null

中国語（簡体字）

unit_items[].​name.​csstring or null

チェコ語

unit_items[].​name.​destring or null

ドイツ語

unit_items[].​name.​esstring or null

スペイン語（スペイン）

unit_items[].​name.​frstring or null

フランス語

unit_items[].​name.​hestring or null

ヘブライ語

unit_items[].​name.​itstring or null

イタリア語

unit_items[].​name.​jastring or null

日本語

unit_items[].​name.​kostring or null

韓国語

unit_items[].​name.​plstring or null

ポーランド語

unit_items[].​name.​ptstring or null

ポルトガル語

unit_items[].​name.​rostring or null

ルーマニア語

unit_items[].​name.​rustring or null

ロシア語

unit_items[].​name.​thstring or null

タイ語

unit_items[].​name.​trstring or null

トルコ語

unit_items[].​name.​twstring or null

中国語（繁体字）

unit_items[].​name.​vistring or null

ベトナム語

unit_items[].​name.​kmstring or null

クメール語

unit_items[].​name.​idstring or null

インドネシア語

unit_items[].​name.​lostring or null

ラオス語

unit_items[].​name.​mystring or null

ビルマ語

unit_items[].​name.​phstring or null

フィリピン語

unit_items[].​name.​nestring or null

ネパール語

unit_items[].​groupsArray of objects

アイテムが所属するグループ。

unit_items[].​groups[].​external_idstring必須
例: "horror"
unit_items[].​attributesArray of objects

属性リスト。

例: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
unit_items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$必須

一意の属性ID。external_idには、小文字と大文字のラテン英数字、ダッシュ、およびアンダースコアのみが含まれます。

例: "attribute_external_id"
unit_items[].​attributes[].​nameobject

属性用のローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

例: {"en":"Attribute name","de":"Attributname"}
unit_items[].​attributes[].​name.​property name*string追加プロパティ
unit_items[].​attributes[].​valuesArray of objects必須
例: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
unit_items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$必須

属性の一意の値ID。external_idには、半角小文字の英数字、ハイフン、アンダースコアのみを含めることができます。

例: "value_external_id"
unit_items[].​attributes[].​values[].​valueobject必須

値名がローカライズされたオブジェクト。キーはISO 3166-1で指定されています。

unit_items[].​attributes[].​values[].​value.​property name*string追加プロパティ
unit_items[].​is_freeboolean

アイテムが無料かどうか。

unit_items[].​pricesArray of objects必須

実際通貨建ての価格。

unit_items[].​prices[].​amountnumber必須
例: 1299.99
unit_items[].​prices[].​currencystring必須

商品価格の通貨。3文字のコードISO4217 規格詳細については、ドキュメントを参照してください。エクソーラでサポートされている通貨。

例: "RUB"
unit_items[].​prices[].​is_defaultboolean必須

ユーザーの通貨での価格が指定されていない場合、デフォルトの価格がカタログ作成に使用されます。

unit_items[].​prices[].​is_enabledboolean必須
unit_items[].​vc_pricesArray of objects
unit_items[].​vc_prices[].​skustring

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

例: "gold"
unit_items[].​vc_prices[].​amountnumber必須
unit_items[].​vc_prices[].​is_defaultboolean必須
unit_items[].​vc_prices[].​is_enabledboolean必須
unit_items[].​orderinteger

リスト内のゲーム順の優先順位。

例: 1
unit_items[].​is_enabledboolean

無効の場合、アイテムの購入やインベントリからのアクセスはできません。

unit_items[].​is_show_in_storeboolean

アイテムは購入可能です。

unit_items[].​drm_skustring必須

DRMユニークID。

例: "steam"
unit_items[].​pre_orderobject

先行予約の設定。

unit_items[].​pre_order.​release_datestring必須

ISO 8601形式でのゲームキーのリリース日。

unit_items[].​pre_order.​is_enabledboolean必須

無効の場合、アイテムは先行予約ではありません。

unit_items[].​pre_order.​descriptionstring

予約注文に関する追加情報は電子メールで送信されます。

unit_items[].​regionsArray of objects
unit_items[].​regions[].​idinteger
例: 1
unit_items[].​limitsobject

アイテム制限。

unit_items[].​limits.​per_usernull or integer or object

別ユーザーのアイテム制限。

Any of:

別ユーザーのアイテム制限。

null
unit_items[].​limits.​per_iteminteger or null

グローバルアイテム制限。

unit_items[].​limits.​recurrent_scheduleobject or null

制限更新期間。

unit_items[].​limits.​recurrent_schedule.​per_userobject
One of:

ユーザー制限の日次更新タイプ。

unit_items[].​limits.​recurrent_schedule.​per_user.​interval_typestring必須

定期更新期間。

値"daily"
unit_items[].​limits.​recurrent_schedule.​per_user.​timestring((0[0-9]|1[0-9]|2[0-3]):00:00)(\+|-)(0[0-9]|1...必須

希望するタイムゾーンでのリミットの更新時刻（時間単位への四捨五入）。

例: "02:00:00+03:00"
unit_items[].​periodsArray of objects or null

アイテム販売期間。

unit_items[].​periods[].​date_fromstring(date-time)

指定されたアイテムの販売開始日。

例: "2020-08-11T10:00:00+03:00"
unit_items[].​periods[].​date_untilstring or null(date-time)

指定されたアイテムが販売できなくなる日付。nullを指定することもできます。

例: "2020-08-11T20:00:00+03:00"
curl -i -X PUT \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/game/sku/booster_mega_1 \
  -H 'Content-Type: application/json' \
  -d '{
    "sku": "com.xsolla.game_1",
    "name": {
      "en-US": "Game name",
      "ru-RU": "Название игры"
    },
    "description": {
      "en-US": "Game description",
      "ru-RU": "Краткое описание игры"
    },
    "long_description": {
      "en-US": "Game long description",
      "ru-RU": "Полное описание игры"
    },
    "image_url": "http://image.png",
    "media_list": [
      {
        "type": "image",
        "url": "http://image.png"
      },
      {
        "type": "video",
        "url": "http://video.png"
      }
    ],
    "groups": [
      "new_games"
    ],
    "is_enabled": true,
    "is_show_in_store": true,
    "unit_items": [
      {
        "sku": "com.xsolla.game_key_1",
        "name": {
          "en-US": "Game key name",
          "ru-RU": "Название игрового ключа"
        },
        "drm_sku": "steam_key_1",
        "prices": [
          {
            "amount": 35.5,
            "currency": "USD",
            "is_enabled": true,
            "is_default": true
          }
        ],
        "vc_prices": [
          {
            "amount": 35.5,
            "sku": "com.xsolla.gold_1",
            "is_enabled": true,
            "is_default": true
          }
        ],
        "is_enabled": true,
        "is_free": false,
        "is_show_in_store": true,
        "pre_order": {
          "release_date": "2020-08-11T10:00:00+03:00",
          "is_enabled": true,
          "description": "Some description"
        },
        "regions": [
          {
            "id": 12
          },
          {
            "id": 64
          }
        ],
        "limits": {
          "per_user": {
            "total": 5
          },
          "per_item": {
            "total": 10000,
            "available": 5000,
            "reserved": 500,
            "sold": 4500
          }
        },
        "periods": [
          {
            "date_from": "2020-08-11T10:00:00+03:00",
            "date_until": "2020-08-11T20:00:00+03:00"
          }
        ]
      }
    ]
  }'

レスポンス

ゲームは正常に更新されました。

レスポンス
コンテンツなし

概要

バンドルとは、複数のアイテムを1つの単位としてセット販売するものです。バンドルには、仮想アイテム、仮想通貨、仮想通貨パッケージ、ゲームキー、および他のバンドルを含めることができます。バンドルを活用することで、スターターパック、季節限定オファー、特別セールなどを作成できます。

バンドルを操作するには、以下のAPIコールグループを使用します：

  • バンドルの作成、更新、削除、およびそれらの公開状態を管理するには、管理者サブセクションのAPIコールを使用します。
  • バンドルの情報取得には、カタログサブセクションのAPIコールを使用します。

購入制限は、バンドルの作成または更新時にlimitsオブジェクトを介して設定します。詳細については、制限の概要を参照してください。また、特定の国でアイテムを販売するために、地域制限を設定することも可能です。

注意

バンドルの設定に関する詳細情報については、バンドルセクションを参照してください。

バンドル管理のシナリオ：

  1. バンドルを作成する APIコールを使用して、バンドルを作成します。作成したバンドルを検証するには、バンドルを取得するAPIコールを使用します。プロジェクト内のすべてのバンドルを取得するには、バンドルリストを取得するAPIコールを使用します。
  2. 必要に応じて、バンドルを更新するAPIコールを使用し、バンドルの内容や設定を変更します。
  3. バンドルリストを取得する、指定したバンドルを取得する、または指定したグループのバンドルリストを取得するAPIコールを使用して、ストアフロントにバンドルの表示ロジックを実装します。
  4. カートと決済セクションを使用して注文を作成します。たとえば、素早く購入できるようにするには、バンドルのSKUを渡し、指定したアイテムを含む注文を作成するAPIコールを使用できます。応答には、決済UIを開くためのトークンが含まれています。
  5. 注文の支払いを行うために、決済UIを開く処理を実装します。
  6. 決済が完了したアイテムのデータをタイムリーに受け取り、ユーザーにそれらを付与するために、たとえばウェブフックを使用して注文ステータスのトラッキングを設定します。

バンドル管理のシナリオ

管理者

操作

カタログ

操作

概要

カートは、複数のアイテムを1つの注文にまとめることができる購入メカニズムです。ユーザーは、任意のタイプのアイテムを任意の数量で実際通貨で購入でき、プロモーションコードも使用できます。

カートはエクソーラ側で保存されます。セッションをまたいでカートを保存できるかどうかは、ユーザーが認証されているかによって異なります。

  • 認証されたユーザーの場合、カートは特定のユーザーに紐付けられ、同じユーザーとしてリクエストが送信される限り、セッションをまたいで保存されます。

  • 未認証ユーザーの場合、カートの保存はx-unauthorized-idヘッダーの成否に依存します。未認証ユーザーのカートをセッション間で保持するには、すべてのリクエストで同じx-unauthorized-idを渡してください。なお、このオプションはゲームキーの販売時のみ利用可能です。

カートを特定する方法は2つあります。ユーザーのJWTによる自動特定、またはカートID（cart_id）による特定です。

カート管理は、クライアント側とサーバー側の両方で利用可能です。

サーバー側では、ユーザーセッションを復元する場合などに、カートにアイテムを入れることができます。クライアント側では、以下の操作が利用可能です：

  • 現在のユーザーのカートまたはIDによるカートを取得する
  • カートにアイテムを追加する
  • カート内のアイテムを更新する
  • カートからアイテムを削除する

カートからアイテムを購入するには、注文作成のためのクライアントとサーバーのコールが使用されます。

カートの有効期限（TTL）は、デフォルトで72時間です。新しいアイテムが追加されるなど、カートの内容が変更されると、TTLは延長されます。

決済が成功した後も、カートは自動的にはクリアされません。カートをクリアするには、クライアントサイドの以下のAPIコールを使用してください：

カート使用シナリオ：

  1. ユーザーがアイテムを選択するストアUIを実装します。

  2. ユーザーがストアでアイテムを選択した際、たとえば カートへアイテムを追加するコールを使用してアイテムをカートに追加します。アイテム配列には、SKUと必要なアイテムの数量を渡す必要があります。

  3. カート表示UIを実装します。ユーザーがカートに移動した際、現在のユーザーのカートを取得するコールを使用してカートの内容を表示します。応答には、割引や適用されたプロモーションを含むアイテムの最終価格に関する情報が返されます。

  4. 注文の支払いを行うために、決済UIを開く処理を実装します。たとえば、特定のカートの全アイテムを含む注文を作成するコールを使用できます。応答には、決済UIを開くためのトークンが返されます。

  5. 決済が完了したアイテムのデータをタイムリーに受け取り、ユーザーにそれらを付与するために、たとえばウェブフックを使用して注文状況の追跡を設定します。

注意

ゲーム内およびオンラインでのアイテム販売を実装するには、統合ガイドを参照してください。

カートと決済フロー

注文のライフサイクル

注文のライフサイクルを理解することは、注文の追跡や、アイテムの付与といった購入後ロジックの正確な実装に役立ちます。

注文は以下のステータスを遷移します：

ステータス説明備考
new注文が作成されました。システムは支払い完了の確認を待っています。トランザクションステータスの説明は、ペイステーションAPIに関するドキュメントで確認できます。
paid注文の支払いが完了し（トランザクションがdoneステータスに移行）、ユーザーにアイテムを付与できる状態です支払いが確認されるまで、注文はnewステータスのままとなります。
doneアイテムがユーザーに付与されました。 —
canceled支払いが返金されました。トランザクションステータスがrefundedに変更されると、注文はこのステータスに移行します。
expired制限 付きアイテム、プロモーションコード、またはプロモーションに対して新しい注文を作成すると、そのアイテムを含む過去の未払いの注文はすべてexpiredステータスに移行します。支払いが可能なのは最新の注文のみです。ユーザーが有効期限切れの注文に対して支払いを試みた場合、支払いUIに 2002 エラーが表示され、決済は失敗します。

注文のライフサイクル

注意

ユーザーが支払いを完了する間に注文がexpiredステータスに移行した場合でも、決済自体が成功したときは、注文はexpiredからpaidステータスに移行します。ただし、これが適用されるのは、決済時にその注文アイテムの購入制限数を超えない場合に限られます。

カート（クライアント側）

このセクションのコールを使用して、クライアント側でカートを管理します。

操作

カート（サーバー側）

このセクションのコールを使用して、サーバー側でカートを管理します。

操作

決済（クライアント側）

このセクションのコールを使用して、クライアント側で決済トークンを作成します。

操作

決済（サーバー側）

このセクションのコールを使用して、サーバー側で決済トークンを作成します。

操作

注文

このセクションのコールを使用して、注文に関する情報を取得します。

操作

無料アイテム

ユーザーに無料アイテムを付与するには、このセクションのコールを使用してください。

操作

概要

購入制限を使用すると、単一のユーザーまたはすべてのユーザーが購入できるアイテム数量を制限できます。スケジュールされた制限リセットを設定することもできます。

制限はエクソーラ側に保存され、パブリッシャーアカウントで個々のアイテムレベルで設定されるか、以下のAPIコールのlimitsオブジェクトを介して設定されます：

制限情報は、アイテムカタログを取得するための以下のAPIコールでitems.limitsオブジェクトに返されます：

制限グループの管理サブセクションに属するAPIコールにより、制限の現在状態の取得、および指定したユーザーに対する制限値の更新が可能となります（例：クエスト完了時におけるカウンターのリセット、残存数量の手動調整など）。

注意

カタログでの制限設定の詳細については、アイテム購入制限セクションを参照してください。

管理

操作

管理者

操作

先行予約

操作

マーチャント

操作

カタログ

このAPIは販売可能なアイテムや特定のアイテムを取得することができます。

操作

共通地域

地域別の販売制限を使用すると、特定の国または国グループにおけるアイテムの可用性を管理できます。例えば、ライセンスの制約により、特定の国だけでゲームを販売するといったことが可能です。

制限の設定には「地域」を使用します。各地域は、1つ以上の国を単一のregion_idでまとめたものです。アイテムを1つ以上の地域に関連付けることができます。

アイテムの可用性は、以下のように判定されます：

  • アイテムに地域の指定がない場合、すべての国で購入可能です。
  • アイテムに地域が指定されており、ユーザーの国がそのいずれかに含まれている場合、そのユーザーはアイテムを購入できます。
  • アイテムに地域が指定されており、ユーザーの国がどの地域にも含まれていない場合、そのユーザーはアイテムを購入できません。

ユーザーの国は、カタログセクションからのAPIコールを通じてカタログをリクエストする際、countryパラメータとして渡されます。このパラメータが渡されない場合は、ユーザーのIPアドレスに基づいて国が判定されます。

ユーザーの国とアイテムの地域との照合は、カタログのリクエスト時と注文作成時の2回行われます。購入不可のアイテムはカタログのレスポンスには含まれず、そのようなアイテムを含む注文が作成されることはありません。

地域の作成、更新、および削除には、共通地域グループのAPIコールを使用します。

地域別の販売制限のセットアップフロー：

  1. 地域を作成するAPIコールを使用して、対象となる国のリストを指定して地域を作成します。レスポンスには、次のステップで必要となるregion_idが返されます。
  2. アイテムを作成する際、または更新する際に、regions配列にそのregion_idを渡すことで、仮想アイテムを地域に関連付けます。
  3. カタログセクションのAPIコール（例：仮想アイテムリストを取得するAPIコール）を使用して、ユーザーにカタログを表示します。ユーザーの国はcountryパラメータによって決定されます。このパラメータが提供されない場合は、ユーザーのIPアドレスに基づいて判定されます。ユーザーの国で利用不可のアイテムは、カタログの応答には含まれません。
  4. ユーザーがアイテムまたはカートの決済に進む際に、注文を作成します：

レスポンスには、決済UIを開くためのトークンが含まれています。

注意

エクソーラは、ユーザーの国がアイテムに指定された地域に含まれているかを確認します。国がアイテムの地域に含まれていない場合、注文を作成することはできません。

  1. 注文を支払うための決済UIを開く処理を実装します。

Common regions

操作

ウェブフック

操作

管理者

操作

管理者

操作

カタログ

操作