Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

行動データ連携ガイド

1

連携の準備 (Prepare)

APIを呼び出すために必要な基本情報です。

  • API Endpoint: https://api.gelatto.ai

  • Method: POST

  • Content-Type: application/json (または application/ld+json)

  • API Key: 管理画面の［設定］メニューで発行されたAPI Key

2

認証する (Authenticate)

発行されたキーをHTTPリクエストヘッダー（Header）に設定します。すべてのAPIリクエストには、以下のヘッダーを必ず含めてください。

ィールド名
区分
説明

Content-Type

必須

データの送信形式をJSONに指定します。

api-key

必須

［認証キー］管理画面の設定から発行されたAPI Keyです。

requestId

必須

［トラッキングキー］リクエストごとに新しく生成する一意の識別子です。（エラー追跡用）

Idempotency-Key

必須

［重複防止キー］ネットワークエラーなどによる重複処理を防止するためのキーです。

Idempotency Key のフォーマット詳細

genser APIでは、UUID Version 4標準の使用を推奨しています。

  • 推奨形式: ハイフン（-）を含む標準形式

  • 文字数:

    • 標準（推奨）: ハイフンを含めて全36文字 (例: 550e8400-e29b-41d4-a716-446655440000)

    • 代替形式: ハイフンを除いた全32文字 (例: 550e8400e29b41d4a716446655440000)

HTTP リクエストヘッダーの例:

POST /actions/cart/add HTTP/1.1
Host: api.gelatto.ai
Content-Type: application/json
api-key: <YOUR_API_KEY>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
requestId: req-20260112-001

3

データを送信する (Send Data)

ユーザーの行動が発生したタイミング（ボタンのクリック、ページの読み込みなど）に合わせて、該当するAPIを呼び出します。以下のケース別JSONサンプルを参考に、データを送信してください。各フィールドの詳細な仕様については、それぞれの［APIリファレンス］をご確認ください。

以下のリクエストBodyは、連携時のサンプルです。任意（Optional）フィールドは、お客様側で収集可能な場合にのみ送信してください。収集しないフィールドはリクエストから除外できます。

カート (Cart)

カートに追加 (Add to Cart)

ユーザーが「カートに追加」ボタンをクリックした際に呼び出します。

Path: /actions/cart/add

リクエスト本文（Body）のコードサンプル
{
  "specversion": "1.0.0",
  "id": "EVT-ADD-TO-CART-001",
  "type": "add_to_cart",
  "time": "2025-12-02T10:00:00Z",
  "source": "https://shop.example.com",
  "data": {
    "@context": "https://schema.org/",
    "@type": "AddAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        {
          "@type": "PropertyValue",
          "propertyID": "memberId",
          "value": "user1234"
        },
        {
          "@type": "PropertyValue",
          "propertyID": "userId",
          "value": "2aa9a562..."
        }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 2,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [
          {
            "@value": "ソイ 3人掛けソファ",
            "@language": "ja"
          }
        ],
        "offers": {
          "@type": "Offer",
          "price": 1285000,
          "priceCurrency": "KRW"
        }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://shop.example.com/cart"
    }
  }
}

カートから削除 (Remove from Cart)

ユーザーがカートから商品を削除した際に呼び出します。

Path: /actions/cart/remove

リクエスト本文（Body）のコードサンプル
{
  "specversion": "1.0.0",
  "id": "EVT-REMOVE-FROM-CART-001",
  "type": "remove_from_cart",
  "time": "2025-12-02T10:10:00Z",
  "source": "https://shop.example.com",
  "data": {
    "@context": "https://schema.org/",
    "@type": "DeleteAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        {
          "@type": "PropertyValue",
          "propertyID": "memberId",
          "value": "user1234"
        }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 1,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [
          {
            "@value": "ソイ 3人掛けソファ",
            "@language": "ja"
          }
        ],
        "offers": {
          "@type": "Offer",
          "price": 1285000,
          "priceCurrency": "KRW"
        }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://shop.example.com/cart"
    }
  }
}

注文・決済 (Purchase)

決済開始 (Start Checkout)

ユーザーが注文情報入力ページに遷移した際に呼び出します。

Path: /actions/purchase/checkout

リクエスト本文（Body）のコードサンプル

購入完了 (Complete Purchase)

決済が正常に完了したタイミング（注文完了ページ）で呼び出します。最も重要なデータです。

Path: /actions/purchase/complete

リクエスト本文（Body）のコードサンプル

決済キャンセル (Cancel Purchase)

ユーザーが決済をキャンセル、または注文を取り消した際に呼び出します。

Path: /actions/purchase/cancel

リクエスト本文（Body）のコードサンプル

検索 (Search)

検索キーワード送信 (Search Submitted)

ユーザーが検索ボックスにキーワードを入力し、Enterキーを押す、または虫眼鏡アイコンをクリックして検索を実行した際に呼び出します。

Path: /actions/search/submitted

リクエスト本文（Body）のコードサンプル

検索結果の表示 (View Search Result)

検索結果一覧ページが読み込まれた際に呼び出します。

Path: /actions/search/result

リクエスト本文（Body）のコードサンプル

商品 (Product)

商品詳細の表示 (View Product)

商品詳細ページ（PDP）に遷移した際に呼び出します。

Path: /actions/view/product

リクエスト本文（Body）のコードサンプル

商品クリック (Click Product)

一覧上の特定の商品をクリックした際に呼び出します。

Path: /actions/click/product

リクエスト本文（Body）のコードサンプル

ウィッシュリスト (Wishlist)

ウィッシュリストに追加 (Add to Wishlist)

「お気に入り」または「ウィッシュリストに追加」ボタンをクリックした際に呼び出します。

Path: /actions/wishlist/add=

リクエスト本文（Body）のコードサンプル

ウィッシュリストから削除 (Remove from Wishlist)

ウィッシュリストから商品を削除した際に呼び出します。

Path: /actions/wishlist/remove

リクエスト本文（Body）のコードサンプル

4

レスポンスを確認する (Check Response)

API呼び出し後、HTTPステータスコードを確認し、データ送信が正常に完了したかを判断します。

ステータスコード
結果
説明

200 OK

成功

正常に処理されました。翌日0:15のバッチ処理で反映されます。

400 Bad Request

リクエスト形式エラー

JSONの構文に誤りがないか、または必須項目（sku、nameなど）が不足していないかをご確認ください。

401 Unauthorized

認証エラー

api-keyが無効、または指定されていません。

500 Internal Error

サーバーエラー

一時的な障害の可能性があります。時間を置いてから再試行（Retry）処理を実行してください。

5

連携結果を確認する (Verify) - 今後提供予定

API連携後、データが正常に蓄積されているかを管理画面から確認できます。

Previousユーザー行動データの収集
NextAPIリファレンス

Last updated