標準 API 直接連携

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

---

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

• JSON-LD & Schema.org: データに意味を与える構造化データフォーマットを使用し、Vertex AIが製品の文脈を完全に理解できるように支援します。

• CloudEvents: すべての製品情報の変更を「イベント」として扱い、システム間の信頼性のあるデータ交換を保証します。

1

連携の準備 (Prepare)

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

• APIエンドポイント: https://api.genser.app/collectors/products

• メソッド: POST

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

• サービスキー: genser管理画面の[設定]メニューで発行された apiKey

データ反映時刻の案内

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

2

認証 (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 //発行されたサービスキー

3

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

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

リクエスト本文 (Request Body)

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

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

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

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

リクエスト本文サンプルコード例

{
  "@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"]
        }
      ]
    }
  ]
}

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

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

• 基本原則

  • 単一言語: Object形式 { "@value": "...", "@language": "ko" }

  • 多言語: 配列形式 [ { "ko" データ }, { "en" データ } ]

• 対応フィールド: name, brand.name, category.name, positiveNotes, material, url など

• 注意事項: description フィールドは inLanguage属性を使用して区別します。

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

{
  "@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"]
        }
      ]
    }
  ]
}

4

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

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

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

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

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