> 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/product-collection/parameter-1.md). # \[Archive] リクエストパラメータ説明 {% hint style="info" %} gelatto リクエストデータについて説明します。詳しいAPIリクエスト方式は[gelatto 商品収集API](broken://pages/65d437d160fd84be8cc0a9146d7c1db69c5e01fb)をご参照ください。 {% endhint %} ## **共通データ構造** ### 多言語テキストフィールド 商品名、ブランド名、カテゴリ名などのテキストフィールドは、3つの形式をサポートしています。 **形式 1. 単純文字列** ```json "name": "クラシックTシャツ" ``` **形式 2. 言語指定オブジェクト** ```json "name": { "@value": "クラシックTシャツ", "@language": "ja" } ``` **形式 3. 多言語配列** 対応言語コード（ISO 639-1）：`ko`、`en`、`ja` ```json "name": [ { "@value": "클래식 티셔츠", "@language": "ko" }, { "@value": "Classic T-Shirt", "@language": "en" }, { "@value": "クラシックTシャツ", "@language": "ja" } ] ``` {% hint style="info" %} 言語指定オブジェクト（形式 2、3）を使用する場合、`@value`と`@language`はどちらも必須です。`@language`を省略すると`400`エラーが返されます。すべての言語を必ず提供する必要はなく、必要な言語のみを送信できます。 {% endhint %} ### データ入力ルール * **必須フィールドとnull**：フィールド仕様表で必須（O）と表記されているフィールドには、必ず有効な値を含める必要があります。必須フィールドに`null`を送信すると`400`エラーが返されます。任意（X）フィールドは省略するか、`null`で送信できます。 * **文字列（string）**：特別な`maxLength`制約はなく、適切な長さで送信することを推奨します。 * **数値（number）**：特別な小数点精度の規約はなく、通貨に合わせた一般的な桁数を使用します（例：JPYは整数、USDは小数点以下2桁）。 * **enum**：許可される値が指定されているフィールドは、Enum値リファレンスセクションにまとめています。明示された値以外を送信すると`400`エラーが返されます。 * **フィールド間の依存関係**：特定フィールドの値によって他のフィールドの必須可否が変わる条件付き必須ルールは適用されません。フィールド仕様表の必須可否のみを基準にデータを構成します。 * `@graph`配列には、最小1件、最大1,000件の商品を含めることができます。 * API仕様書に記載されたすべてのフィールドは`null`を許容しません。 *** ## **フィールド詳細仕様** #### イベントオブジェクト（CollectorProductsEvent） | フィールド | タイプ | 必須 | 説明 | | ------------- | ------ | -- | ------------------------------------------------------------- | | `@context` | string | X | スキーマcontext。固定値：`"https://schema.org"` | | `specversion` | string | X | スペックバージョン。固定値：`"1.0"` | | `id` | string | X | イベント固有識別子。登録：`"EVT-CREATE-PRODUCT"`、修正：`"EVT-UPDATE-PRODUCT"` | | `type` | string | X | イベントタイプ。登録：`"create_product"`、修正：`"update_product"` | | `agent` | object | O | リクエスト元情報 | | `@graph` | array | O | 商品データ配列（1〜1,000件） | #### agentオブジェクト | フィールド | タイプ | 必須 | 説明 | | ------- | ------ | -- | ------------------------ | | `@type` | string | X | タイプ。固定値：`"Organization"` | | `name` | string | O | リクエスト企業名 | #### 商品オブジェクト（@graph） `@graph`配列の各項目は1つの商品を表します。 | フィールド | タイプ | 必須 | 説明 | | ----------------------- | ------------------------- | -- | ------------------- | | `@type` | string | X | タイプ。固定値：`"Product"` | | `sku` | string | O | 商品コード（一意の識別子） | | `name` | string \| object \| array | O | 商品名。多言語対応 | | `description` | object \| array | O | 商品説明 | | `brand` | object | O | ブランド情報 | | `category` | object \| array | O | カテゴリ情報 | | `positiveNotes` | string \| object \| array | X | 主な特徴・利点の要約。多言語対応 | | `url` | string \| object \| array | O | 商品ページURL。多言語対応 | | `mobileUrl` | string \| object \| array | X | モバイル商品ページURL。多言語対応 | | `itemCondition` | string | X | 商品状態。enum参照 | | `hasAdultConsideration` | string | X | 成人向け商品区分。enum参照 | | `countryOfOrigin` | object | X | 製造国情報 | | `material` | string \| object \| array | X | 素材情報。多言語対応 | | `additionalProperty` | array | X | 追加属性 | | `offers` | object \| array | O | SKU別価格・在庫情報 | #### countryOfOriginオブジェクト | フィールド | タイプ | 必須 | 説明 | | --------- | ------ | -- | ------------------------------------------------- | | `@type` | string | X | タイプ。固定値：`"Country"` | | `address` | string | O | 製造国コード（ISO 3166-1 alpha-2、例：`"JP"`、`"KR"`、`"US"`） | #### ブランド（brand） | フィールド | タイプ | 必須 | 説明 | | ------- | ------------------------- | -- | ----------------- | | `@type` | string | X | タイプ。固定値：`"Brand"` | | `@id` | string | O | ブランド識別子 | | `name` | string \| object \| array | O | ブランド名。多言語対応 | | `logo` | array\ | X | ブランドロゴURL一覧 | #### カテゴリ（category） 単一オブジェクトまたは配列で送信します。配列を使用する場合、`position`値でカテゴリ階層レベルを表現します。 | フィールド | タイプ | 必須 | 説明 | | ----------- | --------------- | -- | --------------------------- | | `@type` | string | X | タイプ。固定値：`"CategoryCode"` | | `codeValue` | string | O | カテゴリコード | | `name` | object \| array | O | カテゴリ名。多言語対応 | | `position` | integer | O | カテゴリ階層（1 = 大分類、2 = 中分類、...） | #### **商品説明（description）** | フィールド | タイプ | 必須 | 説明 | | -------------------- | --------------- | -- | ------------------------------- | | `@type` | string | X | タイプ。固定値：`"TextObject"` | | `text` | string | O | 説明テキスト | | `inLanguage` | string | O | 言語コード（ISO 639-1）：`ko`、`en`、`ja` | | `image` | object \| array | X | 説明に含まれる画像情報 | | `additionalProperty` | array | X | 追加属性 | #### **description内の画像オブジェクト** | フィールド | タイプ | 必須 | 説明 | | ------------ | ------ | -- | ----------------------- | | `@type` | string | X | タイプ。固定値：`"ImageObject"` | | `contentUrl` | string | X | 画像URL | | `inLanguage` | string | X | 言語コード | #### **価格・在庫情報（offers）** 単一オブジェクトまたは配列で送信します。カラー・サイズなどのオプション別に個別のofferを構成します。 | フィールド | タイプ | 必須 | 説明 | | -------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------ | | `@type` | string | X | タイプ。固定値：`"Offer"` | | `sku` | string | O | オプション別商品コード | | `gtin` | string | O |

国際標準バーコード

最大50桁の数字（1文字あたり最大14文字、追加された空白やハイフンは無視されます）

値：
49123456 4901234567894

| | `mpn` | string | O |

メーカー品番
最大70文字の英数字
値：GO12345OOGLE

| | `price` | number | O | 価格 | | `priceCurrency` | string | O | 通貨コード（ISO 4217、例：`"JPY"`、`"KRW"`、`"USD"`） | | `priceSpecification` | object \| array | X | 価格タイプ詳細 | | `color` | string | O | カラー | | `size` | string | O | サイズ | | `availability` | string | O | 在庫状態。enum参照 | | `availabilityStarts` | string | O | 販売開始日時（UTC ISO 8601） | | `availabilityEnds` | string | O | 販売終了日時（UTC ISO 8601） | | `inventoryLevel` | object | X | 在庫数量情報 | | `shippingDetails` | object | X | 配送情報 | | `image` | object \| array | O | 商品画像 | | `additionalProperty` | array | X | 追加属性 | #### inventoryLevelオブジェクト | フィールド | タイプ | 必須 | 説明 | | ------- | ------ | -- | ----------------------------- | | `@type` | string | X | タイプ。固定値：`"QuantitativeValue"` | | `value` | number | O | 在庫数量 | #### shippingDetailsオブジェクト | フィールド | タイプ | 必須 | 説明 | | -------- | ------ | -- | -------------------------------- | | `@type` | string | X | タイプ。固定値：`"OfferShippingDetails"` | | `weight` | object | O | 配送重量 | #### shippingDetails.weightオブジェクト | フィールド | タイプ | 必須 | 説明 | | ---------- | ------ | -- | ----------------------------- | | `@type` | string | X | タイプ。固定値：`"QuantitativeValue"` | | `value` | number | O | 重量値 | | `unitCode` | string | O | 単位コード（例：`"KGM"`、`"GRM"`） | #### 価格タイプ（priceSpecification） 定価、販売価格、メーカー希望小売価格など、さまざまな価格タイプを表現します。 | フィールド | タイプ | 必須 | 説明 | | --------------- | ------ | -- | ---------------------------------- | | `@type` | string | X | タイプ。固定値：`"UnitPriceSpecification"` | | `priceType` | string | O | 価格区分。enum参照 | | `price` | number | O | 価格 | | `priceCurrency` | string | O | 通貨コード（ISO 4217） | | `unitCode` | string | O | 単位コード | #### 画像（image） | フィールド | タイプ | 必須 | 説明 | | ---------------------- | ------- | -- | ---------------------------------------------------- | | `@type` | string | X | タイプ。固定値：`"ImageObject"` | | `representativeOfPage` | boolean | X | 代表画像かどうか（`true` = 代表画像） | | `contentUrl` | string | O | 画像URL | | `contentSize` | string | X | ファイルサイズ | | `width` | object | X | 幅（`{ "@type": "QuantitativeValue", "value": 800 }`） | | `height` | object | X | 高さ（`{ "@type": "QuantitativeValue", "value": 600 }`） | #### 追加属性（additionalProperty） 標準フィールドでは表現できない追加情報を格納するための拡張フィールドです。 商品オブジェクト（`@graph[]`）、商品説明（`description`）、価格情報（`offers`）内で使用できます。 | フィールド | タイプ | 必須 | 説明 | | ------------ | ------ | -- | --------------------------------------------- | | `@type` | string | X | タイプ。固定値：`"PropertyValue"` | | `propertyID` | string | X | 属性ID（属性を区別するキー） | | `value` | any | X | 値（string、number、boolean、arrayなど、すべてのタイプが使用可能） | 商品オブジェクト（`@graph[]`）内に値を送信することを推奨します。 **属性リファレンス** 以下は`additionalProperty`で使用できる推奨属性の一覧です。許可値の例を参考にして、値のフォーマットを合わせて送信してください。
propertyIDvalueタイプ説明許可値 / 例
genderstring性別Enum値リファレンスのgender参照
seasonstring[]季節Enum値リファレンスのseason参照
temperaturestring保管方法自由値。例："Refrigerate"
platform_ratenumberプラットフォーム手数料0.15
unitobject梱包・重量情報サブフィールド：unit、unit_quantity、weight_unit、weight_quantity
sellerobject販売者情報サブフィールド：prefecture、seller_name
**unitオブジェクト構造** | サブフィールド | タイプ | 説明 | 例 | | ----------------- | ------ | -------- | ----------------------- | | `unit` | string | 梱包単位。自由値 | `"box"`、`"pack"`、`"ea"` | | `unit_quantity` | number | 梱包数量 | `500` | | `weight_unit` | string | 重量単位 | `"g"`、`"ml"` | | `weight_quantity` | number | 重量値 | `500` | **sellerオブジェクト構造** | サブフィールド | タイプ | 説明 | 例 | | ------------- | ------ | ----- | ------------------------ | | `prefecture` | string | 産地・地域 | `"秋田県"`、`"済州島"`など | | `seller_name` | string | 販売者名 | `"きのこ農園"`、`"ユースファーマー"`など | **使用例** ```json "additionalProperty": [ { "@type": "PropertyValue", "propertyID": "gender", "value": "M" }, { "@type": "PropertyValue", "propertyID": "season", "value": ["Spring", "Summer"] }, { "@type": "PropertyValue", "propertyID": "temperature", "value": "Refrigerate" }, { "@type": "PropertyValue", "propertyID": "platform_rate", "value": 0.15 }, { "@type": "PropertyValue", "propertyID": "unit", "value": { "unit": "box", "unit_quantity": 500, "weight_unit": "g", "weight_quantity": 500 } }, { "@type": "PropertyValue", "propertyID": "seller", "value": { "prefecture": "秋田県", "seller_name": "間木きのこ農園" } } ] ``` `unit`属性の`weight_unit`は`g`または`ml`に統一して送信します。 元データが`kg`の場合は`g`に、`L`の場合は`ml`に変換してください。 ## **Enum値リファレンス** #### itemCondition 商品の物理的な状態を表します。 | 値 | 説明 | | ---------------------- | --------- | | `NewCondition` | 新品 | | `RefurbishedCondition` | リファービッシュ品 | | `UsedCondition` | 中古品 | | `DamagedCondition` | 損傷品 | #### hasAdultConsideration 成人向け商品かどうかを区分します。 | 値 | 説明 | | ------------------------------------------ | --------- | | `AlcoholConsideration` | 酒類 | | `DangerousGoodConsideration` | 危険物 | | `HealthcareConsideration` | 医薬品・医療機器 | | `NarcoticConsideration` | 麻薬類 | | `ReducedRelevanceForChildrenConsideration` | 児童不適切 | | `SexualContentConsideration` | アダルトコンテンツ | | `TobaccoNicotineConsideration` | たばこ・ニコチン | | `UnclassifiedAdultConsideration` | その他成人向け | | `ViolenceConsideration` | 暴力性 | | `WeaponConsideration` | 武器類 | #### availability SKUの在庫・販売状態を表します。 | 値 | 説明 | | --------------------- | ---------- | | `BackOrder` | 入荷予定（注文可能） | | `Discontinued` | 販売終了 | | `InStock` | 在庫あり | | `InStoreOnly` | 店頭販売のみ | | `LimitedAvailability` | 数量限定 | | `MadeToOrder` | 受注生産 | | `OnlineOnly` | オンライン限定 | | `OutOfStock` | 在庫切れ | | `PreOrder` | 予約注文 | | `PreSale` | 先行販売 | | `Reserved` | 予約済み | | `SoldOut` | 完売 | #### priceType 価格の性質を区分します。 | 値 | 説明 | | ------------------------ | -------------- | | `InvoicePrice` | 請求価格 | | `ListPrice` | 定価 | | `MSRP` | メーカー希望小売価格 | | `MinimumAdvertisedPrice` | 最低広告価格 | | `RegularPrice` | 通常販売価格 | | `SRP` | 推奨小売価格 | | `SalePrice` | セール価格 | | `StrikethroughPrice` | 取消線価格（元の価格表示用） | #### gender `additionalProperty`の`propertyID`が`gender`の場合に使用します。 | 値 | 説明 | | --- | ------ | | `M` | Men | | `W` | Women | | `U` | Unisex | #### season `additionalProperty`の`propertyID`が`season`の場合に使用します。複数指定する場合は文字列配列で送信してください。 | 値 | 説明 | | -------- | -- | | `Spring` | 春 | | `Summer` | 夏 | | `Fall` | 秋 | | `Winter` | 冬 | #### weight\_unit `additionalProperty`の`propertyID`が`unit`の場合、`value.weight_unit`で使用します。 | 値 | 説明 | | ---- | ------ | | `g` | グラム | | `ml` | ミリリットル | *** ## **参考：JSONスキーマ例**
商品登録 ```json "type": "string", "description": "カラー" }, "size": { "type": "string", "description": "サイズ" }, "availability": { "type": "string", "description": "在庫状態", "enum": [ "BackOrder", "Discontinued", "InStock", "InStoreOnly", "LimitedAvailability", "MadeToOrder", "OnlineOnly", "OutOfStock", "PreOrder", "PreSale", "Reserved", "SoldOut" ] }, "availabilityStarts": { "type": "string", "description": "ISO 8601 UTC販売開始日時（例：2025-11-28T10:00:00Z）", "pattern": "Z$" }, "availabilityEnds": { "type": "string", "description": "ISO 8601 UTC販売終了日時（例：2025-11-28T10:00:00Z）", "pattern": "Z$" }, "inventoryLevel": { "type": "object", "description": "在庫数量情報", "properties": { "@type": { "type": "string", "description": "https://schema.org/QuantitativeValue", "enum": [ "QuantitativeValue" ], "default": "QuantitativeValue" }, "value": { "type": "number", "description": "在庫数量" } }, "required": [ "value" ] }, "shippingDetails": { "type": "object", "description": "配送情報", "properties": { "@type": { "type": "string", "description": "https://schema.org/OfferShippingDetails", "enum": [ "OfferShippingDetails" ], "default": "OfferShippingDetails" }, "weight": { "type": "object", "description": "配送重量", "properties": { "@type": { "type": "string", "description": "https://schema.org/QuantitativeValue", "enum": [ "QuantitativeValue" ], "default": "QuantitativeValue" }, "value": { "type": "number", "description": "配送重量" }, "unitCode": { "type": "string", "description": "配送重量の単位" } }, "required": [ "value", "unitCode" ] } }, "required": [ "weight" ] }, "image": { "oneOf": [ { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/image" } }, { "$ref": "#/$defs/image" } ] }, "additionalProperty": { "type": "array", "description": "追加情報", "minItems": 1, "items": { "type": "object", "properties": { "@type": { "type": "string", "description": "https://schema.org/PropertyValue", "enum": [ "PropertyValue" ], "default": "PropertyValue" }, "propertyID": { "type": "string", "description": "属性ID" }, "value": { "description": "属性値" } } } } }, "required": [ "sku", "gtin", "mpn", "price", "priceCurrency", "color", "size", "availability", "availabilityStarts", "availabilityEnds", "image" ] } } } ```
商品修正 ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "顧客企業 商品収集 - 商品修正", "description": "顧客企業の商品データ修正", "type": "object", "properties": { "@context": { "type": "string", "description": "context", "enum": [ "https://schema.org" ], "default": "https://schema.org" }, "specversion": { "type": "string", "description": "スペックバージョン", "enum": [ "1.0" ], "default": "1.0" }, "id": { "type": "string", "description": "イベント固有識別子", "enum": [ "EVT-UPDATE-PRODUCT" ], "default": "EVT-UPDATE-PRODUCT" }, "type": { "type": "string", "description": "商品修正タイプ", "enum": [ "update_product" ], "default": "update_product" }, "agent": { "type": "object", "description": "組織情報", "required": [ "name" ], "properties": { "@type": { "type": "string", "description": "組織", "enum": [ "Organization" ], "default": "Organization" }, "name": { "type": "string", "description": "修正をリクエストした企業" } } }, "@graph": { "type": "array", "description": "商品データ", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "@type": { "type": "string", "description": "https://schema.org/Product", "enum": [ "Product" ], "default": "Product" }, "sku": { "type": "string", "description": "商品コード" }, "name": { "description": "商品名", "oneOf": [ { "type": "array", "items": { "$ref": "#/$defs/langName" } }, { "$ref": "#/$defs/langName" }, { "type": "string" } ] }, "description": { "oneOf": [ { "type": "array", ```
商品削除 ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "顧客企業 商品収集 - 商品削除", "description": "顧客企業の商品データ削除リクエスト収集", "type": "object", "properties": { "@context": { "type": "string", "description": "context", "enum": [ "https://schema.org" ], "default": "https://schema.org" }, "specversion": { "type": "string", "description": "スペックバージョン", "enum": [ "1.0" ], "default": "1.0" }, "id": { "type": "string", "description": "イベント固有識別子", "enum": [ "EVT-DELETE-PRODUCT" ], "default": "EVT-DELETE-PRODUCT" }, "type": { "type": "string", "description": "商品削除タイプ", "enum": [ "delete_product" ], "default": "delete_product" }, "agent": { "type": "object", "description": "組織情報", "required": [ "name" ], "properties": { "@type": { "type": "string", "description": "組織", "enum": [ "Organization" ], "default": "Organization" }, "name": { "type": "string", "description": "削除をリクエストした企業" } } }, "@graph": { "type": "array", "description": "商品データ", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "@type": { "type": "string", "description": "https://schema.org/Product", "enum": [ "Product" ], "default": "Product" }, "sku": { "type": "string", "description": "商品コード" } }, "required": [ "sku" ] } } }, "required": [ "@graph" ] } ```
####