SC-APIの販売在庫・バッファ数と検証環境（新システム）

SC-APIで商品ごとの販売在庫バッファ数を設定し、バッファ控除後の販売在庫を取得するための仕様と、検証環境での確認方法を説明します。

検証期間

［2026/10/30］～［2026/11/30］

通常のテスト環境には、販売在庫機能を反映済みです。
本番環境では機能をOFFにしており、本番提供の開始は12/1を予定しております。

検証環境

通常のテスト環境

画面・CSV・SC-APIの確認には、テスト環境用の会社アカウントとAPIキーを使用してください。

stg：商品一覧・バッファ数の設定
stg：在庫一覧・販売在庫の確認
APIベースURL：https://test.api.stockcrew.co.jp/api
stg：API仕様書（ReDoc）
stg：OpenAPI定義

対象エンドポイント

以下のパスをAPIベースURLにつなげて使用します。

処理	メソッド	パス
商品登録	POST	`/external/items`
商品更新	PUT	`/external/items/{itemNo}`
商品取得	GET	`/external/items`
在庫取得	GET	`/external/inventories`

認証方法

APIの実行には、テスト環境用の会社コードとAPIキーが必要です。画面のサインイン情報とは別です。

X-STOCKCREW-Key: {検証環境用APIキー} CompanyCode: {検証環境用会社コード} Content-Type: application/json

追加項目と数量の取り扱い

在庫取得：販売に使う数量は qtySalesStock を参照します

在庫取得API GET /external/inventories の主な数量項目は次のとおりです。パスはAPIのベースURLより後の部分です。

項目名	意味・使い方
`qtyStock`	倉庫の在庫数量です。バッファの設定だけでは減りません。
`qtyStockFree`	従来どおりの、引き当てられていない在庫数です。バッファは控除しません。
`qtySalesStock`	バッファ控除後の販売在庫数です。モール等への販売数量にバッファを反映する連携では、この項目を使用します。

たとえば、対象のA品倉庫に在庫が10点あり、引当済みが0点・バッファ数が2点の場合、数量項目は次のようになります（説明用の抜粋）。

{  "itemNo": "SAMPLE-001",  "qtyStock": 10,  "qtyStockFree": 10,  "qtySalesStock": 8}

qtyStockFree を採用する連携は10点、qtySalesStock を採用する連携は8点を販売数量の基準にします。
qtySalesStock からバッファをもう一度差し引かないでください。すでに控除済みです。

倉庫・期限別の行と、引当・出荷の扱い

販売在庫の対象は、通常出荷に使用するA品倉庫の出荷期限内の在庫です。対象外の倉庫や出荷期限切れの行は、qtySalesStock が0になります。
同じ商品が倉庫・期限別に複数行ある場合も、バッファは商品全体で1回だけ控除します。
出荷期限が遅い行からバッファを差し引きます。
遅い行だけでは足りない場合は、次に期限が遅い行から残りを差し引き、控除後の数量を各行のqtySalesStockとして返します。
商品全体の販売数量が必要な連携は、必要な行の qtySalesStock を合算してください。取得条件で一部の行だけを取得している場合は、その行の分だけの合計になります。

出荷期限別の具体例

同じ商品の対象となるA品倉庫で、すべて出荷期限内、各行のフリー在庫が5点ずつある例です。
表は出荷期限が早い順に並べています。

出荷期限	フリー在庫	バッファ4点の場合の販売在庫	バッファ7点の場合の販売在庫
早い行	5	5	5
中間の行	5	5	3
遅い行	5	1	0
合計	15	11	8

バッファ4点は遅い行の5点から差し引くため、販売在庫は早い順に5・5・1点です。
バッファ7点は遅い行から5点、次に中間の行から2点を差し引くため、5・3・0点です。
バッファは倉庫内の在庫を取り置く設定ではなく、実在庫・フリー在庫・引当可能数そのものは変わりません。

SC-APIで登録した受注も、引当・出荷にはバッファ控除前の実在庫を使います。
販売在庫が0でも、引当可能な実在庫があれば出荷できます。バッファは販売数量の調整です。

商品登録・更新：qtySalesBuffer で設定します

商品登録 POST /external/items、商品更新 PUT /external/items/{itemNo} では、qtySalesBuffer に0以上の整数を指定します。上限は2147483647です。
商品取得 GET /external/items の qtySalesBuffer で設定値を確認できます。販売在庫の取得項目 qtySalesStock とは別の項目です。

指定内容	新規登録	更新
`"qtySalesBuffer": 2`	2点に設定	2点に変更
`"qtySalesBuffer": 0`	控除なし	控除を解除
項目を省略	0として登録	現在の値を維持

数値の 0 と項目の省略は異なります。null、文字列、負数、小数は指定できません。
連携プログラム側では、数量項目の切替・控除の二重適用がないこと・複数行の集計・実際のモール反映結果を確認してください。

リクエスト指定例

商品更新でバッファ数を2にする場合の本文です。商品コードは更新対象に置き換えてください。

PUT /external/items/SAMPLE-001 {   "qtySalesBuffer": 2 }

解除するときは数値の0を指定します。商品新規登録では、商品名・商品区分など、エンドポイントで必須となる他の項目も指定してください。

{   "qtySalesBuffer": 0 }

ご確認いただきたい内容

テスト商品のバッファ数を2へ変更し、商品取得APIと商品画面で同じ設定値を確認する。
A品倉庫の出荷期限内フリー在庫が10点の場合、在庫取得APIでqtyStockFree: 10とqtySalesStock: 8を確認する。
バッファ数を0へ変更すると控除が解除され、更新時に項目を省略すると現在の値が維持されることを確認する。
フリー在庫がバッファ数より少ない場合、販売在庫が0となり負数にならないことを確認する。
倉庫・期限別の行の販売在庫を合算し、バッファを重ねて差し引かないことを確認する。

「販売在庫と販売在庫バッファ数（新システム）」