Mercari Shops API フィールド仕様

このドキュメントでは、Mercari Shops APIとCSVフォーマット間のフィールドマッピングとその仕様を詳細に説明します。

重要な仕様 - 必読

CSV Import Format Requirements

72カラム形式（インポート用）:

カラム数: 厳密に72カラム
ヘッダー/データ整合性: ヘッダー行とデータ行のカラム数が完全一致必須
数値変換: APIのEnum値は全て数値に変換
都道府県コード: jp01-jp47形式を維持（日本語変換不要）

162カラム形式（エクスポート専用）:

Mercariからのエクスポート時のみ使用
インポートには使用不可
72カラムへの変換が必要

フィールド概要

商品基本情報

商品ID (product_id) - システム内部ID
商品名 (name/title) - 商品タイトル（最大130文字）
商品説明 (description) - 詳細説明（最大5000文字）

カテゴリ・ブランド

カテゴリ (category/category_id) - 商品カテゴリ
ブランド (brand_id) - ブランドID

商品状態・価格

商品の状態 (itemCondition) - コンディション（1-6の数値）
販売価格 (price) - 価格（300円〜9,999,999円）
在庫数 (stock) - 在庫数量（1〜999）

配送情報

配送料の負担 (shippingPayer) - 送料負担者
配送の方法 (shippingMethod) - 配送方法
発送元の地域 (shippingOrigin) - 発送元地域
発送までの日数 (shippingDuration) - 発送までの期間

ステータス管理

商品ステータス (productStatus) - 公開状態

フィールド仕様詳細

商品の状態 (Item Condition)

商品のコンディションを指定します。フォームでは直接数値（1-6）として管理されます。

フォーム値	CSV値	表示ラベル	説明
`1`	`1`	新品、未使用	商品が完全に新品で未使用の状態
`2`	`2`	未使用に近い	ほぼ新品、または非常に軽い使用のみ
`3`	`3`	目立った傷や汚れなし	通常使用による軽微な痕跡のみ
`4`	`4`	やや傷や汚れあり	多少の傷や汚れがある状態
`5`	`5`	傷や汚れあり	明確な使用感、傷、汚れがある
`6`	`6`	全体的に状態が悪い	状態が悪く、修理が必要な場合も

実装詳細:

フォームフィールド名: itemCondition
直接数値として保存・出力（API Enum変換不要）
ITEM_CONDITIONS定数で選択肢を定義

配送方法 (Shipping Method)

商品の配送方法を指定します。重要: CSVと同じ数値を直接使用します（変換不要）。

CSV値	表示ラベル	説明
`1`	未定(出品者が手配)	配送方法は後日決定
`2`	クール便	温度管理が必要な商品用
`3`	らくらくメルカリ便	ヤマト運輸提携の標準配送
`4`	クールメルカリ便(冷蔵)	冷蔵配送サービス
`5`	クールメルカリ便(冷凍)	冷凍配送サービス
`6`	メルカリBiz配送	事業者向け配送サービス

実装詳細:

フォームフィールド名: shippingMethod
数値（1-6）を直接使用（変換不要）
SHIPPING_METHODS定数で選択肢を定義
Updated 2025-11-20: API Enum文字列から数値形式に変更

発送元の地域 (Shipping Origin) - CRITICAL

発送元の都道府県を指定します。重要: インポート時はコード形式を維持

CSV Import Format (必須形式):

jp01 - 北海道
jp13 - 東京都
jp27 - 大阪府
jp47 - 沖縄県
ex99 - 海外

エラーを防ぐための注意:

❌ 間違い: "東京都", "大阪府" (日本語名)
✅ 正しい: "jp13", "jp27" (コード形式)

実装詳細:

フォームフィールド名: shippingOrigin
mapShippingOrigin()関数は変換せずそのまま返す
SHIPPING_ORIGINS定数で選択肢を定義（value: jpコード、label: 日本語名）

都道府県コード一覧

const SHIPPING_ORIGINS = [
  { value: 'jp01', label: '北海道' },
  { value: 'jp02', label: '青森県' },
  { value: 'jp03', label: '岩手県' },
  { value: 'jp04', label: '宮城県' },
  { value: 'jp05', label: '秋田県' },
  { value: 'jp06', label: '山形県' },
  { value: 'jp07', label: '福島県' },
  { value: 'jp08', label: '茨城県' },
  { value: 'jp09', label: '栃木県' },
  { value: 'jp10', label: '群馬県' },
  { value: 'jp11', label: '埼玉県' },
  { value: 'jp12', label: '千葉県' },
  { value: 'jp13', label: '東京都' },
  { value: 'jp14', label: '神奈川県' },
  { value: 'jp15', label: '新潟県' },
  { value: 'jp16', label: '富山県' },
  { value: 'jp17', label: '石川県' },
  { value: 'jp18', label: '福井県' },
  { value: 'jp19', label: '山梨県' },
  { value: 'jp20', label: '長野県' },
  { value: 'jp21', label: '岐阜県' },
  { value: 'jp22', label: '静岡県' },
  { value: 'jp23', label: '愛知県' },
  { value: 'jp24', label: '三重県' },
  { value: 'jp25', label: '滋賀県' },
  { value: 'jp26', label: '京都府' },
  { value: 'jp27', label: '大阪府' },
  { value: 'jp28', label: '兵庫県' },
  { value: 'jp29', label: '奈良県' },
  { value: 'jp30', label: '和歌山県' },
  { value: 'jp31', label: '鳥取県' },
  { value: 'jp32', label: '島根県' },
  { value: 'jp33', label: '岡山県' },
  { value: 'jp34', label: '広島県' },
  { value: 'jp35', label: '山口県' },
  { value: 'jp36', label: '徳島県' },
  { value: 'jp37', label: '香川県' },
  { value: 'jp38', label: '愛媛県' },
  { value: 'jp39', label: '高知県' },
  { value: 'jp40', label: '福岡県' },
  { value: 'jp41', label: '佐賀県' },
  { value: 'jp42', label: '長崎県' },
  { value: 'jp43', label: '熊本県' },
  { value: 'jp44', label: '大分県' },
  { value: 'jp45', label: '宮崎県' },
  { value: 'jp46', label: '鹿児島県' },
  { value: 'jp47', label: '沖縄県' },
  { value: 'ex99', label: '海外' }
];

発送までの日数 (Shipping Duration)

商品発送までの予定日数を指定します。重要: CSVと同じ数値を直接使用します（変換不要）。

CSV値	表示ラベル	説明
`1`	1〜2日で発送	迅速な発送対応
`2`	2〜3日で発送	標準的な発送期間
`3`	4〜7日で発送	1週間以内の発送
`4`	8〜14日で発送	2週間以内の発送
`5`	90日以内で発送	長期または未定の発送期間

実装詳細:

フォームフィールド名: shippingDuration
数値（1-5）を直接使用（変換不要）
SHIPPING_DURATIONS定数で選択肢を定義
Updated 2025-11-20: API Enum文字列から数値形式に変更

配送料の負担 (Shipping Payer)

送料の負担者を指定します。重要: CSVと同じ数値を直接使用します（変換不要）。

CSV値	表示ラベル	説明
`1`	送料込み(出品者負担)	出品者が送料を負担
`2`	送料別（購入者負担）	購入者が送料を負担

実装詳細:

フォームフィールド名: shippingPayer
数値（1-2）を直接使用（変換不要）
SHIPPING_PAYERS定数で選択肢を定義
Updated 2025-11-20: API Enum文字列から数値形式に変更

商品ステータス (Product Status)

商品の公開状態を管理します。重要: 実装では値が逆になっています。

フォーム値	CSV値	表示ラベル	説明
`1`	`1`	公開中	商品が公開されて購入可能な状態（Active）
`2`	`2`	下書き	商品情報は保存されているが非公開（Draft）

実装詳細:

フォームフィールド名: productStatus
直接数値として保存・出力（変換不要）
PRODUCT_STATUSES定数で選択肢を定義
デフォルト値: '2' (下書き)

72カラムCSVインポート仕様（正確な配置）

重要: カラム位置が1つでもずれるとインポートエラーになります。

カラム	フィールド名	値の形式	必須	備考
0-19	商品画像名_1〜20	URL/ファイル名	No	画像URL
20	商品名	テキスト	Yes	最大130文字
21	商品説明	テキスト	Yes	最大5000文字、改行は`
`
22-61	SKU情報（10セット）	各4カラム	Partial	詳細は下記参照
62	ブランドID	数値/空	No	空欄可
63	販売価格	数値	Yes	300-9999999
64	カテゴリID	文字列	Yes	リーフカテゴリのみ
65	商品の状態	数値	Yes	1-6（直接数値）
66	配送方法	数値	Yes	1-6（直接数値）
67	発送元の地域	jpコード	Yes	jp01-jp47形式
68	発送までの日数	数値	Yes	1-5（直接数値）
69	商品ステータス	数値	Yes	1=公開中, 2=下書き
70	配送料の負担	数値	Yes	1-2（直接数値）
71	送料ID	文字列/空	No	通常は空欄

SKU情報の詳細構造（カラム22-61）

各SKU（1-10）は4カラムずつ使用:

オフセット	フィールド	カラム位置（例：SKU1）
+0	SKU[n]_種類	22
+1	SKU[n]_在庫数	23
+2	SKU[n]_商品管理コード	24
+3	SKU[n]_JANコード	25

重要: SKU1_在庫数（カラム23）は必須。最低でも1を設定。

フォームフィールドとCSVカラムのマッピング

DraftFormのフィールド構造

const formState = {
  // 基本情報
  name: '',           // 商品名 → カラム20
  description: '',    // 商品説明 → カラム21
  category: '',       // カテゴリID → カラム64
  price: '',         // 販売価格 → カラム63
  itemCondition: '', // 商品の状態 → カラム65（数値1-6）
  productStatus: '', // 商品ステータス → カラム69（数値1-2）
  
  // 画像
  images: [],        // 商品画像 → カラム0-19
  
  // 配送情報
  shippingMethod: '',   // 配送方法 → カラム66（数値1-6）
  shippingOrigin: '',   // 発送元の地域 → カラム67（jpコード）
  shippingDuration: '', // 発送までの日数 → カラム68（数値1-5）
  shippingPayer: '',    // 配送料の負担 → カラム70（数値1-2）
  
  // SKU情報
  stock: '',         // SKU1_在庫数 → カラム23
};

値の取り扱い（Updated 2025-11-20）

重要な変更点

2025-11-20以降の実装では、すべてのフィールドでCSVと同じ数値を直接使用します。

❌ 旧実装: API Enum文字列 (METHOD_TYPE_UNDECIDED, PAYER_TYPE_SELLERなど) を数値に変換
✅ 新実装: 数値（'1', '2', '3'など）を直接使用（変換不要）

変換が不要なフィールド

以下のフィールドは、すべて数値文字列（'1' - '6'）を直接使用します：

shippingMethod: '1' - '6' (配送方法)
shippingDuration: '1' - '5' (発送までの日数)
shippingPayer: '1' - '2' (配送料の負担)
productStatus: '1' - '2' (商品ステータス)
itemCondition: '1' - '6' (商品の状態)

特殊な取り扱いが必要なフィールド

shippingOrigin (発送元の地域):

jpコード形式（'jp01' - 'jp47', 'ex99'）をそのまま使用
日本語名への変換は行わない

デフォルト値（Updated 2025-11-20）

// settings.mjs の定数でデフォルト値として使用される数値
export const DEFAULT_VALUES = {
  shippingMethod: '3',      // らくらくメルカリ便
  shippingOrigin: 'jp11',   // 埼玉県 (Saitama) - DEFAULT
  shippingDuration: '2',    // 2〜3日で発送
  shippingPayer: '1',       // 送料込み(出品者負担)
  productStatus: '1',       // 下書き (Draft) - 1=Draft, 2=Published
  itemCondition: '1',       // 新品、未使用
};

重要: すべて数値文字列を使用します（API Enum文字列は使用しません）。

バリデーションルール

価格: 300円〜9,999,999円の範囲内
商品名: 最大130文字
商品説明: 最大5000文字
在庫数: 1〜999の範囲内（SKU1_在庫数は必須）
画像: 最大20枚まで
カラム数: 厳密に72カラム
都道府県コード: jp01-jp47形式（日本語名は不可）

よくあるインポートエラーと対処法

エラーメッセージ	原因	解決方法
フォーマットエラー	カラム数不一致	72カラムを確認
SKU1_在庫数が未入力です	在庫数未設定	カラム23に最低`1`を設定
発送元の地域が不正です	日本語名使用	jp01-jp47コード使用
ブランドIDが存在しません	無効なID	空欄にするか有効ID使用
カテゴリIDが不正です	親カテゴリ使用	リーフカテゴリID使用
商品名が長すぎます	130文字超過	130文字以内に短縮
商品説明が長すぎます	5000文字超過	5000文字以内に短縮

CSV生成実装（draftManager.js）

// CSV生成部分の実装
function generateImportCSV(drafts) {
  const rows = [];

  // ヘッダー行（72カラム）
  const headers = [
    ...Array(20).fill(0).map((_, i) => `商品画像名_${i+1}`),
    '商品名', '商品説明',
    ...Array(10).fill(0).flatMap((_, i) => [
      `SKU${i+1}_種類`,
      `SKU${i+1}_在庫数`,
      `SKU${i+1}_商品管理コード`,
      `SKU${i+1}_JANコード`
    ]),
    'ブランドID', '販売価格', 'カテゴリID',
    '商品の状態', '配送方法', '発送元の地域',
    '発送までの日数', '商品ステータス', '配送料の負担', '送料ID'
  ];

  rows.push(headers);

  // データ行
  drafts.forEach(draft => {
    const row = new Array(72).fill('');

    // 画像（0-19）
    draft.images?.forEach((img, i) => {
      if (i < 20) row[i] = img;
    });

    // 基本情報
    row[20] = draft.name || '';
    row[21] = (draft.description || '').replace(/
/g, '\n');

    // SKU情報
    row[23] = draft.stock || '1'; // 必須！

    // 詳細情報（62-71）
    row[62] = ''; // ブランドID
    row[63] = draft.price || '';
    row[64] = draft.category || draft.categoryId || '';
    row[65] = draft.itemCondition || draft.productCondition || ''; // 数値1-6を直接使用
    row[66] = draft.shippingMethod || ''; // 数値1-6を直接使用（変換不要）
    row[67] = draft.shippingOrigin || ''; // jpコード形式を維持
    row[68] = draft.shippingDuration || ''; // 数値1-5を直接使用（変換不要）
    row[69] = draft.productStatus || ''; // 数値1-2を直接使用
    row[70] = draft.shippingPayer || ''; // 数値1-2を直接使用（変換不要）
    row[71] = ''; // 送料ID

    rows.push(row);
  });

  return Papa.unparse(rows, {
    quotes: false, // 必要な場合のみクォート
    quoteChar: '"',
    delimiter: ','
  });
}

更新履歴

2025-11-20: 重要な変更 - すべてのフィールドでCSV数値形式を直接使用するように変更
- API Enum文字列（METHOD_TYPE_UNDECIDEDなど）の使用を廃止
- shippingMethod, shippingDuration, shippingPayerを数値（'1'-'6'）に統一
- SHIPPING_METHODSなど全ての定数を数値形式に更新
- shippingOptions.jsの全定数を更新
- ドキュメント全体を新仕様に合わせて更新
2025-09-15: 実装に基づく完全な仕様書に更新
2025-09-15: productStatusとitemConditionの実装詳細を追加
2025-09-15: フォームフィールドとCSVカラムのマッピングを追加
2025-09-15: デフォルト値と定数定義を追加
2025-09-14: 72カラム仕様の正確な実装詳細を追加
2025-09-14: 都道府県コード形式の維持を明確化
2025-09-14: SKU1_在庫数の必須要件を追加
2025-09-14: よくあるエラーと対処法を追加