Coupang Open APIで商品カタログをアップロードできますか？

CoupangのOpen APIでは、カタログから構造化された商品登録情報を作成できますが、あらゆるカタログを取り込める汎用インポーターではありません。信頼性の高い連携では、まず各SKUとバリエーションをCoupangのカテゴリーメタデータに基づいて正規化し、有効な購入オプションを送信します。そのうえで、却下されたレコードや書類対応が必要なレコードをレビューキューに振り分けます。

Coupang Open APIで商品登録のどこまで自動化できるか

Open APIは、スキーマによって制約された送信レイヤーだと考えると分かりやすいです。ソースレコードがCoupangに受け入れられるフィールドと値へ変換されていれば、ソフトウェアでペイロードの構築、購入オプションの生成、レコードの送信、結果の記録といった反復作業を実行できます。

これは、PIMでいう広義のカタログインポートとは異なります。グローバルカタログには通常、親商品、バリエーション、説明文、メディア、識別子、複数の市場で使えるように設計された属性が含まれます。Coupangの登録構造には、カテゴリー固有の要件と許可された値が加わります。APIはこの変換結果を送信できますが、変換方法を代わりに判断するものではありません。

この違いは、欧米ブランドにとって重要です。コネクターは見栄えがよくても、実際には送信工程しか処理していないことがあります。タイトル、価格、SKUコードをAPIリクエストにコピーすることは、完全な商品登録ワークフローを構築することと同じではありません。カテゴリーが間違っていたり、必須の購入オプションが欠けていたり、許可された値が誤ったデータ型で表現されていたりすれば、自動化は単に失敗を早めるだけです。

技術面での一次情報として、Coupangの公式Open API開発者向けドキュメントを参照してください。カテゴリーメタデータの照会、商品登録のガイダンス、結果やエラーの挙動を基準に、連携を設計してください。サードパーティー製コネクターのフィールド一覧は古くなる可能性があるため、現在のCoupangドキュメントに取って代わるものではありません。

この記事では商品登録を扱います。価格と在庫には別のAPIワークフローを使用します。詳しくは価格と在庫にCoupangで別々のAPI呼び出しが必要な理由をご覧ください。

なぜ商品登録の前にカテゴリーマッピングが必要なのか

カテゴリーマッピングは、最初の却下バッチが出てから行う対応ではなく、実装の初期段階で作るべき成果物です。Coupangの必須フィールドと許可された値はカテゴリーごとに異なります。一方、グローバルPIMは通常、どこでも再利用できるよう設計された汎用的な属性を中心に構成されています。

したがって、連携側は商品ペイロードを生成する前にカテゴリーメタデータを照会する必要があります。この照会によって、選択したカテゴリーが求める構造が分かります。具体的には次のとおりです。

• 必須の購入オプションとして表示する項目
• いずれか1つの選択が必要なグループ化属性
• 適用されるデータ型
• 利用可能な単位や値

これらの詳細によって、ソースカタログをどのように変換すべきかが決まります。グローバルフィールド名がsizeであっても、それだけではCoupang側のフィールドが特定の型、単位、または制約付きの値を求めているかは分かりません。複数のバリエーションを持つ親商品だけでは、マッピングした属性のうちどれを購入オプションにする必要があるかも分かりません。名称が見慣れたものでも、データ契約は異なる可能性があります。

実務的なマッピング手順は次のとおりです。

1. 候補となるCoupangカテゴリーを選択します。 送信しやすいという理由だけで、汎用フォールバックカテゴリーを恒久的な選択肢にしないでください。
2. そのカテゴリーについてメタデータを取得します。 選択した構造に適用される必須オプション、グループ化属性、データ型、単位、許可された値を記録します。
3. グローバルスキーマをマッピングします。 ソースフィールド、Coupangフィールド、必要な変換、データが欠落または無効な場合の処理ルールを定義します。
4. 購入オプションを生成します。 ブランドのバリエーションモデルを、グローバルのバリエーションオブジェクトをそのまま送るのではなく、そのカテゴリーが求めるオプション構造に変換します。
5. 送信前に検証します。 必須フィールドの欠落、無効なデータ型、利用できない値、形式が不正なオプションの組み合わせを、連携側のレビュー層で検出します。

マッピングはカテゴリー固有にする必要があります。汎用的なフィールドマップを1つだけ用意する方法は、エンジニアリング上は魅力的ですが、運用では脆弱です。2つのカテゴリーで公開されるオプション構造が異なる場合、同じソース属性でもカテゴリーごとに別の変換が必要になることがあります。すべてのカテゴリーが同じスキーマを共有しているかのように扱うと、カタログのバリエーションに不整合が生じ、手作業による修正を繰り返すことになります。

カテゴリーマップは、内容を確認できる状態で管理してください。レビュー担当者が、ソースからCoupangへのフィールド割り当てと適用した変換を確認できるようにします。マップには、ソース値が空欄の場合の処理も示してください。この記録はAPIリクエスト自体と同じくらい重要です。個々の商品登録を1件ずつ修正するのではなく、チームがマッピングモデルそのものを修正できるようになるからです。

韓国語のタイトルや完成度の高い画像セットがあっても、カテゴリーの不一致は解消できません。ローカライズによって商品ページは読みやすくなりますが、有効なカテゴリー構造や必須の購入オプションの代わりにはなりません。Open APIには、データとして整合し、顧客が選択・購入できる商品としても一貫した商品登録情報を渡す必要があります。

SKUとバリエーションの識別情報を維持する方法

カテゴリーマッピングがフィールドの意味を明らかにするのに対し、IDマッピングは、どのソースSKUがCoupang上で作成され、却下され、修正され、その後照合されたのかを明らかにします。

ブランドのグローバル商品IDまたはバリエーションIDと、Coupangの販売者商品コードを結び付ける、恒久的なSKU対応表（クロスウォーク）を作成してください。カタログに選択可能なオプションがある場合は、販売可能なバリエーションのレベルで対応表を管理してください。複数の購入オプションを個別に購入できる場合、親商品だけでは不十分です。

Coupangのドキュメントでは、外部SKUとの関係を示すフィールドとしてexternalVendorSkuを案内しています。ここには、タイトル、価格、現在のオプションテキストから新しい値を生成するのではなく、安定したグローバルSKUまたはバリエーション識別子を設定してください。タイトルやマーチャンダイジング関連のフィールドは変更される可能性があります。照合に使う識別子は、商品情報をローカライズしたり修正したりしただけで変わってはいけません。

CoupangのextraPropertiesには追加の社内参照情報を保持できますが、これらはストアフロントに表示されるフィールドではありません。たとえば社内の商品システムの参照IDを加えるなど、対応表を補完するために利用できます。ただし、顧客に表示するコンテンツや、管理された照合記録の代わりとして扱ってはいけません。

少なくとも、社内レコードで次の情報を関連付けてください。

• グローバル商品ID
• グローバルバリエーションIDまたはSKU ID
• Coupangの販売者商品コード
• externalVendorSkuの値
• ペイロード構築に使ったカテゴリーマッピング
• 送信、却下、修正、書類レビューの状態

これらの関係をペイロードの外側で保持すると、運用チームは基本的な問いに確実に答えられます。このCoupangの商品登録情報は、どのソースレコードを表しているのか、という問いです。さらに、よくある再試行の問題、つまり修正したペイロードを新規商品として送信してしまう問題も防げます。対応表がなければ、元のレコードがすでに存在するかどうかを連携側で判断できません。

同じ販売者アカウントに複数の社内システムを接続する場合は、自動化を有効にする前に、そのアーキテクチャを決めておいてください。Coupang Open API：2つのシステムで1つのSeller IDを共有できますか？では、コネクターの所有権とSeller IDのルーティングを、競合する2つの連携に任せず、明示的に決める必要がある理由を説明しています。

却下と必要書類をどのように扱うか

APIによる送信は、商品登録の完了と同じではありません。Coupangの商品登録ガイダンスによれば、無効な送信では問題のある行が特定されます。連携ではこの情報を使い、何が失敗したか分からないままカタログ全体を失敗扱いにするのではなく、該当レコードを具体的な修正対応へ振り分ける必要があります。

実用的な例外キューでは、少なくとも次の処理を行えるようにします。

1. 元のソースペイロードを保持します。
2. 実際に送信した変換済みペイロードを保持します。
3. レスポンスを該当する商品・バリエーション・フィールドに紐付けます。
4. 返された理由を、レビュー担当者が対応できる形式で表示します。
5. 修正後の値またはマッピングを記録できるようにします。
6. 直前の試行を失わずに、修正済みレコードを再試行できるようにします。
7. 照合と監査のために履歴を保持します。

この設計により、データエラーと判断エラーを切り分けられます。誤ったデータ型は、カテゴリー変換の中で修正できる場合があります。必須の購入オプションが欠けている場合は、マッピングの判断が必要になることがあります。書類が必要な商品では、担当者が適格性を確認し、証拠書類を収集しなければならない場合があります。自動再試行が適切なのは、修正内容と失敗理由を理解できているケースです。却下されたすべてのペイロードに対して行うものではありません。

並行輸入品は、この境界を明確に示す例です。並行輸入品の場合は、requiredDocumentsに並行輸入品であることを示す区分と輸入申告書類を含めてください。APIコネクターはその情報を送信できますが、商品の適格性、輸入手続き、書類対応に関する本来の作業をなくすことはできません。書類フィールドが存在することは、その書類が承認されたことを意味しません。

このため、書類対応にはワークフロー内で専用のステータスを持たせる必要があります。「書類が必要」「書類受領済み」「審査中」「送信準備完了」を「API完了」にまとめてはいけません。韓国で別途適用される輸入要件や安全要件については、所管当局に確認してください。商品によっては、Korea Customs Service、Ministry of Food and Drug Safety (MFDS)、Korea Agency for Technology and Standards (KATS)、またはlaw.go.krに掲載された関連法令を確認する必要があります。Coupangの開発者向けドキュメントはデータ形式を説明するものです。商品ルールを所管する当局の代わりにはなりません。

自社開発か既製ツールか：実用的な連携を見極める5つのテスト

自社開発か既製ツールかを検討する際、間違った問いは「このツールはCoupangに接続できるか」です。コネクターは、問題のないペイロード1件でデモに成功しても、カテゴリーメタデータの更新、オプション検証、例外の振り分けに対応できないことがあります。本当に確認すべきなのは、グローバルカタログを継続的に運用できる韓国向け商品登録へ変換する途中の作業まで処理できるかどうかです。

連携を次のテストで評価してください。

1. カテゴリーメタデータの更新。 必須の購入オプションとして表示する項目、グループ化属性、データ型、単位、利用可能な値を含む、カテゴリー固有の要件を取得して適用できますか。カテゴリー構造が変わったときに、チームでマップを更新できますか。それともロジックが固定テンプレートに埋め込まれていますか。
2. バリエーションとオプションの生成。 親商品とバリエーションのレコードを、各カテゴリーで有効な購入オプションに変換できますか。送信前に、必須オプションが欠けたレコードを止められますか。それともCoupangの却下に頼ることになりますか。
3. 識別情報と追跡可能性。 グローバルSKUを保持し、externalVendorSkuを一貫して使用し、レコードをCoupangの販売者商品コードに紐付け、ソースと変換済みの両方のペイロードを保持できますか。
4. 却下と書類対応。 失敗した行とフィールドを表示し、レコードをエラーキューに振り分け、修正と再試行をサポートし、requiredDocumentsに該当するケースを通常のデータエラーと区別できますか。
5. 運用上の境界。 商品登録と、その後の価格・在庫ワークフローを明確に分け、複数のシステムが同じSeller IDへの接続をめぐって競合することを防げますか。

タイトル、価格、SKUコードをコピーするだけのツールは、商品登録のための完全な連携ではありません。送信コンポーネントとしては有用かもしれませんが、欠けているマッピング層と例外処理層は、どこか別の場所に存在しなければなりません。それがスプレッドシートや場当たり的なメッセージのやり取りに埋もれているなら、見かけ上の自動化は、手作業を見えない場所に移しているにすぎません。

最初からカタログ全体を送るのではなく、段階的に展開してください。

1. 実際の品ぞろえから代表的なカテゴリーを選びます。事業上意味のあるバリエーション構造と、ビジネスにとって重要な書類対応が必要なカテゴリーを含めてください。
2. カテゴリーメタデータを取得し、それらのカテゴリーについてソースからCoupangへの明示的なマッピングを作成します。
3. 代表的なレコードを絞って送信し、成功した結果と却下された行の両方を確認します。
4. 自動化の範囲を広げる前に、マッピングルール、オプション生成、レビュー状態の定義と運用を整えます。
5. マッピングが安定したカテゴリーを自動化し、新規カテゴリー、却下されたレコード、書類対応が必要な商品登録は人手レビューの対象として残します。

準備完了の正しい判定基準は、送信した行数ではありません。各商品登録がソースSKUまで追跡でき、各失敗に明確な次のアクションがあることが重要です。レビュー担当者がエンジニアにペイロードの再構成を依頼せずに例外を修正できる状態にしてください。

Coupangのカタログ自動化に関するよくある質問

グローバルPIMのエクスポートを送って、Coupangにカテゴリーを選ばせることはできますか？

いいえ。信頼できる商品ペイロードを構築するには、まずCoupangのカテゴリーとそのメタデータを選択する必要があります。Open APIは、グローバルの分類体系を代わりに解釈してくれる汎用インポーターではありません。

APIで商品バリエーションを作成できますか？

はい。バリエーションをカテゴリー構造にマッピングした後であれば、定型的な購入オプションの生成を自動化できます。ただし、どのグローバル属性が有効なオプションか、またはグループ化属性の要件を満たすかを、そのマッピングなしに安全に判断することはできません。

ブランドのSKU対応表はどこに保存すべきですか？

安定したグローバル商品IDまたはバリエーション識別子を使い、それをCoupangの販売者商品コードにマッピングしてください。Coupangのドキュメントでは、外部SKUとの関係にexternalVendorSkuを使用すると説明されています。extraPropertiesで社内参照情報を追加できますが、ストアフロントのコンテンツや唯一の照合記録として扱うべきではありません。

API送信が成功すれば、商品が販売可能な状態だと証明できますか？

いいえ。その時点で適用された登録チェックをリクエストが通過したことを示すだけです。輸入適格性、必要書類、カテゴリー固有のコンプライアンス、後続の現物入庫チェックが未完了のまま残ることがあります。Coupangの入庫確認：ラベルと証明書の審査では、この別のチェックポイントについて説明しています。

一括送信の1行が失敗した場合、どうすべきですか？

元のペイロードと変換済みペイロードを保持し、失敗したフィールドを正確に特定して、レコードをレビューキューに振り分け、修正内容を記録したうえで再試行してください。リクエストを送信しただけでカタログ全体を完了扱いにしないでください。

すべてのカテゴリーを一度に自動化すべきですか？

いいえ。まず代表的なカテゴリーをマッピングしてテストし、マッピングが安定したカテゴリーを自動化してください。ワークフローの有効性が確認できるまでは、新規、却下、または書類対応が必要なレコードを人手レビューの対象にします。