# 標準 API 直接連携

<figure><img src="/files/OhJGBR73UVEhyVbxXhnm" alt=""><figcaption></figcaption></figure>

標準API直接連携は、顧客の製品情報をAPIを通じてgenserに直接送信する方式です。

***

genserの直接連携APIは、データの拡張性と相互運用性のために次のようなグローバル技術標準を準拠します。

* **JSON-LD & Schema.org:** データに意味を与える構造化データフォーマットを使用し、Vertex AIが製品の文脈を完全に理解できるように支援します。
* **CloudEvents:** すべての製品情報の変更を「イベント」として扱い、システム間の信頼性のあるデータ交換を保証します。

{% stepper %}
{% step %}

### 連携の準備 (Prepare)

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

* **APIエンドポイント:** `https://api.genser.app/collectors/products`
* **メソッド:** `POST`
* **Content-Type:** `application/json` (または `application/ld+json`)
* **サービスキー:** genser管理画面の\[設定]メニューで発行された `apiKey`

> **データ反映時刻の案内**
>
> APIで送信されたデータは即時に検索結果に表示されるわけではなく、該当国の現地時間で毎日午前00:15に実行されるバッチ処理により検索エンジンへ反映されます。
> {% endstep %}

{% step %}

### 認証 (Authenticate)

genser APIは複雑なトークン交換方式の代わりに、ヘッダーにキー値を直接含める簡便な方式を使用します。管理画面で発行された **Service Key**をご準備ください。（`genser管理 > 設定` で確認可能）

* **ヘッダー名:** `apiKey`
* **値:** 発行されたキー値をそのまま入力（Base64エンコード不要）

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

```
POST /searches/products HTTP/1.1
Host: api.genser.app
Content-Type: application/json
apiKey: cb37cce9d6ae434fa366151b3420a9af //発行されたサービスキー
```

{% endstep %}

{% step %}

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

新規商品を登録する場合や、既存商品の情報（価格、在庫など）が変更されたときに以下の形式でデータを送信します。 **JSON-LD** および **CloudEvents** 標準規格に従います。

**リクエスト本文 (Request Body)**

商品収集APIを呼び出す際に本文（Body）に含めるべき最上位フィールドです。詳細な商品情報は `@graph` オブジェクトに入れて送信します。

<table><thead><tr><th width="117.11328125">フィールド名</th><th width="96.91015625">型</th><th width="79.609375">区分</th><th>説明</th></tr></thead><tbody><tr><td>@context</td><td>文字列</td><td>推奨</td><td>JSON-LDデータの基準辞書定義（値: <code>https://schema.org/</code>)</td></tr><tr><td>specversion</td><td>文字列</td><td>推奨</td><td>CloudEventsスペックバージョン（値: <code>1.0</code>)</td></tr><tr><td>id</td><td>文字列</td><td>推奨</td><td>リクエストごとの固有識別子（UUIDなど）</td></tr><tr><td>type</td><td>文字列</td><td>推奨</td><td>イベントタイプ（例: create_product）</td></tr><tr><td>agent</td><td>オブジェクト</td><td>必須</td><td>データを送信する主体（システム）の識別値</td></tr><tr><td>@graph</td><td>オブジェクト</td><td>必須</td><td>実際の製品情報を含むProductオブジェクトのリスト</td></tr></tbody></table>

**リソースオブジェクト (Resource Objects)**

<table><thead><tr><th width="174.95703125">フィールド名</th><th width="89.03515625">型</th><th width="80.3671875">区分</th><th>説明</th></tr></thead><tbody><tr><td>@type</td><td>文字列</td><td>必須</td><td>オブジェクトタイプ定義（値: <code>Product</code>)</td></tr><tr><td>sku</td><td>文字列</td><td>必須</td><td>社内で商品を区別する管理コード（例: A001-Red）</td></tr><tr><td>name</td><td>文字列</td><td>必須</td><td>顧客に表示される実際の商品の名前</td></tr><tr><td>category</td><td>オブジェクト</td><td>必須</td><td>サイトに陳列されるカテゴリ分類（例: 服 > メンズ > Tシャツ）</td></tr><tr><td>└ @type</td><td>文字列</td><td>必須</td><td>オブジェクトタイプ定義（値: <code>CategoryCode</code>)</td></tr><tr><td>└ name</td><td>文字列</td><td>必須</td><td>カテゴリ名称（例: スニーカー、アウター）</td></tr><tr><td>└ code</td><td>文字列</td><td>推奨</td><td>カテゴリ分類コード</td></tr><tr><td>brand</td><td>オブジェクト</td><td>必須</td><td>この商品を作ったブランド情報</td></tr><tr><td>└ @type</td><td>文字列</td><td>任意</td><td>オブジェクトタイプ定義（値: <code>Brand</code>)</td></tr><tr><td>└ id</td><td>文字列</td><td>必須</td><td>ブランドID</td></tr><tr><td>└ name</td><td>オブジェクト</td><td>必須</td><td>ブランド名、ブランド名の表記言語コード（例: ko）</td></tr><tr><td>description</td><td>オブジェクト</td><td>必須</td><td>商品説明、言語コード、商品説明の付加情報等</td></tr><tr><td>offers</td><td>オブジェクト</td><td>必須</td><td>価格および在庫情報オブジェクト</td></tr><tr><td>└ @type</td><td>文字列</td><td>任意</td><td>オブジェクトタイプ定義（値: <code>Offer</code>)</td></tr><tr><td>└ sku</td><td>文字列</td><td>必須</td><td>販売用SKU</td></tr><tr><td>└ gtin</td><td>文字列</td><td>必須</td><td>世界的に通用する製品固有番号（例: 880で始まるバーコード、EAN/UPC）</td></tr><tr><td>└ mpn</td><td>文字列</td><td>必須</td><td>メーカーが付与した部品番号や型番</td></tr><tr><td>└ price</td><td>数値</td><td>必須</td><td>顧客が実際に支払う最終販売金額</td></tr><tr><td>└ priceCurrency</td><td>文字列</td><td>必須</td><td>支払い通貨の基準（韓国はKRW、米国はUSDなど）</td></tr><tr><td>└ availability</td><td>文字列</td><td>必須</td><td>現在購入可能かどうか（値: <code>InStock, OutOfStock, PreOrder</code>)</td></tr><tr><td>└ availabilityStarts</td><td>日付</td><td>必須</td><td>商品販売が開始される日時（2025-11-28T10:00:00Z）</td></tr><tr><td>└ availabilityEnds</td><td>日付</td><td>必須</td><td>商品販売を終了する日時（2025-11-28T10:00:00Z）</td></tr><tr><td>└ shippingDetails</td><td>オブジェクト</td><td>任意</td><td>配送情報</td></tr><tr><td>└ image</td><td>オブジェクト</td><td>必須</td><td>商品画像</td></tr><tr><td>additionalProperty</td><td>配列</td><td>任意</td><td>関税申告用のHSコードやエコタグなど特殊な追加情報</td></tr><tr><td>└ @type</td><td>文字列</td><td>任意</td><td>情報がどのような形式かを定義（値: <code>PropertyValue</code>)</td></tr><tr><td>└ propertyID</td><td>文字列</td><td>任意</td><td><p>情報のラベル（ID）<br></p><ul><li><code>html</code>: ウェブ用のHTML説明</li><li><code>seo_title</code>: 検索表示用タイトル</li><li><code>hsCode</code>: 通関用関税コード</li><li><code>sustainabilityTags</code>: 環境配慮タグ</li></ul></td></tr><tr><td>└ value</td><td>文字列</td><td>任意</td><td>ラベルに対応する実際の内容（例: ラベルが <code>hsCode</code>なら、値は <code>851762</code>)</td></tr></tbody></table>

<details>

<summary><strong>リクエスト本文サンプルコード例</strong></summary>

```js
{
  "@context": "https://schema.org/",
  "specversion": "1.0",
  "id": "EVT-CREATE-PRODUCT",
  "type": "create_product",
  "agent": {
    "@type": "Organization",
    "name": "ExampleCorp"
  },
  "@graph": [
    {
      "@type": "Product",
      "sku": "PROD-001-A",
      "name": {
        "@value": "プレミアムBluetoothイヤホン",
        "@language": "ko"
      },
      "description": [
        {
          "@type": "TextObject",
          "text": "完全ワイヤレスBluetoothイヤホンで高音質サウンドと快適な装着感を提供します。",
          "inLanguage": "ko",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>完全ワイヤレスBluetoothイヤホンで <strong>高音質サウンド</strong>と快適な装着感を提供します。</p>"
            },
            {
              "@type": "PropertyValue",
              "propertyID": "seo_title",
              "value": "プレミアムBluetoothイヤホン - 高音質ワイヤレスイヤホン"
            },
            {
              "@type": "PropertyValue",
              "propertyID": "seo_description",
              "value": {
                "@value": "高音質完全ワイヤレスイヤホン、長時間装着でも快適なプレミアム製品",
                "@language": "ko"
              }
            }
          ]
        }
      ],
      "brand": {
        "@type": "Brand",
        "@id": "brand-001",
        "name": {
          "@value": "サウンドマックス",
          "@language": "ko"
        },
        "logo": "https://example.com/brand/soundmax-logo.png"
      },
      "category": [
        {
          "@type": "CategoryCode",
          "codeValue": "ELEC001",
          "name": {
            "@value": "電子機器",
            "@language": "ko"
          },
          "position": 1
        },
        {
          "@type": "CategoryCode",
          "codeValue": "AUDIO005",
          "name": {
            "@value": "オーディオ機器",
            "@language": "ko"
          },
          "position": 2
        }
      ],
      "positiveNotes": {
        "@value": "高音質、長時間バッテリー、快適な装着感",
        "@language": "ko"
      },
      "url": {
        "@value": "https://example.com/product/P001",
        "@language": "ko"
      },
      "itemCondition": "NewCondition",
      "hasAdultConsideration": "UnclassifiedAdultConsideration",
      "countryOfOrigin": {
        "@type": "Country",
        "address": "KR"
      },
      "material": {
        "@value": "プラスチック、シリコーン",
        "@language": "ko"
      },
      "offers": {
        "@type": "Offer",
        "sku": "PROD-001-A",
        "gtin": "8801234567890",
        "mpn": "SM-EAR-2025",
        "price": 129000,
        "priceCurrency": "KRW",
        "priceSpecification": {
          "@type": "UnitPriceSpecification",
          "price": 129000,
          "unitCode": "EA"
        },
        "availability": "InStock",
        "availabilityStarts": "2025-11-28T10:00:00Z",
        "availabliltyEnds": "2026-12-31T23:59:59Z", 
        "inventoryLevel": {
          "@type": "QuantitativeValue",
          "value": 250
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "weight": {
            "@type": "QuantitativeValue",
            "value": 0.2,
            "unitCode": "KG"
          }
        },
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://example.com/product/P001/main.jpg",
            "contentSize": "350KB",
            "width": {
              "@type": "QuantitativeValue",
              "value": 1080
            },
            "height": {
              "@type": "QuantitativeValue",
              "value": 1080
            }
          }
        ]
      },
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "propertyID": "hsCode",
          "value": "851762"
        },
        {
          "@type": "PropertyValue",
          "propertyId": "sustainabilityTags", 
          "value": ["lowEnergyConsumption", "recyclablePackaging"]
        }
      ]
    }
  ]
}
```

</details>

**多言語情報連携 (Multi-language Support)**

単一のリクエストで複数言語の製品情報を同時に登録できます。グローバル販売のために商品名、ブランド、カテゴリなどのテキスト情報に多言語値を設定するには、該当フィールドをJSON配列(`配列`)に変更し、言語コード(`@language`)で区別して入力してください。

* **基本原則**
  * **単一言語:** Object形式 `{ "@value": "...", "@language": "ko" }`
  * **多言語:** 配列形式 `[ { "ko" データ }, { "en" データ } ]`
* **対応フィールド:** `name`, `brand.name`, `category.name`, `positiveNotes`, `material`, `url` など
* **注意事項:** `description` フィールドは `inLanguage`属性を使用して区別します。

<details>

<summary><strong>多言語適用リクエスト本文サンプルコード例</strong></summary>

```js
{
  "@context": "https://schema.org/",
  "specversion": "1.0",
  "id": "EVT-CREATE-PRODUCT",
  "type": "create_product",
  "agent": {
    "@type": "Organization",
    "name": "ExampleCorp"
  },
  "@graph": [
    {
      "@type": "Product",
      "sku": "PROD-001-A",
      "name": [
        {
          "@value": "プレミアムBluetoothイヤホン",
          "@language": "ko"
        },
        {
          "@value": "Premium Bluetooth Earphones",
          "@language": "en"
        }
      ],
      "description": [
        {
          "@type": "TextObject",
          "text": "完全ワイヤレスBluetoothイヤホンで高音質サウンドと快適な装着感を提供します。",
          "inLanguage": "ko",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>完全ワイヤレスBluetoothイヤホン...</p>"
            }
          ]
        },
        {
          "@type": "TextObject",
          "text": "True wireless bluetooth earphones providing high-quality sound and comfortable fit.",
          "inLanguage": "en",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>True wireless bluetooth earphones...</p>"
            }
          ]
        }
      ],
      "brand": {
        "@type": "Brand",
        "@id": "brand-001",
        "name": [
          {
            "@value": "サウンドマックス",
            "@language": "ko"
          },
          {
            "@value": "SoundMax",
            "@language": "en"
          }
        ],
        "logo": "https://example.com/brand/soundmax-logo.png"
      },
      "category": [
        {
          "@type": "CategoryCode",
          "codeValue": "ELEC001",
          "name": [
             { "@value": "電子機器", "@language": "ko" },
             { "@value": "Electronics", "@language": "en" }
          ],
          "position": 1
        },
        {
          "@type": "CategoryCode",
          "codeValue": "AUDIO005",
          "name": [
             { "@value": "オーディオ機器", "@language": "ko" },
             { "@value": "Audio Devices", "@language": "en" }
          ],
          "position": 2
        }
      ],
      "positiveNotes": [
        {
          "@value": "高音質、長時間バッテリー、快適な装着感",
          "@language": "ko"
        },
        {
          "@value": "High fidelity, Long battery life, Comfortable fit",
          "@language": "en"
        }
      ],
      "url": [
        {
          "@value": "https://example.com/product/P001",
          "@language": "ko"
        },
        {
          "@value": "https://example.com/en/product/P001",
          "@language": "en"
        }
      ],
      "itemCondition": "NewCondition",
      "hasAdultConsideration": "UnclassifiedAdultConsideration",
      "countryOfOrigin": {
        "@type": "Country",
        "address": "KR"
      },
      "material": [
        {
          "@value": "プラスチック、シリコーン",
          "@language": "ko"
        },
        {
          "@value": "Plastic, Silicone",
          "@language": "en"
        }
      ],
      "offers": {
        "@type": "Offer",
        "sku": "PROD-001-A",
        "gtin": "8801234567890",
        "mpn": "SM-EAR-2025",
        "price": 129000,
        "priceCurrency": "KRW",
        "priceSpecification": {
          "@type": "UnitPriceSpecification",
          "price": 129000,
          "unitCode": "EA"
        },
        "availability": "InStock",
        "availabilityStarts": "2025-11-28T10:00:00Z",
        "availabliltyEnds": "2026-12-31T23:59:59Z",
        "inventoryLevel": {
          "@type": "QuantitativeValue",
          "value": 250
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "weight": {
            "@type": "QuantitativeValue",
            "value": 0.2,
            "unitCode": "KG"
          }
        },
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://example.com/product/P001/main.jpg",
            "contentSize": "350KB",
            "width": {
              "@type": "QuantitativeValue",
              "value": 1080
            },
            "height": {
              "@type": "QuantitativeValue",
              "value": 1080
            }
          }
        ]
      },
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "propertyID": "hsCode",
          "value": "851762"
        },
        {
          "@type": "PropertyValue",
          "propertyId": "sustainabilityTags",
          "value": ["lowEnergyConsumption", "recyclablePackaging"]
        }
      ]
    }
  ]
}
```

</details>
{% endstep %}

{% step %}

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

API呼び出し後にHTTPステータスコードを確認して送信の成否を判断します。

**ステータスコード (HTTP Status Codes)**

最初に確認すべき応答ステータスコードです。

<table><thead><tr><th width="166.3515625">ステータスコード</th><th width="117.9609375">結果</th><th>説明</th></tr></thead><tbody><tr><td>200 OK</td><td>成功</td><td>成功です。翌日00:15のバッチで反映されます。</td></tr><tr><td>400 Bad Request</td><td>リクエスト形式エラー</td><td>JSON構文が誤っているか、必須値（<code>sku</code>, <code>name</code> など）が欠落していないか確認してください。</td></tr><tr><td>401 Unauthorized</td><td>認証失敗</td><td>ヘッダーの <code>apiKey</code> 値が正しいか、空白がないか確認してください。</td></tr><tr><td>500 Internal Error</td><td>サーバーエラー</td><td>一時的な障害である可能性があります。しばらくしてから再試行（Retry）ロジックを実行してください。</td></tr></tbody></table>
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.genser.ai/ja/integration/product-data-integration/standard-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.