> For the complete documentation index, see [llms.txt](https://help.genser.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genser.ai/ja/developers/action-data/action-data-integration.md). # 行動データ連携ガイド
{% stepper %} {% step %} ## 連携の準備 (Prepare) APIを呼び出すために必要な基本情報です。 * **API Endpoint:** `https://api.gelatto.ai` * **Method:** `POST` * **Content-Type:** `application/json` (または `application/ld+json`) * **API Key:** 管理画面の［設定］メニューで発行されたAPI Key {% endstep %} {% step %} ## 認証する (Authenticate) 発行されたキーをHTTPリクエストヘッダー（Header）に設定します。すべてのAPIリクエストには、以下のヘッダーを必ず含めてください。
ィールド名区分説明
Content-Type必須データの送信形式をJSONに指定します。
api-key必須［認証キー］管理画面の設定から発行されたAPI Keyです。
requestId必須［トラッキングキー］リクエストごとに新しく生成する一意の識別子です。（エラー追跡用）
Idempotency-Key必須［重複防止キー］ネットワークエラーなどによる重複処理を防止するためのキーです。
{% hint style="success" %} **Idempotency Key** のフォーマット詳細 genser APIでは、UUID Version 4標準の使用を推奨しています。 * **推奨形式:** ハイフン（-）を含む標準形式 * **文字数:** * **標準（推奨）:** ハイフンを含めて全36文字 (例: `550e8400-e29b-41d4-a716-446655440000`) * **代替形式:** ハイフンを除いた全32文字 (例: `550e8400e29b41d4a716446655440000`) {% endhint %} **HTTP リクエストヘッダーの例:** ``` POST /actions/cart/add HTTP/1.1 Host: api.gelatto.ai Content-Type: application/json api-key: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 requestId: req-20260112-001 ``` {% endstep %} {% step %} ## データを送信する (Send Data) ユーザーの行動が発生したタイミング（ボタンのクリック、ページの読み込みなど）に合わせて、該当するAPIを呼び出します。以下のケース別JSONサンプルを参考に、データを送信してください。各フィールドの詳細な仕様については、それぞれの［APIリファレンス］をご確認ください。 {% hint style="info" %} 以下のリクエストBodyは、連携時のサンプルです。任意（Optional）フィールドは、お客様側で収集可能な場合にのみ送信してください。収集しないフィールドはリクエストから除外できます。 {% endhint %} #### カート **(Cart)** **カートに追加 (Add to Cart)** ユーザーが「カートに追加」ボタンをクリックした際に呼び出します。 **Path**: `/actions/cart/add`
リクエスト本文（Body）のコードサンプル ```js { "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）のコードサンプル ```js { "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）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-START-CHECKOUT-001", "type": "start_checkout", "time": "2025-12-02T10:20:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "CheckoutAction", "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/purchase/checkout" } } } ```
**購入完了 (Complete Purchase)** 決済が正常に完了したタイミング（注文完了ページ）で呼び出します。**最も重要なデータです。** **Path**: `/actions/purchase/complete`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-COMPLETE-PURCHASE-001", "type": "complete_purchase", "time": "2025-12-02T10:25:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "OrderAction", "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/purchase/complete" } } } ```
**決済キャンセル (Cancel Purchase)** ユーザーが決済をキャンセル、または注文を取り消した際に呼び出します。 **Path**: `/actions/purchase/cancel`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-CANCEL-PURCHASE-001", "type": "cancel_purchase", "time": "2025-12-02T11:00:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "CancelAction", "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/purchase/cancel" } } } ```
#### 検索 (Search) **検索キーワード送信 (Search Submitted)** ユーザーが検索ボックスにキーワードを入力し、Enterキーを押す、または虫眼鏡アイコンをクリックして検索を実行した際に呼び出します。 **Path**: `/actions/search/submitted`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-SEARCH-SUBMITTED-001", "type": "search_submitted", "time": "2025-11-28T10:00:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "SearchAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ], "gender": "Female", "additionalProperty": [ { "@type": "PropertyValue", "propertyID": "age", "value": 18 } ] }, "query": "快適なソファを探して", "object": { "@type": "Thing", "actionOption": [ { "@type": "PropertyValue", "propertyID": "search_type", "value": "AI" }, { "@type": "PropertyValue", "propertyID": "color", "value": "ブラック" } ] }, "target": { "@type": "EntryPoint", "urlTemplate": "https://shop.example.com/search?color=ブラック" } } } ```
**検索結果の表示 (View Search Result)** 検索結果一覧ページが読み込まれた際に呼び出します。 **Path**: `/actions/search/result`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-VIEW-SEARCH-RESULT-001", "type": "view_search_result", "time": "2025-11-28T10:00:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "ViewAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ] }, "object": { "@type": "ItemList", "numberOfItems": 1, "itemListElement": { "@type": "ListItem", "item": { "@type": "Product", "sku": "131776", "name": "ソイ 3人掛けソファ" }, "position": 1 } }, "target": { "@type": "EntryPoint", "urlTemplate": "https://shop.example.com/search" } } } ```
#### 商品 (Product) **商品詳細の表示 (View Product)** 商品詳細ページ（PDP）に遷移した際に呼び出します。 **Path**: `/actions/view/product`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-VIEW-PRODUCT-001", "type": "view_product", "time": "2025-11-28T10:00:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "ViewAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ] }, "object": { "@type": "Product", "sku": "131776", "name": [ { "@value": "ソイ 3人掛けソファ", "@language": "ja" } ] }, "target": { "@type": "EntryPoint", "urlTemplate": "https://shop.example.com/product/131776" } } } ```
**商品クリック (Click Product)** 一覧上の特定の商品をクリックした際に呼び出します。 **Path**: `/actions/click/product`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-CLICK-PRODUCT-001", "type": "click_product", "time": "2025-11-28T10:00:00Z", "source": "https://shop.example.com", "data": { "@context": "https://schema.org/", "@type": "ChooseAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ] }, "object": { "@type": "ItemList", "itemListElement": { "@type": "ListItem", "position": 1, "item": { "@type": "Product", "sku": "131776", "name": [ { "@value": "ソイ 3人掛けソファ", "@language": "ja" } ] } } }, "target": { "@type": "EntryPoint", "urlTemplate": "https://shop.example.com/product/131776" } } } ```
#### ウィッシュリスト (Wishlist) **ウィッシュリストに追加 (Add to Wishlist)** 「お気に入り」または「ウィッシュリストに追加」ボタンをクリックした際に呼び出します。 **Path**: `/actions/wishlist/add=`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-ADD-TO-WISHLIST-001", "type": "add_to_wishlist", "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" } ] }, "object": { "@type": "OrderItem", "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/wishlist" } } } ```
**ウィッシュリストから削除 (Remove from Wishlist)** ウィッシュリストから商品を削除した際に呼び出します。 **Path**: `/actions/wishlist/remove`
リクエスト本文（Body）のコードサンプル ```js { "specversion": "1.0.0", "id": "EVT-REMOVE-FROM-WISHLIST-001", "type": "remove_from_wishlist", "time": "2025-12-02T10:05: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", "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/wishlist" } } } ```
{% endstep %} {% step %} ## レスポンスを確認する (Check Response) API呼び出し後、HTTPステータスコードを確認し、データ送信が正常に完了したかを判断します。
ステータスコード結果説明
200 OK成功正常に処理されました。翌日0:15のバッチ処理で反映されます。
400 Bad Requestリクエスト形式エラーJSONの構文に誤りがないか、または必須項目（sku、nameなど）が不足していないかをご確認ください。
401 Unauthorized認証エラーapi-keyが無効、または指定されていません。
500 Internal Errorサーバーエラー一時的な障害の可能性があります。時間を置いてから再試行（Retry）処理を実行してください。
{% endstep %} {% step %} ## 連携結果を確認する (Verify) - 今後提供予定 API連携後、データが正常に蓄積されているかを管理画面から確認できます。 {% endstep %} {% endstepper %}