GET APIの利用ガイド

CAFE24 APIではデータを取得するためのさまざまな方法を提供しています。このガイドでは、GETリクエストで利用できる7種類のパラメータの使い方を解説します。

1️⃣ 検索条件の追加

エンドポイントにパラメータを付与することで検索条件を追加できます。複数の条件は & で連結します。

使用例

# 特定ブランドかつ価格が1000以上の商品を照会
GET https://yourmall.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

# 日付範囲で照会（YYYY-MM-DD）
GET https://yourmall.cafe24api.com/api/v2/products?created_start_date=2024-01-03&created_end_date=2024-02-03

# 日付＋時刻範囲で照会（ISO 8601）
GET https://yourmall.cafe24api.com/api/v2/products?updated_start_date=2024-01-03T14:01:26+09:00&updated_end_date=2024-02-03T14:01:26+09:00

コード例

// Node.js
const response = await axios.get('/api/v2/admin/products', {
  params: {
    brand_code: 'B000000A',
    price_min: 1000,
    price_max: 50000,
    status: 'active'
  }
});

# Python
params = {
    'brand_code': 'B000000A',
    'price_min': 1000,
    'created_start_date': '2024-01-03'
}
response = requests.get(url, params=params)

2️⃣ カンマによる複数値検索

カンマ（,）を使うと最大100件まで同時に検索できます。カンマ区切りの検索条件は OR条件 として動作します。

使用例

# 指定した商品番号で照会（11 OR 12 OR 13）
GET https://yourmall.cafe24api.com/api/v2/products?product_no=11,12,13

# 複数条件を組み合わせる
GET https://yourmall.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W

コード例

// Node.js
const productNos = [11, 12, 13];
const response = await axios.get('/api/v2/admin/products', {
  params: {
    product_no: productNos.join(',')
  }
});

# Python
product_nos = [11, 12, 13]
params = {'product_no': ','.join(map(str, product_nos))}
response = requests.get(url, params=params)

⚠️ 注意: 最大100件、OR条件、空白を含めない

3️⃣ マルチショップ情報の取得

shop_no パラメータで特定のマルチショップの情報を取得できます。省略した場合はデフォルト（1番目）のショッピングモール情報が返されます。

使用例

# 2番ショップの商品を照会
GET https://yourmall.cafe24api.com/api/v2/products?shop_no=2

# デフォルトショッピングモール（shop_no省略）
GET https://yourmall.cafe24api.com/api/v2/products

コード例

// Node.js - すべてのショップを巡回
async function getAllShopsProducts() {
  const allProducts = [];
  for (let shopNo = 1; shopNo <= 5; shopNo++) {
    try {
      const response = await axios.get('/api/v2/admin/products', {
        params: { shop_no: shopNo }
      });
      allProducts.push({ shop_no: shopNo, products: response.data });
    } catch (error) {
      break; // ショップが存在しない
    }
  }
  return allProducts;
}

4️⃣ 詳細照会 vs 単件照会

リソースIDを指定することで詳細情報を取得できます。

方式	URL	取得データ
詳細照会	`GET /products/128`	より多くの情報
単件照会	`GET /products?product_no=128`	基本情報

使用例

# 詳細照会 - より多くの情報を含む
GET https://yourmall.cafe24api.com/api/v2/admin/products/128

# 単件照会 - 基本情報のみ
GET https://yourmall.cafe24api.com/api/v2/admin/products?product_no=128

コード例

// Node.js
// 詳細照会
const detail = await axios.get(`/api/v2/admin/products/${productNo}`);

// 単件照会
const info = await axios.get('/api/v2/admin/products', {
  params: { product_no: productNo }
});

5️⃣ ページネーション

limit と offset パラメータを使ってページ単位でデータを取得できます。

パラメータ	説明	例
`limit`	一度に取得する件数	`100`
`offset`	スキップする件数（0始まり）	`200`

計算式

ページ番号 = P（1始まり）
limit = L
offset = (P - 1) * L

例）3ページ目を取得（limit=100）
offset = (3 - 1) * 100 = 200

使用例

# 最初の100件
GET https://yourmall.cafe24api.com/api/v2/admin/products?limit=100

# 201〜300件目（3ページ目）
GET https://yourmall.cafe24api.com/api/v2/admin/products?limit=100&offset=200

コード例

// Node.js - 全データ取得
async function getAllProducts() {
  const allProducts = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await axios.get('/api/v2/admin/products', {
      params: { limit, offset }
    });

    const products = response.data.resource;
    if (products.length === 0) break;

    allProducts.push(...products);
    offset += limit;
  }

  return allProducts;
}

# Python - ページ単位での取得
def get_products_page(page, limit=100):
    offset = (page - 1) * limit
    response = requests.get(url, params={'limit': limit, 'offset': offset})
    return response.json()['resource']

6️⃣ 特定フィールドの取得

fields パラメータで必要なフィールドだけを選択的に取得できます。

使用例

# 商品名と商品番号のみ取得
GET https://yourmall.cafe24api.com/api/v2/admin/products?fields=product_name,product_no

# 複数フィールドを取得
GET https://yourmall.cafe24api.com/api/v2/admin/products?fields=product_no,product_name,price,inventory_qty

レスポンス例

{
  "resource": [
    {
      "product_no": 128,
      "product_name": "サンプル商品"
    }
  ]
}

コード例

// Node.js
const fields = ['product_no', 'product_name', 'price'];
const response = await axios.get('/api/v2/admin/products', {
  params: { fields: fields.join(',') }
});

メリット

ネットワーク帯域の節約
処理速度の向上
メモリ効率の改善
センシティブデータのフィルタリング

7️⃣ サブリソースの取得

embed パラメータで関連するサブリソースを一緒に取得できます。

使用例

# 商品照会時にバリアントと在庫を含める
GET https://yourmall.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories

# 注文照会時に商品情報を含める
GET https://yourmall.cafe24api.com/api/v2/admin/orders/123?embed=products,shipping

レスポンス例

{
  "resource": {
    "product_no": 570,
    "product_name": "サンプル商品",
    "variants": [
      {"variant_no": 1, "option_name": "カラー", "option_value": "レッド"}
    ],
    "inventories": [
      {"warehouse_name": "本倉庫", "quantity": 100}
    ]
  }
}

コード例

// Node.js
const response = await axios.get(`/api/v2/admin/products/${productNo}`, {
  params: { embed: 'variants,inventories,categories' }
});

const product = response.data.resource;
console.log('Variants:', product.variants);
console.log('Inventories:', product.inventories);

embed vs 個別照会の比較

項目	embedを使う	個別照会
API呼び出し回数	1回	N+1回
パフォーマンス	高速	低速
レスポンスサイズ	大きい	小さい

🎯 ベストプラクティス

1. 条件の組み合わせを最適化する

# ✅ 良い例 - 1回のリクエストで必要なデータのみ取得
GET /products?status=active&fields=product_no,product_name,price&limit=100

# ❌ 悪い例 - 全件取得してからフィルタリング
GET /products

2. エラーハンドリング

async function safeGetData(endpoint, params) {
  try {
    const response = await axios.get(endpoint, { params });
    return response.data.resource;
  } catch (error) {
    if (error.response?.status === 404) {
      return null; // リソースが見つからない
    } else if (error.response?.status === 422) {
      console.error('不正なパラメータ:', error.response.data);
    }
    throw error;
  }
}

3. URLエンコーディング

// ✅ 自動エンコーディング（推奨）
const params = {
  product_name: '商品名',
  category: 'カテゴリ'
};
axios.get(url, { params }); // axiosが自動でエンコードする

// ❌ 手動エンコーディング（非推奨）
const url = `/products?name=${encodeURIComponent('商品名')}`;

4. パフォーマンス最適化

// ✅ 必要なフィールドのみ取得
const params = {
  fields: 'product_no,product_name,price',
  limit: 100
};

// ✅ embedでN+1問題を解消
const params = {
  embed: 'variants,inventories',
  fields: 'product_no,product_name,variants,inventories'
};

// ✅ 条件を可能な限り活用
const params = {
  status: 'active',
  price_min: 10000,
  created_start_date: '2024-01-01',
  limit: 50
};

📊 パラメータ組み合わせ例

複合検索の例

# 価格帯内のactive商品から特定フィールドだけページ取得
GET /api/v2/admin/products?status=active&price_min=10000&price_max=50000&fields=product_no,product_name,price&limit=100&offset=0

// Node.jsでの複合検索
const response = await axios.get('/api/v2/admin/products', {
  params: {
    status: 'active',
    price_min: 10000,
    price_max: 50000,
    created_start_date: '2024-01-01',
    fields: 'product_no,product_name,price,created_date',
    limit: 100,
    offset: 0,
    shop_no: 1
  },
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

⚠️ 注意事項

URLエンコーディング: 日本語や特殊文字は必ずエンコードしてください
日付フォーマット: ISO 8601形式を推奨（YYYY-MM-DDTHH:MM:SS+09:00）
カンマ件数制限: 最大100件
オフセットのパフォーマンス: offset値が大きいとパフォーマンス低下を招くことがあります
APIドキュメントの確認: APIごとに利用できるパラメータが異なります

📚 関連ドキュメント

💡 まとめ

機能	パラメータ	例
検索条件	`param=value`	`status=active`
複数値	`param=v1,v2,v3`	`product_no=11,12,13`
マルチショップ	`shop_no=N`	`shop_no=2`
詳細照会	`/resource/{id}`	`/products/128`
ページネーション	`limit=N&offset=M`	`limit=100&offset=200`
特定フィールド	`fields=f1,f2`	`fields=product_no,name`
サブリソース	`embed=r1,r2`	`embed=variants,inventories`

1️⃣ 検索条件の追加​

使用例​

コード例​

2️⃣ カンマによる複数値検索​

使用例​

コード例​

3️⃣ マルチショップ情報の取得​

使用例​

コード例​

4️⃣ 詳細照会 vs 単件照会​

使用例​

コード例​

5️⃣ ページネーション​

計算式​

使用例​

コード例​

6️⃣ 特定フィールドの取得​

使用例​

レスポンス例​

コード例​

メリット​

7️⃣ サブリソースの取得​

使用例​

レスポンス例​

コード例​

embed vs 個別照会の比較​

🎯 ベストプラクティス​

1. 条件の組み合わせを最適化する​

2. エラーハンドリング​

3. URLエンコーディング​

4. パフォーマンス最適化​

📊 パラメータ組み合わせ例​

複合検索の例​

⚠️ 注意事項​

📚 関連ドキュメント​

💡 まとめ​

1️⃣ 検索条件の追加

使用例

コード例

2️⃣ カンマによる複数値検索

使用例

コード例

3️⃣ マルチショップ情報の取得

使用例

コード例

4️⃣ 詳細照会 vs 単件照会

使用例

コード例

5️⃣ ページネーション

計算式

使用例

コード例

6️⃣ 特定フィールドの取得

使用例

レスポンス例

コード例

メリット

7️⃣ サブリソースの取得

使用例

レスポンス例

コード例

embed vs 個別照会の比較

🎯 ベストプラクティス

1. 条件の組み合わせを最適化する

2. エラーハンドリング

3. URLエンコーディング

4. パフォーマンス最適化

📊 パラメータ組み合わせ例

複合検索の例

⚠️ 注意事項

📚 関連ドキュメント

💡 まとめ