なお、ここで書く挙動は Yahoo!ショッピングのAPIについて確認した内容です。楽天やAmazonのAPIは検証していないため、同じ性質かどうかは断定しません。
商品名と説明文だけを送ったら、他の項目が消えた
作っていたツールの構成
ツールの流れは、計測、分析、改善案の生成、人の承認、反映、再計測のループです。
- 計測：競合の取得と順位の計測。取得は Yahoo!ショッピングの公式の商品検索APIを使い、スクレイピングはしていません
- 改善案の生成：商品名と説明文の案をAIが作る
- 承認：スプレッドシートのチェック列に、人がチェックを入れる
- 反映：スプレッドシート側の仕組み（GAS）が、承認された案をストアへ書き込む
当初の設計では、AI側は案を作るだけで、書き込みはGASが担当する想定でした。承認のチェック列があるので、人の確認は挟まっています。ここまでは、安全な設計のつもりでした。
2026年6月16日、実在のストアで書き込みを検証した
6月16日、反映（書き込み）の部分を実在のストアで実機検証しました。1件ずつ商品を更新するAPI（editItem）に、商品名と説明文だけを送っています。
結果は、実在の商品3点で、次の項目が消えるというものでした。
- 画像
- ブランド
- META情報
- 関連商品
- スマホ用フリースペース
これらの商品は影響が小さく、復旧は不要と判断できました。ただ、主力商品で同じことが起きていたら、と考えると、検証の段階で気づけたのは幸いでした。
消えた理由は「上書き型」のAPIだったこと
部分更新だと思い込んでいた
私たちは editItem を「送った項目だけを変えるAPI」だと思って使いました。実際には、送らなかった項目を初期化する上書き型でした。
名前と説明文だけを送ると、APIから見れば「この商品のデータは名前と説明文だけです」という指示になります。そのため、残りの項目は空に戻りました。
部分更新と上書きの見分け方
この違いは、APIの名前だけでは判断できません。更新系のAPIを使う前に、次の点を確かめるのが現実的です。
- 公式仕様に「送らなかった項目の扱い」が書かれているか
- 書かれていない場合、テスト用の商品で実際に送って確かめたか
- 更新の前後で、商品データ全体を比較できるか
今回、私たちは3つ目の比較をしていませんでした。実機で更新したあとに、画像などが空になっていることに気づいた形です。
同じモールに「非破壊」の入口もあった
一方で、同じ Yahoo!ショッピングには、商品データのファイルアップロードで「項目指定」という方式があります。公式仕様に記載されており、ファイルに含めた列だけを更新し、他の項目は保持します。つまり非破壊です。
同じモールの中に、上書き型の入口と、部分更新の入口が両方ありました。「商品を更新する」という同じ目的でも、入口によって安全性が違います。
CSVで一括更新するときに触っていない列が壊れる問題と、差分更新・退避の運用は、モール商品CSV一括更新｜差分更新と退避で事故を防ぐ運用設計で扱っています。この記事の主眼は、APIの書き込みの性質と、ツールに書き込み権限を持たせない判断です。
全反映のロックと、書き込み権限の壁
上書きの問題のほかに、APIで日常的に書き込む運用を難しくする事実が2つありました。
全反映はストア全体の編集を長時間ロックする
更新内容を店舗に反映する「全反映」の操作は、実行中にストア全体の編集をロックします。APIからも管理画面からも編集できなくなり、このとき返るのがエラーコード ed-00006 です。
自動で何度も反映をかける運用では、出店者が管理画面で作業している最中にロックがかかる可能性があります。日常的にAPIを回す用途には向きません。ロックの具体的な長さは今回の記録で計測していないため、ここには書きません。
書き込みには出店者向けの専用登録が要る
もう1つは権限の壁です。書き込み用のAPIを使うには、通常の新規アプリ登録では足りませんでした。出店者向けの専用登録が必要で、条件は次のとおりです。
- 本番環境用であること
- ID連携ありであること
- サーバーサイドのアプリであること
通常登録のままでは「利用可能なスコープなし」となり、使えませんでした（エラー px-04104）。読み取りのAPIは通常登録で動いたので、書き込みだけが別の扱いになっている形です。
ツールは読み取り専用にして、項目指定CSVを人がアップロードする
判断の理由
このツールは、私たち自身のストアではなく、他の出店者（購入者）の本番ストアで動きます。壊したら責任を取れません。
上書き型の挙動、全反映のロック、専用登録の壁を並べた結果、API書き込みの経路を残す利点より、事故の可能性のほうが大きいと判断しました。そこで、API書き込みのコードをすべて削除しました。
注意して運用するのではなく、そもそも書き込む手段を持たせないことで、構造的に事故が起きない形にしたということです。
新しい反映の流れ
- AIが改善案を作る
- 人がスプレッドシートのチェック列で承認する
- 承認された案だけが、スプレッドシートの「反映用CSV」タブに書き出される
- 人が、ストアクリエイターProの商品データアップロードで「項目指定」を選び、CSVをアップロードする
「反映用CSV」タブの列は、商品コード・商品名・商品情報（説明文）の3つだけです。項目指定はファイルに含めた列だけを更新するので、3列しか持たないCSVなら、画像やブランドなど他の項目に手が及びません。今回の事故の原因を、仕組みの側から避けられます。
説明文は制約に合わせて整形して出す
商品情報欄には、500字まで、HTMLは使えない、という制約があります。AIが作った説明文をそのまま出すと、この制約に合わないことがあります。そのため、書き出しの段階で整形し、制約に合う形でタブに出すようにしました。
読み取り側は、これまでどおり自動で回している
競合の取得、順位の計測、改善案の生成は、APIのまま自動で動いています。読むのは自動、書くのは人、という線引きです。
読み取りの側にも落とし穴はありました。順位の計測で全件が圏外と出たことがあり、主因は商品コードの大文字・小文字の区別でした。小文字にそろえ、接頭辞を除いてから照合するようにして解消しています。
それでも書き込みを自動化したい人が先に確かめること
私たちは削除する道を選びましたが、続ける場合に確認したい点を挙げます。以下は一般論で、すべてのモールで同じとは限りません。必ず自分の使うAPIの仕様で確かめてください。
テスト商品1件で、送らない項目が残るかを見る
本番の商品に触る前に、テスト用の商品を1件用意します。更新したい項目だけを送り、画像、ブランド、関連商品など、送っていない項目が残っているかを確認します。APIの応答だけでなく、管理画面で見える状態や店舗の表示まで確認するのが安全です。
更新前のデータを退避しておく
更新の直前に、対象商品のデータを保存しておきます。万一項目が消えても、元のデータがあれば戻せます。
公式仕様で「非破壊」と書かれた入口を優先する
項目指定のように、公式仕様で「含めた列だけを更新する」と明記された入口があれば、それを優先して選ぶ価値があります。仕様に書かれていない挙動は、実機で確かめるまで信用しない、という姿勢が今回は効きました。
ロックと権限の条件を、実装の前に確認する
全反映のようにストア全体に影響する操作がないか、書き込みに必要な登録や権限の条件は何か。これらは実装に入る前に確認できる事項です。私たちは、実機で初めてエラー（ed-00006、px-04104）に当たりました。
他のモールについて
楽天やAmazonのAPIは、今回の検証の対象外です。同じ性質かどうかは確認が必要で、この記事から類推はしないでください。
どこまでAIに任せ、どこから人がやるか
- AIと自動処理に任せる：競合の取得、順位の計測、分析、改善案の生成、CSVの書き出しと整形
- 人がやる：承認（チェック列）、ストアクリエイターProでの項目指定アップロード
分け方の基準は、間違えたときに店舗へ影響が出るかどうかです。読み取りは、間違っても店舗のデータは変わりません。書き込みは、間違うと商品ページそのものが変わります。
人がアップロードするひと手間は残りますが、アップロードの直前に、何が書き換わるかをCSVで目視できます。更新の対象が3列だけなので、確認の負担も小さく済みます。
AIに商品ページを書き換えさせたい場合でも、最初に決めるのは「どの項目を、どの入口から、誰が書き込むか」です。私たちのツールは、読む権限は持たせ、書く権限は持たせない形に落ち着きました。