Yahoo!・Qoo10・Amazon の3モール在庫同期API「キャメル vs スネーク」混在地獄

EC事業者がいちばん事故りやすい業務、それがマルチモールの在庫同期。弊社ではAmazon・Yahoo!ショッピング・Qoo10・自社ECの4モールを並行運営しているが、特にYahoo!とQoo10のAPI実装でどうしても乗り越えられない壁にぶつかった。

それが「APIキー命名規則の混在地獄」だ。

【問題の発端】

VOMS（自社SaaS）の在庫同期機能を実装中、Yahoo!の商品情報を取得する処理で何度叩いてもmissing required parameter: sellerIdエラー。リクエストには確かにseller_idを渡しているのに認識されない。

ドキュメントを再確認したら、まさかの仕様：
・Yahoo!ショッピング 注文API：sellerId（キャメルケース）
・Yahoo!ショッピング 商品管理API：seller_id（スネークケース）

同じYahoo!のAPIなのに、商品管理APIと注文APIで命名規則が違う。

【各モールの命名規則カオス】

◆Yahoo!ショッピング
・注文API：キャメルケース
・商品管理API：スネークケース
・在庫API：スネークケース
・ダウンロード受信箱API：キャメルケース
→同じプロバイダー内で混在

◆Qoo10
・商品API：パスカルケース
・注文API：パスカルケース
・クレームAPI：一部キャメルケース
→統一感はあるがメソッド名がドキュメントと異なる場合がある

◆Amazon SP-API
・全API：スネークケース
→Amazonは比較的統一

【Qoo10で更にハマったメソッド名問題】

Qoo10で「公式ドキュメントに書いてあるメソッド名が間違っている」という事案にも遭遇した。

公式ドキュメントには：
・ClaimBasic.GetClaimInfo（クレーム照会）
・CustomerQnABasic.GetMessage（問い合わせ照会）

と書かれているが、実際の正しいメソッド名は：
・ShippingBasic.GetClaimInfo_V3
・CSCenter.GetInquiryMessage

ドキュメントが更新されておらず、実装初心者は確実に詰む。

【解決策：APIラッパー層で命名を統一】

実装上の解決策は、全APIを薄いラッパー層で包むこと。各モールのAPIを共通のインターフェース（get_orders, update_inventory, get_product）で抽象化し、ラッパー内部でモール固有の命名（sellerIdやItemCode）をスネークケースに正規化。これで業務ロジック側はモール固有の命名を意識しなくて済む。

【ドキュメントを信用しない、レスポンスログを保存する】

API実装で詰まらないためのルール：
1. 「公式ドキュメントは最新ではない」前提。最新仕様は実際にAPIを叩いて返ってきたレスポンスを正とする
2. 全リクエスト・レスポンスをログ保存
3. MCPツール作成時は「実APIレスポンスを開示する」

【ハマる前に知っておけば、半年は短縮できる】

弊社がVOMS開発に費やした1年半のうち、API命名規則の混乱で溶かした時間は推定200時間以上。これからEC自動化に挑む方には、ばひこの記事を見て地雷を回避してほしい。

マルチモールEC自動化システム開発、ココナラのDMからお気軽にご相談ください。