コンテンツにスキップ
スマレジ・プラットフォームAPI 仕様書

商品一括更新

PATCH
/products/bulk

商品情報を一括更新します。

※ 商品の更新処理は非同期で実行されます。処理完了後、指定されたコールバックURLにWebhook通知されます。

※ 商品は1リクエストにつき100件まで更新できます。

対象プラン

  • スタンダード
  • プレミアム
  • プレミアムプラス
  • フードビジネス
  • リテールビジネス

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”
object
products
required
商品情報
Array<object>
object
productId
required
商品ID

商品ID
※ ユーザーアクセストークンを利用する場合、ユーザーの所属する店舗で販売している商品IDを指定してください。

string format: int
categoryId
部門ID

部門毎に付与するID

string format: int
productCode
商品コード

ユニーク値

string
<= 20 characters /^[ -~]+$/
productName
商品名
string
<= 85 characters
productKana
商品カナ
string
<= 85 characters
taxDivision
税区分

商品単価の税区分 (0：税込、1：税抜、2：非課税)

string
default: 1
Allowed values: 0 1 2
productPriceDivision
商品価格区分

商品をオープン価格販売するかどうかの設定
(1：通常価格、2：オープン価格)

string
default: 1
Allowed values: 1 2
price
商品単価

商品単価

string format: int
>= -99999999 <= 99999999
customerPrice
会員価格
string format: int
>= -99999999 <= 99999999
cost
原価
string format: decimal
>= -99999999.99999 <= 99999999.99999
attribute
規格

商品属性

string
<= 1000 characters
description
説明

商品の説明

string
<= 1000 characters
catchCopy
キャッチコピー

商品のキャッチコピー

string
<= 1000 characters
size
サイズ

サイズの和名を設定

string
<= 85 characters
color
カラー

色の和名を設定

string
<= 85 characters
tag
タグ

タグの和名を設定

string
<= 85 characters
groupCode
グループコード

グルーピングする為の一意のキー (親の商品IDになる)

string
<= 85 characters
url
URL

スマレジ端末でWEBページを表示する場合設定

string
<= 255 characters
printReceiptProductName
レシート印字商品名

レシートに印字する商品名 （64文字以内）

string
<= 64 characters
displaySequence
表示順

表示順序

string format: int
<= 999999999
displayFlag
端末表示

端末で表示するか判定
(0：表示しない、1：表示する)

string
default: 1
Allowed values: 0 1
division
商品区分

商品区分（0:通常、1:回数券、2:オプション)
※回数券 は回数券機能が利用可能な契約のみ指定可能。ご利用できない契約で指定された場合エラー。

string
0
Allowed values: 0 1 2
productOptionGroupId
オプショングループID

商品オプショングループのID（商品区分が0:通常の場合のみ設定可能）。オプショングループの設定方法が「全店舗共通」の場合、適用可能なオプショングループのIDをこちらに設定します。
nullの場合は未設定として更新します。
※（注）既にオプショングループ設定方法が「店舗ごと」のオプショングループが設定されている商品に対して、このフィールドをnull以外で指定することは非推奨です。将来的にそのようなケースは入力チェックでエラーとなる予定です。（同じリクエストにおいてすべての商品取扱店舗に対してオプショングループIDをnullに指定される場合は問題ございません。） なお、「店舗ごと」のオプショングループが設定されている商品に対して「全店舗共通」のオプショングループを設定してしまった場合、更新前と変わらず店舗ごと設定のオプショングループ設定がそのまま適用されますが、プラットフォームAPIにおけるレスポンスデータの本フィールドにおいては、更新時に指定された全店舗共通のproductOptionGroupIdが取得されるようになりますのでご注意下さい。

string format: int
>= 1 <= 999999999
salesDivision
売上区分

（0:売上対象、1:売上対象外）

string
0
Allowed values: 0 1
stockControlDivision
在庫管理区分

（0:在庫管理対象、1:在庫管理対象外）

string
0
Allowed values: 0 1
pointNotApplicable
ポイント対象区分

（0:ポイント対象、1:ポイント対象外）

string
0
Allowed values: 0 1
taxFreeDivision
免税区分

(0：対象外、1：一般品、2：消耗品)

string
0
Allowed values: 0 1 2
calcDiscount
値引割引計算対象

小計値引／割引(クーポン値引、ポイント値引き含む)の対象かどうかを識別する。
（0:対象外、1:対象）

string
default: 1
Allowed values: 0 1
staffDiscountRate
社員販売割引率

社員販売時の割引率

string format: int
<= 100
useCategoryReduceTax
部門税設定参照フラグ

軽減税率個別設定フラグ(0:reduceTaxIdを使用、1:部門の税設定を使用)
画面項目「部門の税設定を使用」

string
default: 1
Allowed values: 0 1
reduceTaxId
軽減税率ID

軽減税率ID
標準:null
軽減:10000001 (特定商品の軽減税率適用）
選択[標準]:10000002（状態による適用[適用しない]）
選択[軽減]:10000003（状態による適用[適用する]）
選択[選択]:10000004（状態による適用[都度選択する]）
上記以外の場合、カスタム軽減税率で登録されている軽減税率ID

※10000001〜10000004における軽減税率は日本国における軽減税率(8%)です
※存在しない軽減税率IDを指定した場合エラー

string format: int
<= 999999999
reduceTaxPrice
軽減税率用商品単価
string format: int
>= -99999999 <= 99999999
reduceTaxCustomerPrice
軽減税率用商品会員単価
string format: int
>= -99999999 <= 99999999
orderPoint
発注点

発注をかけるべき在庫数

string format: int
<= 999999999
purchaseCost
仕入原価

商品の仕入原価

string format: decimal
>= -99999999.99999 <= 99999999.99999
supplierProductNo
品番

メーカー品番　 【在庫PKG用】

string
<= 85 characters
appStartDateTime
適用開始日時

端末に適用を開始する日時[YYYY-MM-DDThh:mm:ssTZD]

string format: date-time
prices
商品価格

商品価格
※（注）このフィールドに100件以上指定することは非推奨です。将来的にそのようなケースは入力チェックでエラーとなる可能性がございます。

Array<object>
object
storeId
required
店舗ID

店舗ID：(全店の場合、-1を設定)

string format: int
>= -1 <= 99999999
priceDivision
required
価格区分

(1：商品単価、2：会員価格)

string
Allowed values: 1 2
startDate
required
適用開始日

[YYYY-MM-DD]

string format: date
endDate
適用終了日

[YYYY-MM-DD]
※未設定の場合、有効期限なしとして適用されます
※適用開始日>適用終了日の場合エラー
※適用終了日と商品単価のいずれか必須

string format: date
price
商品単価

※適用終了日と商品単価のいずれか必須

string format: int
>= -99999999 <= 99999999
reserveItems
商品自由項目

商品自由項目

Array<object>
object
no
required
商品自由項目番号

商品自由項目に付与されている連番

string format: int
>= 1 <= 99
value
required
値

商品自由項目を指定する場合必須

string
<= 85 characters
stores
商品取扱店舗

商品取扱店舗

Array<object>
object
storeId
required
店舗ID
string format: int
>= 1 <= 99999999
productOptionGroupId
オプショングループID

オプショングループID：商品オプショングループのID（商品区分が0:通常の場合のみ設定可能）。オプショングループの設定方法が「店舗ごと」の場合、適用可能なオプショングループのIDをこちらに設定します。
nullの場合は未設定として更新します。

string format: int
>= 1 <= 999999999
assignDivision
required
取扱区分

(0:販売する／1:販売しない)
商品取扱店舗を指定する場合必須

string
0
Allowed values: 0 1
inventoryReservations
在庫引当商品

在庫引当商品

Array<object>
object
reservationProductId
required
在庫引当商品ID
string format: int
>= 1 <= 99999999
reservationAmount
required
引当数
string format: int
>= 1 <= 999
attributeItems
商品属性項目

商品属性項目

Array<object>
object
code
コード

商品属性項目を一意にする項目
nullの場合は未設定として更新します

string format: string
<= 9 characters
no
required
項目番号

商品属性に付与されている連番

string format: int
>= 1 <= 3
orderSetting
発注設定

発注設定が存在しない場合default値で登録されます。

object
continuationDivision
継続区分

[管理画面->設定->在庫設定->発注設定->継続区分]から確認できる継続区分のコードを指定。

string format: int
nullable
orderStatusDivision
発注状態

発注不可理由を設定している場合は必須です。(0:発注不可、1:発注可)

string
default: 1
Allowed values: 0 1
orderNoReasonDivision
発注不可理由

発注状態を設定している場合は必須。発注可の場合はnullを設定、発注不可の場合は発注不可理由のコードを設定してください。
発注不可理由のコードは、 [管理画面->設定->在庫設定->発注設定->発注不可理由]から確認できます。

string format: int
nullable
orderUnit
発注単位

発注単位

object
division
required
発注単位区分

(0:単位なし、1:単位あり)
(0:単位なし)の場合、「発注単位数」「「発注単位名」にnullを設定してください。
(1:単位あり)の場合、「発注単位数」「発注単位名」に値が必要です。

string
0
Allowed values: 0 1
num
required
発注単位数
string format: int
nullable >= 1 <= 99999999
name
required
発注単位名
string format: string
nullable <= 32 characters
orderLimitAmount
発注制限数

(null:発注制限なし、0~99999999:発注制限)
発注時の制限数の設定。発注単位数を設定している場合発注単位数＊発注制限数が発注時に設定できる最大数になります。

string format: int
nullable <= 99999999
orderSupplierEditable
発注時仕入先編集状態

編集可能に設定すると、仕入先分割設定時の補充発注仮発注画面にて仕入先を選択できるようになります。(0:編集不可、1:編集可能)

string
0
Allowed values: 0 1
pbDivision
PB区分

PB区分(1:プロパー、2:バーゲン)

string
default: 1
Allowed values: 1 2
displayFlag
発注表示

(0:表示しない、1:表示する)

string
default: 1
Allowed values: 0 1
stores
店舗別発注設定

店舗別発注設定

Array<object>
object
storeId
店舗ID
string format: int
>= 1 <= 999999999
orderLimitAmount
発注制限数

(null:発注制限なし、-1:全店舗設定、0~99999999:発注制限)
発注時の制限数の設定。発注単位数を設定している場合発注単位数＊発注制限数が発注時に設定できる最大数になります。

string format: int
default: -1 nullable >= -1 <= 99999999
displayFlag
発注表示

(-1:全店舗設定、0:表示しない、1:表示する)

string
default: -1
Allowed values: -1 0 1
callbackUrl
required
商品更新完了通知URL

商品の更新が完了した際に、更新結果をWebhook通知するURL

string
<= 511 characters
Example
{
  "products": [
    {
      "productId": "1",
      "categoryId": "1",
      "productCode": "string",
      "productName": "string",
      "productKana": "string",
      "taxDivision": "0",
      "productPriceDivision": "1",
      "price": "12345678",
      "customerPrice": "12345678",
      "cost": "99999999.99999",
      "attribute": "string",
      "description": "string",
      "catchCopy": "string",
      "size": "string",
      "color": "string",
      "tag": "string",
      "groupCode": "string",
      "url": "string",
      "printReceiptProductName": "string",
      "displaySequence": "123456789",
      "displayFlag": "0",
      "division": "0",
      "productOptionGroupId": "123456789",
      "salesDivision": "0",
      "stockControlDivision": "0",
      "pointNotApplicable": "0",
      "taxFreeDivision": "0",
      "calcDiscount": "0",
      "staffDiscountRate": "100",
      "useCategoryReduceTax": "0",
      "reduceTaxId": "10000001",
      "reduceTaxPrice": "12345678",
      "reduceTaxCustomerPrice": "12345678",
      "orderPoint": "123456789",
      "purchaseCost": "99999999.99999",
      "supplierProductNo": "string",
      "appStartDateTime": "2000-01-23T01:23:45+09:00",
      "prices": [
        {
          "storeId": "12345678",
          "priceDivision": "1",
          "startDate": "2000-01-23",
          "endDate": "2000-01-23",
          "price": "12345678"
        }
      ],
      "reserveItems": [
        {
          "no": "12",
          "value": "string"
        }
      ],
      "stores": [
        {
          "storeId": "12345678",
          "productOptionGroupId": "123456789",
          "assignDivision": "0"
        }
      ],
      "inventoryReservations": [
        {
          "reservationProductId": "12345678",
          "reservationAmount": "123"
        }
      ],
      "attributeItems": [
        {
          "code": "string",
          "no": "1"
        }
      ],
      "orderSetting": {
        "continuationDivision": "1",
        "orderStatusDivision": "0",
        "orderNoReasonDivision": "1",
        "orderUnit": {
          "division": "0",
          "num": "12345678",
          "name": "string"
        },
        "orderLimitAmount": "12345678",
        "orderSupplierEditable": "0",
        "pbDivision": "1",
        "displayFlag": "0",
        "stores": [
          {
            "storeId": "123456789",
            "orderLimitAmount": "12345678",
            "displayFlag": "-1"
          }
        ]
      }
    }
  ],
  "callbackUrl": "string"
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

処理受付完了

object
requestId

問い合わせ用ID：弊社への問い合わせの際にご利用ください

integer
callbackUrl

商品更新完了通知URL：商品の更新が完了した際に、更新結果をWebhook通知するURL

Webhook通知について ■ Request Header:
key value
Content-Type application/json;charset=UTF-8
■ Request Body (更新成功): Array of Objects
key value
requestId レスポンス時に返却したリクエストID (Integer)
result 処理結果（Array)
productId 商品ID：数字15桁以内 (String)
リクエスト例
  
  Content-Type: application/json;charset=UTF-8

  {

   "requestId":700,

   "result":[

    {

     "productId":"123"

    },

    {

     "productId":"456"

    }

   ]

  }

■ Request Body (更新失敗):
key value
requestId レスポンス時に返却したリクエストID (Integer)
message エラーメッセージ (String)
リクエスト例
    
    Content-Type: application/json;charset=UTF-8

    {

     "requestId":700,

     "message":"[stores][2行目]商品コードが重複しています。"

    }

■ 更新失敗時のエラーメッセージの詳細:
※ Webhook通知では、既存データを参照した上での結果を返します
※「 [ 大項目 ] [ 何番目のオブジェクトで発生したか ] エラーメッセージ 」の形式で返されます
※「大項目」は下記のリクエストボディの項目と対応します
「大項目」 対応する項目
reserveItems 商品自由項目の各項目
prices 商品価格の各項目
stores 商品取扱店舗の各項目
inventoryReservations 在庫引当商品の各項目
attributeItems 商品属性項目の各項目
orderSetting 発注設定の各項目
orderStoreSettings 店舗別発注設定の各項目
products 上記以外の商品項目
※「何番目のオブジェクトで発生したか」は「〇〇行目」と表現されます
※「エラーメッセージ」の一覧は下記です
ケースエラーメッセージ
存在しない商品IDを指定した場合商品IDが存在しません
商品コードが重複している場合商品コードが重複しています
存在しない部門IDを指定した場合部門IDが存在しません
存在しない軽減税率IDを指定した場合軽減税率IDが存在しません
存在しないオプショングループIDを指定した場合商品オプショングループIDが存在しません
存在しない店舗IDを指定した場合店舗IDが存在しません
存在しない商品IDを在庫引当商品IDとして指定した場合在庫引当商品IDが存在しません
存在しない商品属性項目が指定された場合商品属性項目が存在しません。
商品の登録上限数を超えてしまう場合登録件数の上限をオーバーしたため、登録できません
商品区分が「0:通常」以外の商品に対してオプショングループIDを指定した場合商品区分が「通常」でない商品に対してオプショグループIDは指定できません。
オプショングループの設定方法が「全店舗共通」の商品に対して設定方法が「店舗ごと」のオプショングループIDを指定した場合設定方法が「全店舗共通」のオプショングループが設定された商品に対して設定方法が「店舗ごと」のオプショングループIDは指定できません。
オプショングループの設定方法が「店舗ごと」の商品に対して設定方法が「全店舗共通」のオプショングループIDを指定した場合（現状はエラーではありませんが、将来的にエラーとする予定です）設定方法が「店舗ごと」のオプショングループが設定された商品に対して設定方法が「全店舗共通」のオプショングループIDは指定できません。
店舗区分が「倉庫」の店舗に対して設定方法が「店舗ごと」のオプショングループIDが設定された場合倉庫に対してオプショングループは設定できません。
回数券の内容になっている商品の区分を回数券に設定する場合本商品は別の回数券の内容になっています。回数券の内容になっている商品の区分は「回数券」には設定できません。
標準時の会員単価が指定されていない商品に、軽減税率時の会員単価を指定した場合軽減税率時の会員単価を設定する場合は、会員単価を設定してください。
オプション商品として使用中の商品の商品区分を変更しようとした場合オプション商品として使用中のため、商品区分を変更できません。
バンドル商品として使用中の商品の商品区分を変更しようとした場合バンドル商品として使用中のため、商品区分を変更できません。
商品価格のうち、スマレジにもリクエストにも商品単価が存在しない場合価格情報がない商品価格レコードは登録できません。
存在しない継続区分を発注設定に指定した場合継続区分が存在しません。
存在しない発注不可理由を発注設定に指定した場合発注不可理由が存在しません。
string
Example
{
  "requestId": 700,
  "callbackUrl": "string"
}

400

Section titled “400 ”
  • 商品IDがリクエスト内で重複している場合
  • 商品コードがリクエスト内で重複している場合
  • 商品価格の店舗IDと価格区分と適応開始日の組み合わせが重複している場合
  • 商品自由項目の商品自由項目番号がリクエスト内で重複している場合
  • 商品取扱店舗の店舗IDがリクエスト内で重複している場合
  • 在庫引当商品の在庫引当商品IDがリクエスト内で重複している場合
  • 商品属性項目の項目番号が重複している場合
  • リクエスト上限数が超えている場合
  • 商品情報が1件も送られてこなかった場合
  • 回数券を利用できない契約で、商品区分に回数券を指定した場合
  • 商品区分が「0:通常」以外を指定して、設定方法が「全店舗共通」の商品オプショングループIDを指定した場合（将来的に「店舗ごと」の商品オプショングループIDを指定した場合と同じメッセージ内容で統合となる予定です）
  • 商品区分が「0:通常」以外を指定して、設定方法が「店舗ごと」の商品オプショングループIDを指定した場合
  • 設定方法が「全店舗共通」のオプショングループIDと「店舗ごと」のオプショングループIDがともに指定された場合
  • 軽減税率時の会員単価が指定されているが、標準時の会員単価が指定されていない場合
  • 商品価格の商品単価か適用終了日のいずれも指定していない場合
  • 商品価格の適用開始日を適用終了日よりも未来を指定した場合
  • 発注設定の店舗別発注設定の店舗IDが重複している場合
  • 発注状態または発注不可理由を設定していて、どちらかが未設定の場合
  • 発注設定の発注状態に「1:発注可」を設定していて、発注不可理由にnull以外を設定している場合
  • 発注設定の発注単位区分に「1:単位あり」を設定していて、発注単位名または発注数を設定していない場合
  • 発注設定の発注単位区分に「0:単位なし」を設定していて、発注単位名または発注数にnullを設定していない場合
  • リクエスト内の全ての商品情報で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての商品価格で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての商品取扱店舗で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての商品自由項目で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての在庫引当商品で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての商品属性項目で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての発注設定で指定しているフィールドが揃っていない場合
  • リクエスト内の全ての店舗別発注設定で指定しているフィールドが揃っていない場合
object
type
required
string
title
required
string
detail
string
status
integer
Examples
{
  "type": "about:blank",
  "title": "Bad Request",
  "detail": "指定された商品IDが重複しています。(商品ID-{商品ID})",
  "status": 400
}