# Products — 商品マスター

## POST /api/products/bulk-upsert

商品マスターの一括登録・更新。`shop + barcode` で UPSERT。価格や名前の変更は自動でログに記録。

## Request

```http
POST https://ai.lmile.io/api/products/bulk-upsert
x-cron-secret: {SECRET}
x-shop: demo-store.myshopify.com
Content-Type: application/json
```

```json
{
  "products": [
    {
      "barcode": "1234567890123",
      "sku": "DEMO-CASE-BLK-001",
      "product_name": "スマートフォンケース ブラック",
      "variant_name": "iPhone 16",
      "brand": "Demo Brand",
      "category_l1": "ケース",
      "category_l2": "ケース",
      "current_price": 9800,
      "current_cost": 3500,
      "currency": "JPY",
      "is_active": true
    }
  ]
}
```

## Fields

| Field           | Type    | Required | Description                          |
| --------------- | ------- | -------- | ------------------------------------ |
| `barcode`       | string  | ✅        | 商品識別子 (JAN/EAN/UPC)。受注・在庫との JOIN key |
| `product_name`  | string  | ✅        | 商品名                                  |
| `sku`           | string  |          | SKU コード                              |
| `variant_name`  | string  |          | バリエーション名 (サイズ/色等)                    |
| `brand`         | string  |          | ブランド名                                |
| `category_l1`   | string  |          | カテゴリ大分類                              |
| `category_l2`   | string  |          | カテゴリ中分類                              |
| `category_l3`   | string  |          | カテゴリ小分類                              |
| `current_price` | number  |          | 現在販売価格                               |
| `current_cost`  | number  |          | 原価                                   |
| `currency`      | string  |          | 通貨コード (default: `JPY`)               |
| `is_active`     | boolean |          | 有効フラグ (default: `true`)              |

## Response

```json
{
  "created": 5,
  "updated": 12,
  "unchanged": 3,
  "errors": [
    { "barcode": "INVALID", "error": "barcode and product_name required" }
  ]
}
```

## 変更ログ

価格変更・名前変更時は `product_update_logs` に自動記録されます。

| change\_type   | トリガー                                   |
| -------------- | -------------------------------------- |
| `created`      | 新規登録                                   |
| `price_change` | `current_price` または `current_cost` の変更 |
| `name_change`  | `product_name` の変更                     |

## Idempotency

`shop + barcode` で UPSERT。同じ barcode を再送しても安全 (変更があればログ記録、なければ `unchanged`)。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lmile.gitbook.io/lmile-docs/ingestion-apis/products.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.