メインコンテンツまでスキップ

カートAPI

概要​

カートAPIを使用することで、Roktのパートナーはトランザクション内で顧客のカートに追加の商品を追加することができます。カートAPIはWeb SDKと連携してフロントエンドの配置をレンダリングし、顧客のカートを更新するためのフックを提供します。Roktを介してアップセルを実現するためには、以下の2つの統合が必要です。

  1. バックエンドのカート/チェックアウトシステムをRoktのカートAPIと統合します（このドキュメント）。
  2. Web SDKをカートフロントエンドに統合します。

駐車場の予約は、Roktのカートに追加する商品の良い例です。たとえば、チケット販売パートナーは、イベントチケットを購入する際に顧客に駐車場の予約をアップセルすることができます。これらの駐車場は、サードパーティの駐車場提供業者から提供されます。

最小限の統合​

顧客の注文を処理するために、以下のフックとAPIエンドポイントとの統合が必要です。

  1. V2_CART_ITEM_UPDATED イベントにサブスクライブして、ユーザーがカートに商品を追加したときに通知を受け取ります。
  2. /cart/confirm を呼び出して、商品の購入が成功したことを確認します。

商品の予約​

一部の商品は、チェックアウト中に予約する必要があります。これにより、最終的に確認するときに在庫がまだ利用可能であることが保証されます。以下のエンドポイントは、予約の処理に使用する必要があります。

  1. /cart/reserve を呼び出して、一定期間の間商品を予約します。
  2. オプションで、/cart/releaseを呼び出して予約をキャンセルし、他の顧客がそれらのアイテムを予約できるようにします。

確定アイテムのキャンセル​

以下のエンドポイントは、アイテムが確定した後にキャンセルするために使用できます。

  1. /confirmation/cancelを呼び出します。

トランザクションリクエストフロー​

顧客の注文を処理するために、パートナーは以下のトランザクションフローに従う必要があります。

トランザクションリクエストフロー

  1. (オプション) /placements/anyを呼び出して、表示する配置があるかどうかを判断し、関連するオファーがない場合はクロスセル/アップセルのステージをスキップできます。
  2. /placements/anyがtrueまたはfalseを返すかどうかに基づいて、トランザクションフローのアップセルページを表示するかスキップするかを選択できます。アップセルページでは、Web SDKを初期化する必要があります。これにより、利用可能な配置が要求され、表示されます。
  3. 顧客がオプトインすると、Web SDKはV2_CART_ITEM_UPDATEDメッセージを送信してパートナーのフロントエンドに通知します。その後、通常の購入プロセスが進行します。
  4. (オプション) /cart/reserveを呼び出して、アイテムを一定期間予約します。その期間内に購入を完了し、Roktとの確認を行う必要があります。
  5. 顧客がアイテムを支払ったら、/cart/confirmを呼び出してアイテムの購入が成功したことを確認します。その後、Roktは商品の履行を担当する関連プロバイダに通知します。
    1. 予約をキャンセルするには、/cart/releaseを呼び出します。これは予約されたアイテムが確定されない場合に自動的に解放されるため、高トラフィックのパートナーに適しています。
    2. 確定したアイテムをキャンセルするには、/confirmation/cancelを呼び出します。これは、確定後にアイテムをキャンセルしたいパートナーに適しています。

認証​

認証を設定するには、Roktのアカウントマネージャーにお問い合わせください。

APIエンドポイント​

POST Any Placements​

パートナーは、表示する配置があるかどうかを判断し、必要に応じてアップセル/クロスセルのステージをスキップすることができます。

説明​

Roktのカートに追加する配置を含むページを表示する価値があるかどうかを判断するために使用されます。これがtrueまたはfalseを返すかどうかに基づいて、パートナーはトランザクションフローのアップセルページを表示するかスキップするかを選択できます。

サンプルリクエスト

POST /v1/placements/any
{
    "cartId": "1580265846172",
    "attributes": {
        "eventId": "1100526195FA115A",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36",
        "venueName": "Madison Square Garden",
        "eventdate": "20311212",
        "country": "US",
        "locale": "en-US"
    },
"pageIdentifier": "checkout.upsell"
}

リクエスト​

パス

POST /v1/Placements/any

パラメータ

名前In説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ。現在は 'application/json' のみサポートされています application/json
Acceptヘッダーレスポンスのメディアタイプの指定。現在は 'application/json' のみサポートされています application/json
rokt-session-idヘッダーRokt内部で使用されるセッションID。このエンドポイントではオプションです（提供されていない場合、セッションIDが生成されます）。 ca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idヘッダーユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageヘッダー消費者の予想されるロケール。言語と国を含む完全なロケール、または言語のみを持つ中立的なロケールが指定できます。ロケールが指定された場合、ロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "pageIdentifier": "string",
  "url": "string",
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "result": true
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Reserve Cart Items​

パートナーが一定期間アイテムを予約/保持できるようにします。この期間中に購入が完了し、Roktと確認されることで、パートナーは在庫と価格を確保できます。

説明​

ユーザーがカタログアイテムの選択を最終的に決定したが、まだ支払っていない場合、カートアイテムを予約することで、在庫の供給と価格の確保が行われます。このメソッドに複数のカートアイテムが渡された場合、一部は正常に予約され、一部は拒否される可能性があります。

サンプルリクエスト 

    POST /v1/cart/reserve
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": 1
            }
        ]
    }

リクエスト​

パス

POST /v1/cart/reserve

パラメータ

名前In説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ。現在は 'application/json' のみサポートされています application/json
Acceptヘッダーレスポンスのメディアタイプの指定。現在は 'application/json' のみサポートされています application/json
rokt-session-idheaderRokt内部で使用されるセッションID。トラッキング、リファラル、ログ記録、デバッグに使用されます。trueca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idheaderユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageheader消費者の期待するロケール。言語と国を含む完全なロケール、または言語のみを持つ中立的なロケールが指定できます。ロケールが指定された場合、ロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "quantity": 0
    }
  ],
  "isPayPalPayment": true,
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0,
      "unitPrice": 0,
      "totalPrice": 0,
      "currency": "string",
      "expirationDateTimeUtc": "2025-10-04T10:00:00.000Z",
      "success": true
    }
  ],
  "payPalOrderId": "string"
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Confirm Cart Items​

パートナーがアイテムの購入を確認するためのエンドポイントです。Roktは、適切なプロバイダーに製品の情報を提供します。

説明​

カート内のすべてのアイテムの支払いが処理された後に呼び出すことをお勧めします。このエンドポイントは、すべてのプラットフォーム、デバイス、環境（Web / アプリ）、国、チャネルでの購入イベントに対して呼び出す必要があります。

サンプルリクエスト #1

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

サンプルリクエスト #2

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": "15"
            }
        ]
    }

itemsコレクションには、少なくとも次のいずれかを含める必要があります。

- `cartItemId`と`itemReservationId`または
- `cartItemId`と`quantity`

リクエスト​

パス

POST /v1/cart/confirm

パラメーター

名前In説明必須例
rokt-api-keyheaderAPI認証キーtrueskeletonkey
Content-Typeheaderリクエストのメディアタイプ。現時点では 'application/json' のみがサポートされています。 application/json
Acceptheaderレスポンスのメディアタイプの指定。現時点では 'application/json' のみがサポートされています。 application/json
rokt-session-idheaderRokt内部で使用されるセッションID。トラッキング、リファラル、ログ記録、デバッグに使用されます。アイテムが含まれていない場合はオプションです（提供されていない場合はセッションIDが生成されます）。 ca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idheaderユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageheader消費者の期待するロケール。言語と国を含む完全なロケール、または言語のみを持つ中立的なロケールが指定できます。ロケールが指定された場合、ロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0
    }
  ],
  "payPalOrderId": "string",
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "itemConfirmationId": "string",
      "itemConfirmationUrl": "string",
      "success": true
    }
  ]
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

### POST 購入アイテムのキャンセル

パートナーが以前に購入した（確認済みの）アイテムをキャンセルすることを許可します。Roktは関連するプロバイダーにキャンセルを要求し、その応答を返します。

#### 説明 {#description}

**サンプルリクエスト**
```json
    POST /v1/confirmation/cancel
    {
        "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
    }

リクエスト​

パス

POST /v1/confirmation/cancel

パラメーター

名前In説明必須例
rokt-api-keyheaderAPI認証キーtrueskeletonkey
Content-Typeheaderリクエストのメディアタイプ。現時点では 'application/json' のみサポートされています。 application/json
Acceptheaderレスポンスのメディアタイプの予想。現時点では 'application/json' のみサポートされています。 application/json
Accept-Languageheader消費者の予想ロケール。言語と国を含む完全なロケール、または言語のみを持つ中立ロケールが指定できます。ロケールが指定された場合、ロケールに一致する配置とオファーのみが考慮されます。 en-US

リクエストボディ

#### レスポンス {#response}
**200** OK

#### エラー {#error}
**400** BadRequest

```json
{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST カートアイテムの解放​

パートナーは、アイテムの予約をキャンセルすることができます。これはオプションであり、確認されていない予約アイテムはタイムアウト後に自動的に解放されます。これは、予約されたアイテムを迅速に解放する必要があるバーストトラフィックを持つパートナーに適しています。

説明​

ユーザーがカートから予約されたアイテムを削除するか、カート/トランザクション全体をキャンセルする場合に使用します。予約されたカートアイテムは最終的にタイムアウトして自動的に解放されますが、バーストまたは高トラフィック環境を持つパートナーは、供給の早期または一時的な枯渇を防ぐためにこのプロセスを迅速化することができます。

サンプルリクエスト

 POST /v1/cart/release
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

リクエスト​

パス

POST /v1/cart/release

パラメーター

名前In説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ。現時点では 'application/json' のみがサポートされています。 application/json
Acceptヘッダーレスポンスのメディアタイプ。現時点では 'application/json' のみがサポートされています。 application/json
rokt-session-idヘッダーRokt内部で使用されるセッションID。追跡、紹介、ログ記録、デバッグに使用されます。trueca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idヘッダーユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageヘッダー消費者の予想されるロケール。これは、言語と国を含む完全なロケールであるか、言語のみを持つ中立的なロケールであるかのいずれかです。ロケールが指定されている場合、ロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string"
    }
  ],
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "success": true
    }
  ]
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}
この記事は役に立ちましたか？