apply_frame_to_image
ChatGPT商品画像URLにテナント設定のフレームをサーバー側で合成し、Shopee にアップロードして image_id / image_url / original_url / frame_id / badge を返す。横展開 (SG→MY 等) で frame が落ちる課題への対策。事前に list_listing_frames で frame_id を取得し、戻り値を create_listing の先頭画像へそのまま渡す。複数個をまとめて1商品として売る場合は set_quantity に「1セットあたりの同梱個数」(10個セットなら 10)を渡すと、テナントに設定がある場合のみ個数バッジをフレームと同じ1パスで焼き込む。set_quantity は出品する在庫数(リサーチ候補の planned_listing_quantity)とは別物なので取り違えないこと。単品なら省略する(1 は渡さない)。バッジが乗ったかどうかは badge で判断する(空き隅に描画した applied / 空き隅が無く設定された隅で商品に重ねた applied_over_product / set_quantity を渡していない not_requested / テナントに設定が無い not_configured / 設定の取得に失敗した style_unavailable 等)。バッジはまず商品の無い空き隅を探し、どの隅も埋まっている場合だけ設定された隅の商品に重ねる。重ねる相手は商品だけで、フレームの装飾が乗っている隅は避けるため、どの隅にも装飾があるフレームでは重ねずに no_empty_corner を返す。返した image_url がバッジ入りの完成画像で、original_url は渡した元画像のままなので、後から original_url を再フレームするとバッジは残らない。
attach_listing_video
ChatGPTsucceeded の AI 動画を product_id に紐づけ、shop_ids ごとに Shopee media_space へアップロードを開始する(冪等 — 同じ shop を再 POST しても重複アップロードは作らない)。既存の動画は置き換わる。元に戻す手段は無いので、置き換えてよいかを利用者に確かめてから呼ぶ。全店舗の shop_uploads[].status が終わるまで get_listing_video を叩き、failed は error_code と一緒に報告する。各 shop の upload 完了後、Go 側が update_item で video_upload_id を設定する。409 ERR_VIDEO_NOT_READY はジョブがまだ succeeded でない。
calculate_profit_at_price
ChatGPT指定価格での利益を中央の Go pricing API へ1回だけ問い合わせる。provider_id が対象の正本。currency には price_local が実際に何の通貨建てなのかを宣言する。通貨の付け替えは絶対にしない — 手元に日本円しか無いなら換算せず currency:"JPY" と price_local を円のまま渡す(換算はサーバーが行う)。円の数値に現地通貨コードを貼ると、桁が2桁ずれた利益判定が成功として返る。requested_price は入力、listing_price / price_local は実際に評価した対象通貨価格(失敗時は price_local も null)。成功判定は calculation_error=false かつ error_reason=null。セル失敗の計算数値は全て null で、0 と解釈してはならない。profitable と below_min_profit、exceeds_max_price(上限超過 → 値下げ)/ below_min_price(下限割れ → 値上げ)、price_bounds_unverified を全て確認し、provenance と breakdown を根拠として使う。store_name / shop_id / country_code は常に null なので、表示名や国が必要なら provider_id を list_stores と照合する。
calculate_recommended_prices
ChatGPT仕入価格・重量・provider_id[] を中央の Go pricing API へ1回だけ送り、各ストアの推奨価格を返す。provider_id が対象の正本であり、マーケット名やリージョン文字列から対象を再構築しない。このツールがそのストアについて成功を返さない限り、価格を決めたり create_listing / create_listing_with_variations に進んだりしてはならない。 別の根拠で価格を代替してはならない。成功判定は results[].calculation_error=false かつ error_reason=null。セル失敗では全ての計算数値が null になるため、0 と解釈してはならない。exceeds_max_price(上限超過 → 値下げ)と below_min_price(下限割れ → 値上げ)は対処が正反対なので必ず両方を見る。price_bounds_unverified=true または上下限フラグが null の価格は未検証なので出品しない。provenance と shipping_breakdown / fee_profit_breakdown が中央 API の設定根拠と内訳を示す。results[].using_default_fee_settings=true はそのストアがサーバー既定値で計算されたことを表し、人間の確認なしに出品しない。sales_price を指定すると目標マークアップと最低利益ガードが 0 で送られ、below_min_profit は「利益がマイナス」でしか true にならない(=テナントの最低利益ラインは検査されない)。purchase_price / sales_price は JPY、recommended_price_local は返却通貨。store_name / shop_id / country_code は常に null なので、表示名や国が必要なら provider_id を list_stores と照合する。
complete_video_upload
ChatGPTS3 へ POST 済みの seller upload を complete し検証と Shopee fan-out を開始する(202、冪等)。ページ経路では不要。409 ERR_UPLOAD_NOT_FOUND は POST 後にリトライ可。409 ERR_UPLOAD_EXPIRED はリトライ不可。409 ERR_SOURCE_TOO_LARGE は job failed — リトライ不可。503 ERR_VIDEO_UPLOAD_UNAVAILABLE。出品中の既存 Shopee 動画は置き換わる。元に戻す手段は無いので、置き換えてよいかを利用者に確かめてから complete_video_upload を呼ぶ。 生成・検証は数分かかる。job_id を返したら get_listing_video を 30〜60 秒間隔でポーリングし、status と shop_uploads がすべて終端になるまで待つ(1回のツール呼び出し内で sleep しない)。 get_listing_video で全ショップの shop_uploads が終わるまで確かめ、failed は error_code と一緒に報告する。202 や upload_page_url を渡しただけで完了と言わない。
compose_variation_thumbnail
ChatGPTバリエーション画像を渡された順に最大6枚選び、各画像の白余白を除去してアスペクト比に最適な均等グリッドへタイル合成し、Shopee にアップロードする。7枚以上は先頭6枚を使い omitted_image_count / truncated を返す。同一画像だけなら単品表示へフォールバックする。variation_name には tier_variation[0].name をそのまま渡し、テナントに設定がある場合のみバッジも合成する。複数個をまとめて1商品として売る場合は set_quantity に「1セットあたりの同梱個数」を渡すと、バリエーション軸のバッジより優先されてバッジは1つだけになる(出品在庫数とは別物なので取り違えないこと)。バッジが乗ったかどうかは badge で判断する(applied / 何も渡していない not_requested / variation_name にバッジ語が無い axis_unrecognised / テナントに設定が無い not_configured / 設定の取得に失敗した style_unavailable / 空き隅が無い no_empty_corner 等の描画スキップ理由)。axis_unrecognised はテナント設定の問題ではないので、設定を見に行かず別の軸名を渡すか運用側に語の追加を依頼すること。frame_id 指定時はフレーム前タイルの URL と frame_id を original_url / frame_id のペアで返すため、戻り値を create_listing* の images[0] にそのまま渡せる。
create_listing
ChatGPTShopeeに単品(バリエーションなし)を出品。作成前に必ず prepare_listing を実行し、status が ready のストアだけ、その stores[].create_request(画像だけ差し替え)を引数に使う。また出品先の各ストアで get_shopee_shop_info を呼び、status が NORMAL であることを確かめる。 MCP 経由の作成は、prepare_listing のルール(オプション画像の共有・視覚軸のオプション画像・オプション名の重複・ギャラリー画像の重複と枚数・仕入原価と ASIN の形式)に反すると、422(ERR_VALIDATION_FAILED)で拒否される。issues[] の code は prepare_listing と同じ。422 を受けたら作成を繰り返さず、入力を直して prepare_listing からやり直す。作成した出品は UNLIST のまま残し、set_listing_status(listed=true) は呼ばない(公開は出品者が行う)。 item_name と description は出品先ストアの言語で書く(list_stores が provider_id ごとに返す listing_language.code が正)。日本語のまま渡すと日本語のまま公開され、update_item で直すまで戻らない。listing_language が付かないストアは言語を推測せずユーザーに確認する。 事前に recommend_category / get_attributes / get_logistics_channels / upload_image_url / get_compliance_rules を実施する。images[].image_url は必須。フレームを適用した先頭画像は apply_frame_to_image / compose_variation_thumbnail の戻り値の image_id / image_url / original_url / frame_id をそのまま images[0] に載せる。 JPY基準の価格意図がある場合は、必須の現地通貨 original_price と併せて price_jpy を優先して指定する。price_jpy 省略時は Go API が現在レートで逆換算する。横展開(既存商品を別リージョンへ追加)時は product_id か amazon_asin を指定して重複マスタ作成を防ぐ。リサーチ候補から出品する場合は list_research_candidates → get_research_candidate で取得した候補 id を research_candidate_id に渡し、ストア横断のバルク出品では同一 submission_id(8-64 文字の冪等性キー)を全リクエストで共有する。purchase_price(JPY、products.price に保存される原価)は必須で、0 より大きい値を渡す。省略すると PURCHASE_PRICE_INVALID の 422 になる。
create_listing_with_variations
ChatGPTShopeeにバリエーション付き商品を出品。作成前に必ず prepare_listing を実行し、status が ready のストアだけ、その stores[].create_request(画像だけ差し替え)を引数に使う。また出品先の各ストアで get_shopee_shop_info を呼び、status が NORMAL であることを確かめる。 MCP 経由の作成は、prepare_listing のルール(オプション画像の共有・視覚軸のオプション画像・オプション名の重複・ギャラリー画像の重複と枚数・仕入原価と ASIN の形式)に反すると、422(ERR_VALIDATION_FAILED)で拒否される。issues[] の code は prepare_listing と同じ。422 を受けたら作成を繰り返さず、入力を直して prepare_listing からやり直す。作成した出品は UNLIST のまま残し、set_listing_status(listed=true) は呼ばない(公開は出品者が行う)。 item_name と description は出品先ストアの言語で書く(list_stores が provider_id ごとに返す listing_language.code が正)。日本語のまま渡すと日本語のまま公開され、update_item で直すまで戻らない。listing_language が付かないストアは言語を推測せずユーザーに確認する。 model ごとに確認済みの variation_product_id、または新しい子商品を作る new_option=true を指定できる(false でも両方の同時指定は不可)。ASIN や位置から商品を自動選択しない。422 の ERR_VARIATION_MAPPING_REQUIRED は紐付けの明示、ERR_LISTING_BASE_IS_CHILD は親の product_id への修正、ERR_VARIATION_CHILD_SKU_AMBIGUOUS は SellBridge 側の重複SKUの修復が必要。これらは作成前の拒否なので、修正が済むまで再送しない。同期応答または非同期の result にある sku_changes[] の sent_sku を実際のSKUとして記録し、warnings[] も確認する。作成済みの保存失敗の警告があれば再作成せず、既存出品の保存・紐付けを修復する。 tier_variation(軸定義)と model(各SKUの価格・在庫・tier_index)を指定する。images[].image_url は必須。フレームを適用した先頭画像は apply_frame_to_image / compose_variation_thumbnail の戻り値の image_id / image_url / original_url / frame_id をそのまま images[0] に載せる。 JPY基準の価格意図がある場合は、各 model で必須の現地通貨 original_price と併せて price_jpy を優先して指定する。price_jpy 省略時は Go API が現在レートで逆換算する。単品は create_listing を使う。横展開時は product_id / amazon_asin を指定。リサーチ候補からの出品なら research_candidate_id、ストア横断バルク時は共通の submission_id を渡す(詳細は create_listing 参照)。purchase_price(JPY、仕入原価)は必須で、0 より大きい値を必ずitemレベルに渡す。省略すると PURCHASE_PRICE_INVALID の 422 になる。modelごとに原価が違う場合は model 側にも指定する(model に無ければ item の値が使われる)。
delete_item
ChatGPTShopeeの既存商品を完全削除する破壊的操作(復元不可)。item_id で指す出品を消し、sku で解決した商品のストア紐付けを外す。Go APIは実行前に item_id と sku が同じ商品(またはその親子)を指すことを検証し、別商品なら 409 ERR_ITEM_SKU_MISMATCH、SellBridgeが紐付けを持たない出品なら 409 ERR_ITEM_NOT_MAPPED で拒否する(どちらもShopeeには何も送られない)。409 のときは推測で組み合わせを変えず、get_shopee_item / get_listing_data で出品を読み直してから送り直す。
generate_listing_video
ChatGPTSellBridge の AI で商品動画(約 10 秒)を生成し job_id を返す。source_image_url は upload_image_url / apply_frame_to_image / compose_variation_thumbnail が返した SellBridge 上の画像 URL のみ使う(任意の URL は不可)。 1 ジョブあたり 1.5 SBC の AI クレジットを消費する。402 (ERR_INSUFFICIENT_CREDITS) は残高不足。429 (ERR_TOO_MANY_VIDEO_JOBS) はテナントの同時実行上限(3 件)。 生成・検証は数分かかる。job_id を返したら get_listing_video を 30〜60 秒間隔でポーリングし、status と shop_uploads がすべて終端になるまで待つ(1回のツール呼び出し内で sleep しない)。
get_attributes
ChatGPTカテゴリの必須・任意属性リストを取得。必須属性が抜けると出品APIがエラーになるため事前確認必須。同じカテゴリでも必須属性はリージョンごとに異なる(例: カテゴリ 101241 の Sports Product は SG/TW で必須、PH/TH では不要)ため、多店舗出品では出品先の provider_id ごとに必ず確認する。1ストア分の全属性は約300行あるので、多店舗展開の事前確認には mandatory_only=true を使う(必須属性と条件付き必須を発生させうる属性に絞り、選択肢は残したまま多言語名だけ落とす)。選択肢が多すぎて打ち切った属性には note で対処法を添えて返す。各ツリーの attribute_total_count は絞り込み前の属性数なので、attribute_tree が空でも attribute_total_count > 0 なら「必須属性なし」と判断してよい(両方0なら取得自体を疑う)。一部の属性は、選択した値によって追加の必須属性を発生させる(選択肢の requires_attributes に出る。例: TH のおもちゃカテゴリで Recommended Age に 14 Years Above 以外を選ぶと TIS No. 等が必須になる)。requires_attributes がある値を選んだ場合、そこに並ぶ属性のうち mandatory: true のものは必ず埋める(mandatory: false の要素も含まれるので、埋められないなら省いてよい。分からない値を埋めるより省く方が安全)。requires_attributes の各要素は要約であり、属性の完全な定義ではない。attribute_value_total_count がある場合、その属性は選択式で選択肢はこの応答に含まれていないので、mandatory_only を外して取り直し value_id を確認する(value_id を推測してはならない)。attribute_value_total_count がなければ通常は自由入力なので value に直接書いてよいが、出品APIが値を拒否したら mandatory_only を外して input_type を確認すること。TIS / FDA などの認証番号は推測してはならない。値が分からない場合は、requires_attributes を持たない選択肢を選ぶか、そのリージョンへの出品を見送る。
get_brands
ChatGPTカテゴリで使用可能なブランド一覧を取得。ブランドなしは brand_id=0 (NoBrand) を指定。全件は数万行になるため、特定ブランドを探すときは query でブランド名を絞り込む(クライアント側の部分一致フィルタ)。一致が多すぎる場合は先頭のみ返し brand_truncated / brand_match_count / note を添えるので、query をより具体的なブランド名にして呼び直す。
get_category_summary
ChatGPTカテゴリ別売上サマリーを取得。直近30日のカテゴリ別パフォーマンス。
get_compliance_rules
ChatGPTShopee出品ルール(禁止カテゴリ/商品/ブランド/キーワード/配送制限)のデータをグローバル+対象ストアごとに返す。判定は呼び出し側 LLM が行う。keywordMatchHighlights は文字列マッチで拾った当たり候補で、最終判断ではない。 利用可能なストア: shopee_sg, shopee_tw, shopee_my, shopee_th, shopee_ph, shopee_vn, shopee_br, shopee_jp
get_dashboard_kpi
ChatGPTKPIスナップショットを取得。今日と昨日の売上・注文数・平均注文額と、直近6ヶ月の利益率。profit_rate は原価入力済みの注文だけの利益合計 / 売上合計で計算し、原価不明の注文は分子・分母から除外する。原価入力済みの注文が無いなど、算出できない場合は profit_rate が null。profit_rate_coverage は対象期間の注文数に占める原価入力済みの割合(0〜100%、対象注文が無ければ null)。割合が低い場合、利益率は一部の注文だけを表す。金額はすべて円換算。旧v1の period 引数は廃止(固定で当日/前日+利益率6ヶ月)。
get_exchange_rates
ChatGPT中央 API が公開する為替レート(1 JPY = X local currency)の参照用生データ。価格計算には使わず、calculate_recommended_prices / calculate_profit_at_price の中央 API 結果を正本とする。
get_fee_settings
ChatGPT中央 API が公開するテナント手数料設定の参照用生データ。クライアント側で価格を再計算せず、pricing tools の provenance と breakdown を使う。
get_inventories
ChatGPT在庫一覧を取得。在庫1点ごとのレコードとステータス (normal / return_to_list / returned / broken など)。
get_inventory_summary
ChatGPT在庫ステータスサマリーを取得。保留・返品・不良品などステータス別の件数。
get_listing_data
ChatGPT既存商品の現在のShopee出品データを取得し、別ストアへの横展開や復旧に再利用する。応答はShopeeから都度取得した現在値であり、SellBridgeに保存された下書きではない。provider_id には「すでに出品済みの取得元ストア」を指定する(横展開先ではない)。SellBridgeのproduct→item紐付けを経由するため、紐付けの無い出品は取得できない(その場合は get_shopee_item に item_id を直接指定する)。返却値はGo APIの生データで、価格・配送設定・model_idは対象ストアに合わせて確認すること。models[].variation_product_id は検証済みの紐付け。ID が null なら未解決なので ASIN や位置から推測しない。amazon_asin はその商品のASINで、未登録なら ID があっても null になる。model_idを別ストアへコピーしてはならない。
get_listing_operation
ChatGPT非同期出品を operation_id、または provider_id と同じ submission_id の組で1件取得する(両方は指定不可)。SellBridge DBだけを読むためShopeeリクエストを送らず、書き込み枠も消費しない(全ツール共通の毎分の枠は消費する)。コード別の対応に進む前に、必ず返る boolean の provisional_price を最初に確認する。provisional_price が true なら status や error_code にかかわらず公開・割引追加をせず、人が Shopee Seller Centre または SellBridge で商品の実際の価格を確認・修正する。これは操作の保存記録であり、Shopee の現在価格を再取得した値ではない。人が後から価格を修正しても false には変わらないため、終了済みの操作を false になるまでポーリングしない。price_restore_pending は終端ではないため、引き続きポーリングする。pending / creating / base_created / configuring / reconciling / cleanup_pending は処理中なので、retry_after_seconds(最低2秒)後に再取得する。needs_review と failed は成功として扱わず error_code を確認する。provider_rebound は受付後にストアが別の Shopee ショップへ再接続された状態。failed かつ item_id が無い場合だけ、接続先ショップを確認して同じ submission_id で再送できる(新しいショップには作成されていない)。needs_review で item_id がある場合は作成時の接続先ショップに下書きが残っている可能性があり、新しいショップでは公開されていない。needs_review で item_id が無い場合も作成リクエスト送信済みの可能性があるため、同じ submission_id を再送しない。variation_mapping_required / listing_base_is_child / variation_child_sku_ambiguous は識別情報の拒否。入力の明示・親IDへの修正、または重複SKUの修復が済むまで再送しない。variation_plan_stale は保存済みの出品計画と現在のデータの不一致。これらで failed かつ item_id が無い場合だけ、原因を修正し prepare_listing で再確認してから同じ submission_id で再送できる。needs_review で item_id がある場合は出品が作成済みなので再送しない。item_id が無い needs_review も作成リクエスト送信済みの可能性があり再送しない。人が対象ショップの既存出品と紐付けを確認・修復する。result.sku_changes[] / result.warnings[] は同期作成と同じ意味なので記録する。 price_restore_pending は Shopee TH の商品が分割払いの最低価格に合わせた仮価格で存在し、指定価格への復元中。終端ではないのでポーリングを続け、割引にはまだ追加しない。price_restore_failed は needs_review で item_id があり、仮価格のまま UNLIST に残る。公開・割引追加をせず、人が Shopee Seller Centre または SellBridge で価格を修正する。price_restore_pending から needs_review に終わり item_id がある場合は、別の error_code でも仮価格が残るため同じ対応をする。これらのコードに伴う error_message は SellBridge 自身の説明文であり、Shopee の原文として障害診断(diagnose-failure)に渡さない。price_restore_failed に Shopee の update_price 理由が追記されていても渡さず、別コードで終わった価格復元の説明文も渡さない。succeeded は UNLIST 下書きの作成完了であり、公開済みを意味しない。
get_listing_template
ChatGPTdescription テンプレ単体取得。多言語 content(ja/en/th/vi/pt/zh_tw のキー、または string レガシー形式)と includes_product_description フラグを返す。使い方: (1) 出品先ストアの言語のキーを選ぶ(list_stores の listing_language.template_key をそのまま使う。listing_language.code は別体系で、渡すと存在しないキーを引いて空になる)、(2) includes_product_description=true なら %item_description% プレースホルダを商品説明文で replace() してから、(3) create_listing / create_listing_with_variations の description に渡す。
get_listing_video
ChatGPTAI 生成・出品者 MP4 アップロードの status / video_url / preview_url / error_code / shop_uploads を返す。source=upload のジョブは preview_url を返し video_url は null。status awaiting_upload は S3 未 POST。shop_uploads の pending は MP4 検証中、uploading は Shopee へ fan-out 開始後。 生成・検証は数分かかる。job_id を返したら get_listing_video を 30〜60 秒間隔でポーリングし、status と shop_uploads がすべて終端になるまで待つ(1回のツール呼び出し内で sleep しない)。 AI ジョブは status が succeeded になってから attach_listing_video を呼ぶ。failed で error_code が ERR_KLING_PACK_EMPTY / ERR_CONTENT_MODERATION なら再生成しない。failed の error_code が ERR_SOURCE_NOT_MP4 / ERR_SOURCE_DURATION_OUT_OF_RANGE / ERR_SOURCE_NO_VIDEO_TRACK / ERR_SOURCE_TOO_LARGE のときはファイルを直す — 同じファイルでループ再試行しない。 409 ERR_VIDEO_NOT_READY は attach を早く呼んだ場合 — ポーリングを続ける。
get_logistics_channels
ChatGPTストアの利用可能な配送チャネル一覧を取得。出品時に最低1つの enabled チャネルが必要。
get_low_profit_orders
ChatGPT低利益注文一覧を取得。利益率5%以下の注文を特定して改善に活用。原価不明(profit_rate が null)の注文は含まない。在庫に紐付いている原価未入力の注文は、対象期間・ステータスに該当すれば get_profit_table で確認できる。在庫と紐付いていない注文は get_profit_table / get_low_profit_orders のどちらにも表示されない。get_orders で注文を取得し、応答の id(ord_97889 など)から ord_ を除いた数値を order_id に指定して get_order_summary で確認すること。provider_id (数値) で単一ストアに絞れる。from で既定の「直近2ヶ月」開始日時を上書きできる。Go APIは全件を返すため、MCP応答はlimit/offsetで最大100件ずつ返す。total_countとnext_offsetを確認し、続きが必要なら再呼び出しする(truncated=trueは「この応答が全件ではない」の意味で、next_offset=nullなら最終ページ)。applied_filtersに実際に適用された絞り込みが返る。
get_monthly_order_summaries
ChatGPT月次注文サマリーを取得。年間の月別売上・利益推移。total_profit は原価入力済みの注文だけの利益合計。原価不明(利益が null)の注文は含めず、0円扱いもしない。provider_id (数値) で単一ストアに絞れる。省略時はアクセス可能な全Shopeeプロバイダーの集約(旧v1の provider="shopee_all" 相当)。旧v1の provider 名文字列は廃止。
get_monthly_orders
ChatGPT月次注文数データを取得。月ごとの注文数合計 (total_orders) とプロバイダー別注文数。当月は is_partial=true。
get_monthly_sales
ChatGPT月次売上データを取得。月ごとの売上合計とプロバイダー内訳。当月は is_partial=true。
get_order_detail
ChatGPT注文詳細を取得。商品情報、配送情報、価格内訳を含む。get_orders レスポンスの order_id (外部注文ID) を渡すこと。購入者の氏名・電話番号・住所は、full_access 以外の資格情報 (OAuth 連携、および read_only / listing スコープの API キー) では、マーケットプレイスを問わず SellBridge 側でマスクして返る (氏名は先頭1文字+*、電話番号は末尾2桁以外、番地行は *、郵便番号は先頭3文字まで)。full_access スコープの API キーで呼んだ場合はマスクせずに返る (ただしマーケットプレイスが元データを伏せている場合、その値は復元されない)。マスクされるのは購入者本人を指す項目だけで、市区町村・州・国やマーケットプレイス側の識別子は残るため、応答全体が匿名化されるわけではない。
get_order_summary
ChatGPT注文の利益サマリーを取得。売上、原価、利益率などの詳細。利益は呼び出しごとに再計算され、再計算した仕入費・経費・利益・利益率で SellBridge に保存済みの値を上書きする(注文の入力データは変えない)。
get_orders
ChatGPT注文一覧を取得。marketplace、canonical_status、期間 (RFC 3339 date-time) でサーバ側フィルタ。定期取得は start_date / end_date で窓を切り、page で続きを辿る。期間が見るのは order_date (マーケットプレイス上の注文日時) であり、SellBridge への取込日時ではない。同期遅延やバックフィルで後から入った注文は order_date が過去のため、消化済みの窓には二度と現れない。取りこぼしを防ぐには窓を重ねて取り直し、応答の id で突合すること。start_date がプランの参照可能期間より前だとエラーにならず期間の先頭に切り詰められる (Free 30日 / Basic 12ヶ月 / Standard 24ヶ月 / Premium 無制限)。取得できた最古の注文日がその境界と一致していないか確認する。購入者の氏名・電話番号・住所は、full_access 以外の資格情報 (OAuth 連携、および read_only / listing スコープの API キー) では、マーケットプレイスを問わず SellBridge 側でマスクして返る (氏名は先頭1文字+*、電話番号は末尾2桁以外、番地行は *、郵便番号は先頭3文字まで)。full_access スコープの API キーで呼んだ場合はマスクせずに返る (ただしマーケットプレイスが元データを伏せている場合、その値は復元されない)。マスクされるのは購入者本人を指す項目だけで、市区町村・州・国やマーケットプレイス側の識別子は残るため、応答全体が匿名化されるわけではない。
get_product_detail
ChatGPT商品詳細を取得。画像、バリエーション、出品情報を含む。
get_products
ChatGPT商品一覧を取得。search (商品名検索) と category_id (数値) でフィルタ可能。
get_profit_table
ChatGPT利益テーブルを取得。直近2ヶ月の完了/発送済み注文の利益情報一覧。在庫に紐付いている原価不明(未入力)の注文も含み、その purchase_fee / profit / profit_rate は null。cost_known=false が原価不明を示す。null を0円や高利益と解釈しないこと。在庫と紐付いていない注文は get_profit_table / get_low_profit_orders のどちらにも表示されない。get_orders で注文を取得し、応答の id(ord_97889 など)から ord_ を除いた数値を order_id に指定して get_order_summary で確認すること。provider_id (数値) で単一ストアに絞れる。省略時はアクセス可能な全プロバイダー。Go APIは全件を返すため、MCP応答はlimit/offsetで最大100件ずつ返す。total_countとnext_offsetを確認し、続きが必要なら再呼び出しする(truncated=trueは「この応答が全件ではない」の意味で、next_offset=nullなら最終ページ)。applied_filtersに実際に適用された絞り込みが返る。旧v1のpage/perは廃止。
get_prohibited_rules
ChatGPTShopee禁止・制限品ルールの閲覧・検索。リージョン、ルールタイプ、キーワードでフィルタ可能。全ルールの一覧表示やルール数の集計にも使える。「TWで制限されているカテゴリを一覧したい」のようにカタログ自体を引く用途に使う。特定商品の出品可否を判断したい場合はこれではなく get_compliance_rules を使うこと。
get_research_candidate
ChatGPTリサーチ候補単体取得。productName / weight / delivery_days / purchase_price / planned_listing_quantity(出品する在庫数)/ set_quantity(1セットあたりの同梱個数。セット販売でなければ null)/ variations / amazon_url / category / amazon_asin / status を返す。サムネイルに個数バッジを焼くときは set_quantity を apply_frame_to_image / compose_variation_thumbnail の set_quantity にそのまま渡す(planned_listing_quantity は在庫数なので渡さない)。出品ウィザードへのプリフィル相当の情報源。create_listing* 呼び出し時はこの候補の id を research_candidate_id に渡し、amazon_asin も同時に渡せば既存商品マスタへの dedup が効く。
get_shipping_rates
ChatGPT中央 API が公開する重量別配送料の参照用生データ。クライアント側で価格を再計算せず、pricing tools の shipping_breakdown を使う。
get_shopee_category_limits
ChatGPTShopee APIからストア・カテゴリ別の出品制限を取得。応答のtitle_max_lengthはShopeeのitem_name_length_limitに相当し、リージョン差が大きい(実測: TW 60 / その他255 / BR 500)ため固定値を仮定しない。source=fallback はShopee障害時にリージョン表から補完した推測値で、実測より緩い側に外れることがある(表に無いリージョンは既定の255になるため、真値60のTWでも255が返りうる)。fallback のときは既知のリージョン実測値と突き合わせ、厳しい方を上限として扱う。ただし create_listing / create_listing_with_variations の item_name はスキーマ側で255文字までなので、BRで500と返っても256文字以上の商品名は出品前に弾かれる。両者のうち小さい方を上限として扱う。
get_shopee_item
ChatGPTShopee APIから現在のアイテム実体(状態・SKU・商品名・重量・画像・モデル等)を取得。item_id を直接指定してShopeeを引くので、SellBridgeに紐付けの無い孤児アイテムも読める。get_listing_data も現在のShopeeを読むが、そちらはSellBridgeのproduct→item紐付けを経由するため、紐付けが無い出品は取得できない(404 ERR_RESOURCE_NOT_FOUND)。出品後の検証にはこのツールを使い、SellBridge側の記録(get_products / get_product_detail)との乖離を幽霊レコード・孤児アイテムとして確認する。バリエーション商品の重量はitem級ではなく models[].weight を検証する(item級はモデル中の最大値になる)。重量はいずれもKGの小数文字列で、create_listing に渡すグラムとは単位が違う(0.3 は 300g)。item級の重量を継承するモデルでは models[].weight ごと省略されるため、その場合はこの応答のitem級 weight が真値。
get_shopee_item_models
ChatGPTShopee APIから現在のモデル(バリエーション)一覧を取得。model_id・model_sku・価格・在庫・モデル別重量を返す。THのinstallment復元や出品後のSKU/重量検証に使用し、バリエーション商品の重量はitem級ではなくモデル別の値を見る。重量はKGの小数文字列で、create_listing に渡すグラムとは単位が違う(0.3 は 300g)。item級の重量を継承するモデルでは weight キーごと省略される。欠落は不一致ではないので、その場合は get_shopee_item のitem級 weight を真値として突き合わせる。
get_shopee_shop_info
ChatGPTShopee APIから、ストアそのもののShopee上の状態(status: NORMAL / BANNED / FROZEN)と店舗名・リージョンを取得する。list_stores の status / token_status はSellBridgeとの接続状態であり、Shopee側の店舗状態ではない(接続済みでもShopee上では凍結・BANされていることがある)。create_listing / create_listing_with_variations(submit_listing / submit_listing_with_variations も同様)の前に、出品先のストアごとにこのツールを呼ぶ。status が NORMAL 以外のストアと、このツールがエラーを返したストアには出品せず、そのストアをスキップする。FROZEN のストアでは、Shopeeが親アイテムを作成したあとでバリエーションを拒否するため、そのストアでの親SKUが使えなくなる。作成側のAPIにも NORMAL 以外を拒否するガード(ERR_PROVIDER_SHOP_NOT_OPERATIONAL)はあるが、Shopeeからの状態取得に失敗したときは素通しし、状態を最大5分キャッシュするため、保証にはならない。エラーの意味: 403 はAPIキーで許可されていないストア、404 はテナント外・Shopee以外・未連携のプロバイダー、502 ERR_EXTERNAL_API_FAILED はShopee側の障害または未知の状態。いずれも「このストアには出品しない」として扱う。
get_stock_monitor_status
ChatGPT商品ごとの在庫監視(Amazonの在庫切れに連動してShopee出品を止める仕組み)の状態を取得する。monitored=true は、その商品に有効な購読が1件以上あるという意味で、全ストア × 全モデル(バリエーション)が監視されていることは意味しない。どのストア・モデルが監視されているかは list_stock_monitor_subscriptions の search に親SKUを渡し、返った行を sku の完全一致で絞ってから、ストア × モデルごとの行を数えて確かめる。APIキーが一部のストアに制限されている場合、subscription_count と monitored はそのストアの購読だけで数える(他のストアだけで監視中の商品は monitored=false, subscription_count=0 になる)。create_listing / create_listing_with_variations(submit_listing / submit_listing_with_variations も同様)後の在庫監視の自動登録は、モデルに amazon_asin が無い場合・テナントの在庫監視設定がオフの場合・プランの購読上限に達した場合に、エラーを出さず黙ってスキップされる(出品自体は成功として返る)。
get_top_selling_products
ChatGPTベストセラー商品一覧を取得。直近7日間の売上上位5商品(在庫ステータス付き)。provider_id で単一ストアに絞れる。
get_trend_categories
ChatGPTResearch → Trends のカテゴリ別トレンドを国別に取得。category_id / category_name / units_latest / units_prev / wow_ratio / listing_count / participating_tenants と pagination を返す。k-anonymity 未満のカテゴリは API が除外するため、小さい国では categories が空でも正常。集計は毎週月曜午後〜火曜朝 (JST) に更新される。日次で同じ結果が返っても失敗ではない。 Basic 以上の有料プランでのみ利用可能。無料プランでは利用不可(MCP access requires a paid SellBridge plan. The current plan is not entitled to use listing and analytics tools.)。
get_trend_keyword_listings
ChatGPT追い風 (tailwind) のキーワードから、テナントの Shopee 出品一覧をドリルダウン。provider_id / shopee_item_id / item_name / image_url / title_contains_keyword / has_active_ads / opportunity_score / product_id と pagination を返す。集計は毎週月曜午後〜火曜朝 (JST) に更新される。日次で同じ結果が返っても失敗ではない。 Basic 以上の有料プランでのみ利用可能。無料プランでは利用不可(MCP access requires a paid SellBridge plan. The current plan is not entitled to use listing and analytics tools.)。
get_trend_keywords
ChatGPTResearch → Trends のキーワードフィードを国別に取得。section で追い風 (tailwind) / 参入チャンス (opportunity) / 新登場 (new) を選ぶ。keyword / latest_volume / prev_volume / wow_delta / wow_ratio / weekly_volumes (スパークライン) / is_new / my_listing_count など画面と同じフィールドと pagination を返す。1回あたり page_size は最大 50。集計は毎週月曜午後〜火曜朝 (JST) に更新される。日次で同じ結果が返っても失敗ではない。 Basic 以上の有料プランでのみ利用可能。無料プランでは利用不可(MCP access requires a paid SellBridge plan. The current plan is not entitled to use listing and analytics tools.)。
get_video_generation_usage
ChatGPT当月(UTC)に作成したジョブ数(失敗・残高不足で拒否されたものを含む)と消費クレジット。残高ではない。
get_weekly_sales
ChatGPT週次売上データを取得。直近7日間の日別売上をプロバイダー内訳付きで返す。
list_listing_frames
ChatGPTテナント保有のリスティングフレーム(出品画像に重ねるブランディング枠)一覧を取得。返った frame_id を apply_frame_to_image / compose_variation_thumbnail に渡す。per_page 省略時は100件、category / is_active で絞り込み可能。
list_listing_templates
ChatGPTテナント保有の description テンプレ(policy / warranty / shipping / custom)一覧を取得。返った id を get_listing_template に渡してコンテンツ全文を引き、出品の description に再利用する。per_page 省略時は100件、category / is_active で絞り込み可能。書き込み系(作成/更新/削除)は Web/Admin で完結させるため MCP には出していない。
list_research_candidates
ChatGPTリサーチで承認した出品候補(productName / weight / purchasePrice / variations / amazonUrl / category / amazonAsin 等)の一覧を取得。デフォルトは status=approved(出品待ち)のみ。LLM が未承認候補を誤って出品しないようガードしているので、必要なときだけ status を明示的に渡す(カンマ区切りで複数指定可、例 draft,pending_review)。返った id を get_research_candidate に渡して詳細を取り、create_listing / create_listing_with_variations 呼び出し時に research_candidate_id として渡すとリサーチ→出品のトレーサビリティが残る。承認フロー自体は Web/Admin で完結。
list_shopee_items
ChatGPTShopee APIから指定状態のアイテム一覧とtotal_countを取得。出品枠の消費数はNORMALだけでなくREVIEWINGも別々に取得して足す(実測ではNORMAL 2998 + REVIEWING 2 = 3000で上限)。has_next_page=trueの続きはoffsetを自計算せず、必ず応答のnext_offsetを使う。
list_stock_monitor_subscriptions
ChatGPT在庫監視の購読(Amazon ASIN ↔ Shopee の item / model の対応)を一覧する。1行 = 1つの (provider_id, item_id, model_id, ASIN)。単品は model_id=0 の1行、バリエーション商品は amazon_asin のあるモデルごとに1行(どのモデルにも amazon_asin が無く、商品全体のASINで登録された場合は model_id=0 の1行で商品全体を監視する)。セット商品(構成品あり)は構成品のASINごとに行が分かれる。出品直後の確認は search に親SKU(単品は sku)を渡し、返った行を sku の完全一致で絞ってから、出品したストアごとに上の形の行が揃っているかを数える。search は SKU・ASIN・商品名の部分一致なので、絞らずに数えると別商品の行(例: ABC-1 に対する ABC-10)が混ざり、欠けているストア・モデルが埋まって見える。enabled=false の行や abnormal_status が入っている行は、実際には照合されていない。Amazonとの照合はバッチで行うため、登録直後の行は last_checked_at が null のことがある。page_size を省略したときのAPI既定は50件(最大100)で、続きは pagination.total_pages を見て page を進める。APIキーが一部のストアに制限されている場合、そのストアの行だけが返り、pagination もその行だけを数える。特定の出品を調べるときは provider_id と item_ids(最大100件)で絞ると、ASIN ごとに呼ばずに1回で全モデルの行が取れる。create_listing / create_listing_with_variations(submit_listing / submit_listing_with_variations も同様)後の在庫監視の自動登録は、モデルに amazon_asin が無い場合・テナントの在庫監視設定がオフの場合・プランの購読上限に達した場合に、エラーを出さず黙ってスキップされる(出品自体は成功として返る)。
list_stores
ChatGPTテナントに接続済みのストア(プロバイダー)一覧を取得。各ストアの provider_id / shop_id / リージョン / listing_language / token_status を返す。出品系ツールに渡す provider_id はここで確認する。listing_language はそのストアの商品名・説明を書く言語で、code が執筆言語、template_key が get_listing_template の content キー。この2つは別の体系なので、code を content キーとして使ってはならない(一部の言語で値が食い違い、空を掴む)。出品ツールに渡す item_name / description は必ずこの言語で書くこと。日本語のまま渡すと日本語のまま Shopee に公開される。listing_language が付かないストア(Shopee 以外、未対応リージョン)は言語を推測せず、ユーザーに確認すること。token_status は各ストアのOAuth接続状態で、expiring は7日以内に失効、expired / invalid は既に切れており同期も出品も通らない状態(SellBridge の管理画面から再連携が必要)。valid 以外を見つけたらユーザーに知らせること。
migrate_canonical_sku
ChatGPT1商品のSKUを全出品ストアとSellBridge本体でまとめて揃える。update_item はストア1つしか変えないので、SKUを直す用途で使うと他ストアと products.sku が取り残されて割れる。割れを直す/防ぐときはこちらを使う。target_sku は呼び出し側が指定し、テナントのSKU接頭辞 + 16桁の小文字16進でなければ422。Shopee全体としては非アトミックなので、HTTPステータスではなく応答の completed を必ず読むこと。プロバイダー単位の失敗は200の中の provider_results[].success=false で返る。ローカル側は全プロバイダー成功後にのみ書かれるため、途中失敗しても同じリクエストを再実行すれば収束する(既に目標SKUのストアは何もしない)。target_sku は生きている出品との衝突だけを見ればよい。削除済みの出品が握っているSKUは再利用できる(TH/SG で実測、sell-bridge-api#4321)ので、それを理由に候補から外さないこと。
prefill_from_asin
ChatGPTAmazon ASIN から Keepa 経由で商品情報(名称・説明・画像・バリエーション)を取得し、出品フォームのプリフィルに使う。domain_id 省略時は amazon.co.jp (5)。price(現在価格。Buy Box が無ければ新品最安などで代替)と regular_price(直近90日の大半で維持されていた価格。履歴が少ないと無い)は最小通貨単位の整数で返る(amazon.co.jp は円、amazon.com はセント)。取得できなければ null か欠落。同じ ASIN・同じ domain_id の 2 回目以降は 24 時間キャッシュから返るため月次上限は消費しないが、初回はプランの月次上限(keepa_lookup_monthly)を 1 消費する。毎分 10 回の上限はキャッシュ由来の呼び出しも数えるので、まとめて引くときは間隔を空ける。共有の Keepa 残量が少ないときは 429 を返すので、数分あけて再試行する。
prepare_listing
ChatGPT出品前の事前チェック(ドライラン)。create_listing / submit_listing の前に必ず呼ぶ。1商品の仕様(実測重量・仕入原価・ストアごとの文言・カテゴリ・属性・配送・画像・バリエーション)を出品先ストアごとに検査し、各ストアの create_request(作成リクエスト本文)・サーバーが計算した価格・errors / warnings を返す。DB にも Shopee にも何も書かないので何度呼んでもよい。使い方: request_errors が空でなければどのストアにも出品しない。stores[].status が ready のストアだけ出品し、blocked のストアには作らない。errors があれば入力を直して prepare_listing を再実行する。ready のストアは stores[].create_request をそのまま送る(kind が single なら submit_listing / create_listing、variation なら submit_listing_with_variations / create_listing_with_variations)。変えてよいのは画像だけで、create_request の説明どおり各画像をそのストアへアップロード(先頭のフレーム枠は apply_frame_to_image)して image_id / image_url を埋める。image_id が空のまま送らない。価格はテナントの手数料設定からサーバーが計算したものなので、original_price / price_jpy を書き換えず、自分で価格計算もしない。issue の code は今後増える。知らない code が errors / request_errors にあればブロッキングとして扱い、判断は常に status で行う。
preview_listing_images
ChatGPT出品候補の画像URL(1〜20件)をサーバー側で取得し、長辺640pxのJPEGに縮小して画像として返す。ローカルにツールが無くても画像を目で確認するためのもので、prepare_listing の gallery_image_urls や option の image_url に入れる前に必ず使う。QRコード・同梱されない商品・日本語だけの効能表示・パッケージ裏面の画像は外す。先頭のテキストに各画像の index・URL・取得した画像のサイズ(fetched_width / fetched_height)・失敗理由を必ず入れて返すので、画像が表示されないクライアントでもこれで結果を判断する。Amazonの画像URLは640pxの縮小版を取得し、その場合は fetched_url に取得先が入る。公開 https のJPEG / PNG / WebPだけを受け付け、内部ネットワークへのURLやリダイレクトは拒否する。1回の応答サイズに上限があり、超えた分は失敗として返すので、その画像以降を再度呼ぶ。Shopeeにもストアにも何も作らない。
recommend_category
ChatGPT商品名からShopeeカテゴリを推薦。商品名は出品先の言語(英語推奨)で指定する。返るのは category_id の配列だけなので、カテゴリ名とリーフ判定(has_children)は search_category に category_ids として渡して確認する。
renew_video_upload
ChatGPTawaiting_upload の seller upload job 向けに presigned POST を再発行する(シェルで 15 分の POST が切れたとき。ダッシュボードのページは同じ API を自分で呼ぶ)。新しい job は作らず cap も消費しない。409 ERR_UPLOAD_EXPIRED は新規 start_video_upload が必要。409 ERR_UPLOAD_ALREADY_COMPLETED は complete 済み。503 ERR_VIDEO_UPLOAD_UNAVAILABLE。get_listing_video で全ショップの shop_uploads が終わるまで確かめ、failed は error_code と一緒に報告する。202 や upload_page_url を渡しただけで完了と言わない。
search_category
ChatGPTShopee出品カテゴリを最大200件取得。返却フィールドは category_id / display_category_name / has_children / parent_category_id(現地語名と英語名が異なる場合のみ original_category_name も付く)。query を指定するとカテゴリ名で絞り込む(クライアント側の部分一致フィルタ。英語名にも当たる)。一致が多すぎる場合は先頭のみ返し category_truncated / category_match_count / note を添えるので、query をより具体的にして呼び直す。recommend_category が返した category_id を調べるときは query ではなく category_ids に渡す(件数上限の対象外で、必ず該当カテゴリが返る)。出品には has_children=false のリーフカテゴリのみ使用可能。
set_item_installment
ChatGPTTH/TWのShopee既存商品でクレジットカード分割払いの期間を設定する。THは3/6/10回、TWは3/6/12/24回だけを指定でき、空の tenure_list は分割払いを無効化する。HTTP 200でもShopeeの部分失敗は results[].success=false と error_code / error で返るため、必ずフィールド別結果を確認する。item_id と sku が別商品を指すと Go API が実行前に 409 ERR_ITEM_SKU_MISMATCH(SellBridge が紐付けを持たない出品は 409 ERR_ITEM_NOT_MAPPED)で拒否し、Shopee には何も送られない。409 のときは get_shopee_item / get_listing_data で出品を読み直してから送り直す。
set_listing_status
ChatGPTShopee出品1件の公開状態を変更する。listed=true で買い手に公開、listed=false で買い手から非表示にする(商品やSellBridgeデータの削除ではない)。公開前に、必ず同じ product_id / provider_id で get_listing_data を実行し、商品名・価格・画像・在庫・配送設定が正しいことを確認する。複数ストアは provider_id ごとに個別実行し、各結果を確認する。
start_video_upload
ChatGPT出品者 MP4 を Shopee へ載せるアップロード job を作成し job_id / upload_page_url / presigned POST / expires_at を返す。出品中の既存 Shopee 動画は置き換わる。元に戻す手段は無いので、置き換えてよいかを利用者に確かめてから start_video_upload を呼ぶ。 チャット経路では file_size_bytes は不要(省略時 30,000,000 を送る)。利用者に upload_page_url を開いて MP4(10〜60 秒、≤30 MB)を選ばせればページが presign と complete まで行う。 シェルが使える場合は expires_at まで upload.url へ upload.fields をすべて付けたうえで file=@video.mp4 を最後に POST し、complete_video_upload を呼ぶ(curl -F)。 429 ERR_TOO_MANY_VIDEO_JOBS は同時実行上限(3 件)。429 ERR_VIDEO_UPLOAD_DAILY_LIMIT は 24 時間ローリング 20 件/テナント。503 ERR_VIDEO_UPLOAD_UNAVAILABLE は機能が利用不可。 生成・検証は数分かかる。job_id を返したら get_listing_video を 30〜60 秒間隔でポーリングし、status と shop_uploads がすべて終端になるまで待つ(1回のツール呼び出し内で sleep しない)。 get_listing_video で全ショップの shop_uploads が終わるまで確かめ、failed は error_code と一緒に報告する。202 や upload_page_url を渡しただけで完了と言わない。
submit_listing
ChatGPT無人処理・バルク処理で推奨される耐久性のある単品出品。作成前に必ず prepare_listing を実行し、status が ready のストアだけ、その stores[].create_request(画像だけ差し替え)を引数に使う。また出品先の各ストアで get_shopee_shop_info を呼び、status が NORMAL であることを確かめる。 MCP 経由の作成は、prepare_listing のルール(オプション画像の共有・視覚軸のオプション画像・オプション名の重複・ギャラリー画像の重複と枚数・仕入原価と ASIN の形式)に反すると、422(ERR_VALIDATION_FAILED)で拒否される。issues[] の code は prepare_listing と同じ。422 を受けたら作成を繰り返さず、入力を直して prepare_listing からやり直す。作成した出品は UNLIST のまま残し、set_listing_status(listed=true) は呼ばない(公開は出品者が行う)。 item_name と description は出品先ストアの言語で書く(list_stores が provider_id ごとに返す listing_language.code が正)。日本語のまま渡すと日本語のまま公開され、update_item で直すまで戻らない。listing_language が付かないストアは言語を推測せずユーザーに確認する。 images[].image_url は必須。フレームを適用した先頭画像は apply_frame_to_image / compose_variation_thumbnail の戻り値の image_id / image_url / original_url / frame_id をそのまま images[0] に載せる。 呼び出し側が安定した submission_id を必ず作り、タイムアウトや応答喪失後も新しい値に変えないこと。応答の pending / creating 等は受付・処理中であり、公開成功ではない。get_listing_operation を retry_after_seconds 後に呼び、succeeded でも作成物は UNLIST の下書きなので公開は別操作。既存の同期 create_listing は対話的な互換フロー向けに残る。
submit_listing_with_variations
ChatGPT無人処理・バルク処理で推奨される耐久性のあるバリエーション出品。作成前に必ず prepare_listing を実行し、status が ready のストアだけ、その stores[].create_request(画像だけ差し替え)を引数に使う。また出品先の各ストアで get_shopee_shop_info を呼び、status が NORMAL であることを確かめる。 MCP 経由の作成は、prepare_listing のルール(オプション画像の共有・視覚軸のオプション画像・オプション名の重複・ギャラリー画像の重複と枚数・仕入原価と ASIN の形式)に反すると、422(ERR_VALIDATION_FAILED)で拒否される。issues[] の code は prepare_listing と同じ。422 を受けたら作成を繰り返さず、入力を直して prepare_listing からやり直す。作成した出品は UNLIST のまま残し、set_listing_status(listed=true) は呼ばない(公開は出品者が行う)。 item_name と description は出品先ストアの言語で書く(list_stores が provider_id ごとに返す listing_language.code が正)。日本語のまま渡すと日本語のまま公開され、update_item で直すまで戻らない。listing_language が付かないストアは言語を推測せずユーザーに確認する。 images[].image_url は必須。フレームを適用した先頭画像は apply_frame_to_image / compose_variation_thumbnail の戻り値の image_id / image_url / original_url / frame_id をそのまま images[0] に載せる。 model ごとに確認済みの variation_product_id、または新しい子商品を作る new_option=true を指定できる(false でも両方の同時指定は不可)。ASIN や位置から商品を自動選択しない。422 の ERR_VARIATION_MAPPING_REQUIRED は紐付けの明示、ERR_LISTING_BASE_IS_CHILD は親の product_id への修正、ERR_VARIATION_CHILD_SKU_AMBIGUOUS は SellBridge 側の重複SKUの修復が必要。これらは作成前の拒否なので、修正が済むまで再送しない。同期応答または非同期の result にある sku_changes[] の sent_sku を実際のSKUとして記録し、warnings[] も確認する。作成済みの保存失敗の警告があれば再作成せず、既存出品の保存・紐付けを修復する。 variation_mapping_required / listing_base_is_child / variation_child_sku_ambiguous は識別情報の拒否。入力の明示・親IDへの修正、または重複SKUの修復が済むまで再送しない。variation_plan_stale は保存済みの出品計画と現在のデータの不一致。これらで failed かつ item_id が無い場合だけ、原因を修正し prepare_listing で再確認してから同じ submission_id で再送できる。needs_review で item_id がある場合は出品が作成済みなので再送しない。item_id が無い needs_review も作成リクエスト送信済みの可能性があり再送しない。人が対象ショップの既存出品と紐付けを確認・修復する。result.sku_changes[] / result.warnings[] は同期作成と同じ意味なので記録する。 tier_variation と model を指定し、呼び出し側が安定した submission_id を必ず作る。タイムアウトや応答喪失後も新しい値に変えず、同じ provider_id / submission_id で get_listing_operation を呼ぶ。pending / configuring 等は公開成功ではなく、succeeded でも UNLIST の下書き。既存の同期 create_listing_with_variations は互換のため残る。
unlist_item
ChatGPTShopeeの既存商品を出品停止する破壊的操作。どの出品が止まるかは shop_id / item_id で決まる。Go APIは実行前に item_id と sku が同じ商品を指すことを検証し、別商品なら 409 ERR_ITEM_SKU_MISMATCH、SellBridgeが紐付けを持たない出品なら 409 ERR_ITEM_NOT_MAPPED で拒否する(どちらもShopeeには何も送られない)。409 のときは get_shopee_item / get_listing_data で出品を読み直し、その出品を作った sku で送り直す。商品はSellBridgeに残る。
update_item
ChatGPTShopee既存商品の item_sku・商品名・説明・category_id・attribute_list・image_id_list・brand を部分更新する。item_sku / item_name / description / category_id / attribute_list / image_id_list / brand の少なくとも1つを指定し、レスポンスのフィールド別 success を必ず確認すること(異常ステータスの出品は Shopee がフィールド単位で拒否するため、HTTP 200 でも success=false になりうる)。category_id を変えると旧カテゴリの属性はすべて失効する。新カテゴリに必須属性があるときは、同じ呼び出しで get_attributes の必須分を attribute_list に載せる(載せないと Go が 400 で拒否し、Shopee には送られない)。必須属性が無いカテゴリは category_id だけで移せる。category_id と一緒の attribute_list は新しい属性の完全な集合で、省いた任意属性は未設定になる。category_id なしの attribute_list は挙げた attribute_id の値だけを置き換える。自由入力は value_id: 0 と original_value_name、数量は数値を original_value_name に単位を value_unit に、日付は original_value_name に epoch 秒の文字列。get_attributes の value キーはこのツールには無い。brand の brand_id はカテゴリごとに異なる。get_brands で item の(新しい)カテゴリに有効な ID を取る。同じ呼び出しで category_id を変えるときは新カテゴリのブランドを選ぶ。Go は category 移動のあと brand を別の Shopee 呼び出しで送るため、brand の per-field success を読む。brand_id 0(No Brand)のときは original_brand_name が必須。image_id_list は 1〜9 件の 完全な並び で既存ギャラリーを置き換える(先頭がカバー)。差し替え前に get_shopee_item で現行 image_id を読み、新規分は upload_image_url / apply_frame_to_image の image_id を使う。文言・属性・画像を直すために delete_item → create_listing で作り直してはならない。item_id が変わるとレビュー・ランキング・広告・外部リンクが切れ、products.sku と Shopee 側 item_sku の割れも生む。item_id と sku が別商品を指すと Go API が実行前に 409 ERR_ITEM_SKU_MISMATCH(SellBridge が紐付けを持たない出品は 409 ERR_ITEM_NOT_MAPPED)で拒否し、Shopee には何も送られない。409 のときは get_shopee_item / get_listing_data で出品を読み直してから送り直す。
update_item_price
ChatGPTShopee既存商品の価格を更新し、SellBridgeの現地通貨価格とFX自動調整用JPY基準価格も同期する。単品はmodel_idを省略し、バリエーション商品はget_listing_dataで取得した対象ストア固有のmodel_idを使う。各original_priceは現地通貨。JPY基準の価格意図がある場合はprice_jpyを優先して指定し、省略時はGo APIが現在レートで逆換算する。item_id と sku が別商品を指すと Go API が実行前に 409 ERR_ITEM_SKU_MISMATCH(SellBridge が紐付けを持たない出品は 409 ERR_ITEM_NOT_MAPPED)で拒否し、Shopee には何も送られない。409 のときは get_shopee_item / get_listing_data で出品を読み直してから送り直す。
update_stock
ChatGPTShopee既存商品の在庫を更新。単品はstock、バリエーション商品はget_listing_dataで取得した対象ストア固有のmodel_idとstockをmodel_stocksに指定する。item_id と sku が別商品を指すと Go API が実行前に 409 ERR_ITEM_SKU_MISMATCH(SellBridge が紐付けを持たない出品は 409 ERR_ITEM_NOT_MAPPED)で拒否し、Shopee には何も送られない。409 のときは get_shopee_item / get_listing_data で出品を読み直してから送り直す。
upload_image_url
ChatGPT画像URLを指定してShopeeにアップロードし image_id / image_url を返す。Go APIがサーバー側でダウンロードするJSON方式(公開HTTPS URLのみ、JPEG/PNG)。返った image_id / image_url を create_listing の images にそのまま渡す。