Products — 商品マスター

商品マスターを外部システム（Shopify / Smaregi / Amazon / 手動取込等）から Last Mile に取り込みます。商品は barcode 単位で管理され、同じ barcode を送ると上書き、未登録なら新規作成されます。barcode は受注・在庫との結合キーです。

Base URL https://api.lmile.io · 認証 x-ingest-secret ヘッダー（詳細） · shop はリクエストボディに含めます（省略するとキーのアカウント）

エンドポイント

Method

Path

用途

POST

/api/ingest/products

商品マスターの一括登録・更新（barcode 単位で上書き）

GET

/api/ingest/products

商品マスターを barcode または sku で引く（登録済みかの確認・SKU / barcode の取得）

GET

/api/ingest/accessory-services

付帯サービスにした商品の一覧

`POST` /api/ingest/products

商品の一括登録・更新。同じ barcode は上書き、未登録なら新規作成されます。省略したフィールドは既存値を維持し、新規行のみ currency=JPY / is_active=true / lifecycle_status=active を既定適用します。

リクエスト

POST https://api.lmile.io/api/ingest/products
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json

{
  "shop": "demo-store.myshopify.com",
  "source_system": "shopify",
  "idempotency_key": "import-2026-06-02-001",
  "dry_run": false,
  "products": [
    {
      "barcode": "1234567890123",
      "product_name": "スマートフォンケース ブラック",
      "sku": "DEMO-CASE-BLK-001",
      "variant_name": "iPhone 16",
      "brand": "Demo Brand",
      "category_l1": "ケース",
      "category_l2": "スマホケース",
      "current_price": 9800,
      "current_cost": 3500,
      "currency": "JPY",
      "is_active": true,
      "released_at": "2026-07-15T10:00:00+09:00",
      "preorder_delivery_dates": { "b179515a-6ca9-4ffa-a40b-0664ccc74366": "2026-10-11" },
      "product_type": "Leather Goods",
      "class_metafields": { "variant": { "global.preorder": "10月末お届け予定" } }
    }
  ]
}

ボディパラメータ

パラメータ

型

必須

説明

shop

string

店舗ドメイン（省略するとキーのアカウント）

products

array

✓

商品オブジェクトの配列（最大 10,000 件）

source_system

string

取込元（shopify / smaregi / manual_api 等。default: manual_api）。変更ログの change_source に記録

idempotency_key

string

監査用キー（変更ログに記録）

changed_by_user_id

string (uuid)

変更実行ユーザー

dry_run

boolean

true で検証のみ（書込なし。default: false）

`products[]` オブジェクト

パラメータ

型

必須

説明

barcode

string

✓

商品識別子（JAN/EAN/UPC）。受注・在庫との結合キー

product_name

string

✓

商品名

sku

string

SKU コード

variant_name

string

バリエーション名（サイズ/色等）

brand

string

ブランド名

category_l1 category_l2 category_l3

string

カテゴリ（大/中/小）

current_price

number

現在販売価格

current_compare_at_price

number

参考価格（定価）

current_cost

number

原価

currency

string

通貨コード（新規 default: JPY）

is_active

boolean

有効フラグ（新規 default: true）

lifecycle_status

string

ライフサイクル（新規 default: active）

primary_image_url

string

代表画像 URL

released_at

string

発売日時（ISO 8601）。タイムゾーンオフセット付きを推奨（例 2026-07-15T10:00:00+09:00。オフセット無しは UTC として解釈されます）。省略すると既存値を維持します

preorder_delivery_dates

object

予約納期。出荷元の拠点 ID → その出荷元から出荷できるようになる日（YYYY-MM-DD）の対応表です（例 { "b179515a-…": "2026-10-11" }）。行のある出荷元だけがこの商品を出荷でき、行の無い出荷元は候補から外れます。チェックアウトと購入者ページの到着予定日は、この日から出荷元の作業日数と配送日数を積んで出します。日付が過ぎた行は無視され、通常の在庫の計算に戻ります。省略すると既存値を維持し、{} を送ると予約納期を外します。拠点 ID 以外のキー（"*"・国コード）を送ると 400 invalid_input になります

product_type

string

商品タイプ（Shopify の Product type などの生値）。到着予定日の商品区分の判定に使います。category_l1 とは別の項目です（あちらはカテゴリの体系名が入ります）。省略すると既存値を維持します

class_metafields

object

到着予定日の商品区分が参照するメタフィールドの値。{ "product": { "名前空間.キー": "値" }, "variant": { … } } の形で、商品側とバリエーション側を分けて送ります（区分の判定が「バリエーションの値だけを見る」場合があるためです）。送る対象は区分の設定で参照しているキーだけで構いません。省略すると既存値を維持します

is_accessory_service

boolean

付帯サービス。当日出荷チケットや刻印サービスのように、それだけでは出荷する荷物にならない明細に付けます。true にした商品は在庫の引き当て対象から外れ、出荷指示の serviceLines に入ります。false を送ると付帯サービスを外し、通常の商品に戻ります。省略すると既存値を維持します

inventory_push_disabled_source_ids

string[]

この商品の在庫連携を止める出荷元（拠点 id の配列）。ここに入れた出荷元については、出荷元在庫の通知の availableTotal が実際の合算ではなく 0 になります（販売チャネルでその出荷元から売らないため）。送ると丸ごと置き換えます（[] ですべての出荷元を再開）。変えた出荷元には、在庫の変動を待たずに 1 回通知します（止めた出荷元は 0、再開した出荷元は最新の合算）。省略すると既存値を維持します

レスポンス

{
  "ok": true,
  "shop": "demo-store.myshopify.com",
  "source_system": "shopify",
  "dry_run": false,
  "created": 5,
  "updated": 12,
  "unchanged": 3,
  "errors_count": 1,
  "errors": [
    { "barcode": "INVALID", "error": "barcode and product_name required" }
  ]
}

フィールド

説明

created / updated / unchanged

新規 / 変更あり / 差分なしの件数

errors[]

barcode と error（barcode and product_name required 等）。該当行は skip

挙動・冪等性

商品は店舗 × barcode ごとに 1 行で管理されます。送ると該当商品が更新され、未登録なら新規作成されます。
部分更新: 送信しなかったフィールドは既存値のまま残ります（null で上書きされません）。
変更ログ: 登録（created）と更新（updated）が記録されます。更新時は変更したフィールド名と変更前後の値が残ります。差分が無ければ unchanged（ログは増えません）。
同じ内容の再送は何度でも安全です（冪等）。unchanged として数えられるだけで、何も変わりません。

`GET` /api/ingest/products

商品マスターを barcode または sku で引きます。取込元（EC モール等）から取れた barcode や商品コードが Last Mile に登録されているか、その商品の sku / barcode は何かを、受注を送る前に確かめるときに使います。shop と barcodes / skus はクエリパラメータで指定します。

リクエスト

GET https://api.lmile.io/api/ingest/products?shop=demo-store.myshopify.com&barcodes=1234567890123,1234567890456
x-ingest-secret: {INGEST_SECRET}

クエリパラメータ

パラメータ

型

必須

説明

shop

string

✓

店舗

barcodes

string

引きたい barcode をカンマ区切りで（1 回 200 件まで。前後の空白は無視）

skus

string

引きたい sku をカンマ区切りで（1 回 200 件まで）。barcodes と skus のどちらかは必須。両方送るとどちらかに一致した行を返す

レスポンス

{
  "ok": true,
  "shop": "demo-store.myshopify.com",
  "count": 1,
  "products": [
    { "barcode": "1234567890123", "sku": "BBGT1-ET" }
  ]
}

フィールド

説明

count

見つかった商品の数

products[]

商品マスターにあった行の barcode と sku（SKU が無い商品は null）。barcode 順

挙動・冪等性

商品マスターにある行だけを返します。送った barcode / sku が応答に無ければ、その商品は未登録です。例: 2 件送って count が 1 なら、応答に無い方が未登録です。
sku は商品マスターで一意とは限りません。同じ sku の行が複数あればすべて返すので、「ちょうど 1 件か」は受け取った側で確かめてください（1 件でなければ商品を特定できないものとして止めるのが安全です）。
読み取り専用です。何回呼んでも安全です。
barcodes / skus それぞれ 200 件を超えて送るとエラー（invalid_input）になります。分けて送ってください。

`GET` /api/ingest/accessory-services

付帯サービス（is_accessory_service = true）にした商品の一覧を返します。出荷指示を送る側が「付帯サービスだけの荷物は送らない」を判断するときに使います。shop はクエリパラメータで指定します。

リクエスト

GET https://api.lmile.io/api/ingest/accessory-services?shop=demo-store.myshopify.com
x-ingest-secret: {INGEST_SECRET}

クエリパラメータ

パラメータ

型

必須

説明

shop

string

店舗（省略するとキーのアカウント）

レスポンス

{
  "ok": true,
  "shop": "demo-store.myshopify.com",
  "count": 2,
  "products": [
    { "barcode": "1234567890456", "sku": "SAME-DAY-TICKET" },
    { "barcode": "1234567890789", "sku": null }
  ]
}

フィールド

説明

products[]

付帯サービスにした商品の barcode と sku（SKU が無い商品は null）

挙動・冪等性

付帯サービスにした商品を全件返します（barcode 順）。
読み取り専用です。何回呼んでも安全です。
500 件を超えるときは、一部だけ返さずにエラー（too_many_rows）を返します。一部だけ返すと、付帯サービスの判定が漏れるためです。

エラー

エンドポイント固有:

Status

条件

レスポンス例

422

ok:false（error_kind 付き）

{ "ok": false, "error_kind": "invalid_payload", "error": "products[] required and non-empty" }

400

preorder_delivery_dates のキーが出荷元の拠点 ID でない（"*"・国コードを含む）、または値が実在する YYYY-MM-DD でない

{ "ok": false, "error_kind": "invalid_input", "error": "products[0].preorder_delivery_dates: key must be a fulfillment source location id: *" }

400

barcodes と skus が両方空、またはどちらかが 200 件を超える（GET /api/ingest/products）

{ "ok": false, "error_kind": "invalid_input", "error": "barcodes / skus: at most 200 each" }

500

付帯サービスが 500 件を超える（GET /api/ingest/accessory-services）

{ "ok": false, "error_kind": "too_many_rows", "error": "more than 500 accessory services" }

行単位の不備（barcode / product_name 欠落）はバッチ全体を止めず errors[] に記録して skip します。共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。

データモデル

sot.products — 商品 SoT（shop + barcode で一意）
sot.product_update_logs — 変更監査ログ（created / updated ＋ changed_fields）
read は agent_read.products / agent_read.product_update_logs（safe view）経由

Previousクイックスタート

NextInventory Levels — 在庫

Last updated 2 days ago

Was this helpful?

エンドポイント

POST /api/ingest/products

リクエスト

ボディパラメータ

products[] オブジェクト

レスポンス

挙動・冪等性

GET /api/ingest/products

リクエスト

クエリパラメータ

レスポンス

挙動・冪等性

GET /api/ingest/accessory-services

リクエスト

クエリパラメータ

レスポンス

挙動・冪等性

エラー

データモデル

`POST` /api/ingest/products

`products[]` オブジェクト

`GET` /api/ingest/products

`GET` /api/ingest/accessory-services