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

[Archive] リクエストパラメータ説明

gelatto リクエストデータについて説明します。詳しいAPIリクエスト方式はgelatto 商品収集APIをご参照ください。

共通データ構造

多言語テキストフィールド

商品名、ブランド名、カテゴリ名などのテキストフィールドは、3つの形式をサポートしています。

形式 1. 単純文字列

"name": "クラシックTシャツ"

形式 2. 言語指定オブジェクト

"name": {
  "@value": "クラシックTシャツ",
  "@language": "ja"
}

形式 3. 多言語配列

対応言語コード（ISO 639-1）：ko、en、ja

"name": [
  { "@value": "클래식 티셔츠", "@language": "ko" },
  { "@value": "Classic T-Shirt", "@language": "en" },
  { "@value": "クラシックTシャツ", "@language": "ja" }
]

言語指定オブジェクト（形式 2、3）を使用する場合、@valueと@languageはどちらも必須です。@languageを省略すると400エラーが返されます。すべての言語を必ず提供する必要はなく、必要な言語のみを送信できます。

データ入力ルール

  • 必須フィールドと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<string>

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で使用できる推奨属性の一覧です。許可値の例を参考にして、値のフォーマットを合わせて送信してください。

propertyID
valueタイプ
説明
許可値 / 例

gender

string

性別

Enum値リファレンスのgender参照

season

string[]

季節

Enum値リファレンスのseason参照

temperature

string

保管方法

自由値。例："Refrigerate"

platform_rate

number

プラットフォーム手数料

0.15

unit

object

梱包・重量情報

サブフィールド：unit、unit_quantity、weight_unit、weight_quantity

seller

object

販売者情報

サブフィールド：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

販売者名

"きのこ農園"、"ユースファーマー"など

使用例

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スキーマ例

商品登録
商品修正
商品削除

Last updated