サードパーティストアでアイテムのフルフィルメントを管理する

Last updated on February 4, 2026

注釈：本資料はAI技術を用いて翻訳されています。

概要​

AccelByte Gaming Services（AGS）フルフィルメントサービスは、サードパーティストアと統合してフルフィルメントを同期し、プレイヤーにアイテムを付与できます。統合の一環として、ストアの注文データをAGSのフルフィルメントエンドポイントにマッピングするミドルウェアとして機能するサーバーをセットアップする必要があります。

備考

統合されたサードパーティストアを通じてプレイヤーのインベントリからアイテムを取り消す方法については、サードパーティ取り消し統合も参照してください。

この記事では、サードパーティストアでアイテムフルフィルメントを管理する方法について説明します。

前提条件​

  • ユーザー認証: ユーザー認証を実装し、プレイヤーの有効なユーザーIDを持っていることを確認してください。
  • APIエンドポイントのアクセストークン: FulfillmentおよびRevocationエンドポイントにアクセスするために必要なアクセストークンと権限があることを確認してください。
  • ミドルウェアのセットアップ: サードパーティストアの注文データをAGS APIリクエスト形式にマッピングおよび変換するミドルウェアサーバーをセットアップします。
  • アイテム設定: 付与されるアイテムをAGSで設定し、サードパーティストアで販売されているアイテムと一致することを確認します。
  • インベントリ統合: InventoryサービスとCommerceサービスの統合が有効になっていないことを確認し、予期しないエンタイトルメント更新を防ぎます。

サポートされているアイテムタイプ​

サードパーティフルフィルメント方法は、次のアイテムタイプをサポートしています：

  • 永続および消費可能なゲーム内アイテム
  • バンドル
  • コイン
  • メディア
  • オプションボックス
  • ルートボックス
重要

個別のアイテムとして、またはバンドルの一部として、サポートされているアイテムタイプは、AGSストアおよび統合されたサードパーティストアでアイテムがアクティブである限り、プレイヤーに正常に付与できます。ただし、バンドル内の1つのアイテムでもサポートされていない場合、エンタイトルメント内のすべてのアイテムを実行またはプレイヤーに付与することはできません。

APIエンドポイント​

サードパーティストアでのアイテムフルフィルメントは、Fulfillment V2およびAdmin Query Fulfillment V2エンドポイントを通じて管理されます。

Fulfillment V2​

PUT /v2/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}エンドポイントは、提供された{transactionId}に基づいて複数のアイテムを付与し、フルフィルメントステータスを記録します。{transactionId}は、重複処理を防ぐために、クライアントのシステム内の各フルフィルメントリクエストの一意の識別子である必要があります。

注記
  • 複数の呼び出しを処理する場合、同じtransactionIdを持つ繰り返しリクエストは重複したエンタイトルメントを作成しません。システムはtransactionIdを認識し、実行されていないアイテムのみが処理されることを保証します。
  • リクエストが失敗した場合、インテグレーターはまず失敗の理由（非アクティブなアイテムやサポートされていないアイテムタイプなど）を特定する必要があります。レスポンスのエラーメッセージが問題の特定に役立ちます。問題が解決されたら、インテグレーターは同じtransactionIdを使用してフルフィルメントプロセスを再試行できます。システムは以前に失敗したアイテムのみを実行しようとし、成功したアイテムが重複しないようにします。必要に応じて、インテグレーターはRevoke Fulfillmentエンドポイントを使用してフルフィルメントを元に戻すこともできます。

パラメータ​

次の表は、Fulfillment V2リクエストの各パラメータを説明しています。

パラメータ説明要件
itemId実行または取り消されるアイテムの一意の識別子。itemSkuが存在しない場合は必須。両方が存在する場合は、itemIdが使用されます。
itemSkuアイテムの在庫管理単位識別子。itemIdが存在しない場合は必須
quantity実行または取り消されるアイテムの数。必須
orderNo購入または取引に関連付けられた注文番号。オプション
sourceアイテムの取得方法を示す、「PURCHASE」などのアイテムのソース。必須
startDateISO 8601形式で指定された、アイテムのエンタイトルメントの開始日。オプション
endDateISO 8601形式で指定された、アイテムのエンタイトルメントの終了日または有効期限。オプション
durationエンタイトルメントが有効な日数。これは、エンタイトルメントの期間（終了日または有効期限に関連）を設定するために使用されます。オプション
originCOINアイテムフルフィルメントの残高オリジン。仮想通貨が付与されるウォレットを設定するために使用されます。提供されない場合、SYSTEMに設定されます。オプション
metadata実行または取り消されるアイテムに関連する追加のプロパティまたはメタデータ。これには、アイテム固有のカスタムデータを含めることができます。
使用方法: コイン以外のアイテムに関連付けられたメタデータは、管理ポータルには表示されません。ただし、このメタデータはentitlementgrantedイベントに表示され、APIイベントを通じて監視できます。詳細については、EntitlementGrantedイベントドキュメントを参照してください。コインアイテムタイプの場合、メタデータはプレイヤーのウォレット履歴に表示され、管理者が仮想通貨取引を追跡できます。		オプション
entitlementOrigin他のアイテムタイプのエンタイトルメントに使用され、エンタイトルメントのオリジンを示します。提供されない場合、SYSTEMに設定されます。オプション

サンプルリクエスト​

{
    "items": [
        {
            "itemId": "required, if itemSku is not present, if both present itemId will be used",
            "itemSku": "required if itemId is not present",
            "quantity": 3,
            "orderNo": "optional",
            "source": "PURCHASE",
            "startDate": "optional",
            "endDate": "optional",
            "duration": 0,
            "origin": "Playstation",
            "metadata": {
                "additionalProp1": {},
                "additionalProp2": {},
                "additionalProp3": {}
            "entitlementOrigin": "Playstation",
        }
    ]
}

Admin Query Fulfillment V2​

GET /v2/admin/namespaces/{namespace}/fulfillmentsエンドポイントは、提供されたパラメータに基づいてフルフィルメントステータスをクエリします。

パラメータ​

次の表は、Admin Query Fulfillment V2リクエストの各パラメータを説明しています。

パラメータデータタイプ
transactionId`string
statestring
("FULFILLED", "REVOKED", "FULFILL_FAILED", または "REVOKE_FAILED")
userIdstring
staartTimetimestamp（ISO 8601形式）
endTimetimestamp（ISO 8601形式）
offsetinteger
limitinteger

サンプルレスポンス​

{
    "data": [
        {
            "id": "string",
            "namespace": "string",
            "userId": "UUID",
            "transactionId": "string",
            "state": "FULFILLED",
            "items": [
                {
                    "itemId": "UUID",
                    "itemSku": "string",
                    "itemType": "enum",
                    "quantity": 1
                }
            ],
            "stateInfo": {
               "successList": [
                   {
                      "itemId": "item-id-1",
                      "itemSku": "item-sku-1"
                   },
                   {
                      "itemId": "bundle-item-id-2",
                      "itemSku": "bundle-item-sku-2",
                      "Items": {
                                      "itemId: "item-id-3",
                                      "quantity": 3
                      }
                   }
               ],
               "failedList": [
                    {
                      "itemId": "item-id-4",
                      "itemSku": "item-sku-4",
                      "error": "failure reason"
                   },
                   {
                      "itemId": "bundle-item-id-5",
                      "itemSku": "bundle-item-sku-5",
                      "Items": {
                                      "itemId: "item-id-6",
                                      "quantity": 6
                                      "error": "failure reason"
                      }
                   }
               ]
            },
            "entitlementSummaries": [],
            "creditSummaries": [],
            "subscriptionSummaries": []
        }
    ],
    "paging": {
        "previous": "string",
        "next": "string"
    }
}

に最終更新
On this page