よくある間違いと対処

2026-10-22 時点の公式のページと照合した内容です。

公式のページに書かれていない、集計と更新の間違いです。検索の条件の書き方は API の基本ルール にまとめています。

検索の対象

1. 店舗名とモール名を取り違えた

• 症状: 「店舗ごと」に集計したのに、同じモールの複数店舗が 1 行にまとまります（またはその逆）。
• 原因: 店舗名 shop_name は、テナントが付けた個々の店舗の名前です。モール名 mall_name は、販売プラットフォームの名前です。1 つのモールに複数の店舗を持てます。
• 正しいやり方: 「店舗」は receive_order_shop_id と shop_id で結合して shop_name を使います。「モール」は shop_mall_id と mall_id で結合して mall_name を引きます。
• 関係する API: /api_v1_master_shop/search、/api_v1_system_mall/search

2. 商品分類タグを受注分類タグで代用した

• 症状: 「商品分類タグが X の受注」を取ったつもりが 0 件になります。
• 原因: 商品分類タグは商品マスタの goods_tag です。受注分類タグ receive_order_gruoping_tag は受注に付ける別のタグで、商品分類タグの値は入っていません。受注ヘッダに goods_tag はありません。
• 正しいやり方: 受注明細の receive_order_row_goods_id と商品マスタの goods_id で結合して、goods_tag を引きます。goods_tag は [タグA][タグB] のように角括弧のタグを連結した文字列で、空のこともあります。
• 関係する API: /api_v1_receiveorder_row/search、/api_v1_master_goods/search

3. 印刷待ちと印刷日待ちを状態名で分けようとした

• 症状: 2 つが区別できません。
• 原因: どちらも受注状態 20 で、状態名も「納品書印刷待ち」で返ります。違いは、納品書印刷指示日 receive_order_statement_delivery_instruct_printing_date が今日以前か未来かです。指示日が未設定の受注は "0000-00-00 00:00:00" で返り、-lte の比較に当たります（印刷待ちに入ります）。
• 正しいやり方: 印刷待ちは -lte=<今日>、印刷日待ちは -gt=<今日> を、状態とキャンセル区分の条件に足します。

receive_order_order_status_id-eq=20
receive_order_cancel_type_id-eq=0
receive_order_statement_delivery_instruct_printing_date-lte=2026-10-22 23:59:59

• 関係する API: /api_v1_receiveorder_base/search

金額と件数

4. 単価を合計して売上にした

• 症状: 売上が、数量の分だけ小さく出ます。
• 原因: receive_order_row_unit_price は 1 個あたりの値です。
• 正しいやり方: 明細単位なら小計金額 receive_order_row_sub_total_price、伝票単位なら商品計 receive_order_goods_amount か総合計 receive_order_total_amount を使います。計算式は 受注明細の項目 と 受注伝票の項目 にあります。

5. 明細と結合した後に、ヘッダの金額を合計した

• 症状: 売上が実際より大きく出ます。
• 原因: ヘッダの項目は、明細と結合すると明細の行数だけ同じ値が並びます。3 明細の受注なら、総合計が 3 回数えられます。
• 正しいやり方: 商品の条件が入る集計は、明細の receive_order_row_sub_total_price を合計します。伝票単位の条件だけで集計するなら、ヘッダを明細と結合せずに合計します。

6. 明細の行数を受注の件数として数えた

• 症状: 「受注件数」が多く出ます。
• 原因: 1 つの受注に、明細が複数あります。
• 正しいやり方: 受注件数は、receive_order_row_receive_order_id の重複を除いた数です。条件がヘッダだけで書けるなら、/api_v1_receiveorder_base/count を使います。

更新

7. 状態を進める更新を、同じ取得条件のまま定期実行した

• 症状: 2 回目以降、前回処理した受注をまた拾って、毎回失敗します。
• 原因: 出荷確定（/shipped）・納品書印刷済（/receipted）・配送情報出力済（/labelprinted）・同梱（/bundle）は、更新後に状態や区分が変わります。取得条件が更新後の値を含んだままだと、同じ受注を何度も対象にします。
• 正しいやり方: 取得条件から更新後の値を外します。出荷確定なら 50、納品書印刷済なら 40、配送情報出力済ならラベル発行フラグ 2、同梱ならキャンセル区分 3 です。状態が変わらない分割は、処理した受注に印を付けて、次回の取得から外します。更新できない状態は 受注伝票更新 と メッセージコード にあります。

8. receive_order_shipped_update_flag=1 で出荷確定にしようとした

• 症状: 受注状態が 50 になりません。
• 原因: このフラグは「出荷確定済みの受注でも更新を許す」ためのもので、出荷確定の操作ではありません。
• 正しいやり方: 出荷確定は 受注伝票出荷確定処理 で行います。出荷確定を API で取り消すことはできません。

9. 確認チェックに、検索で読んだ値をそのまま書いた

• 症状: 確認済みにしたつもりが、確認待ちになります（またはその逆）。
• 原因: receive_order_confirm_check_id は、読む値（2 が確認済み）と書く値（1 でチェックを付ける）の体系が違います。
• 正しいやり方: 確認済みにするなら 1 を書きます。書く値は 受注伝票更新、読む値は 受注伝票の項目 にあります。

10. 作業用欄や備考に送った値で、元の内容が消えた

• 症状: 人が手で書いていたメモが消えます。
• 原因: 作業用欄 receive_order_worker_text や備考 receive_order_note は、送った値で丸ごと置き換わります。
• 正しいやり方: 元の内容を残すなら、送る直前に現在の値を取得し、後ろに足した値を送ります。

11. 在庫を「N 個にする」つもりで、減らす量を確かめなかった

• 症状: 在庫が目標の値になりません。
• 原因: 在庫数は差分でしか送れません（FAQ）。そのうえで、引当の無い商品で在庫数を超えて減らすと、在庫数は 0 で止まります。フリー在庫数（在庫数 − 引当数）が 0 の商品は、減らしても出庫されません。アップロードは非同期なので、同じ内容を送り直すと二重に反映されます。
• 正しいやり方: /api_v1_master_stock/search で現在の在庫数を読み、差分を計算して送ります。減らす量はフリー在庫数 stock_free_quantity 以下にします。結果は que_id でアップロードキューを引いて確かめ、送り直しません。

そのほか

12. 支払区分や発送方法区分のコードを決め打ちした

• 症状: あるテナントでは動くのに、別のテナントでは対象が 0 件になります。
• 原因: 支払区分 receive_order_payment_method_id・発送方法区分 receive_order_delivery_id などは、テナントごとに使っている値が違います。
• 正しいやり方: 区分情報の API（/api_v1_system_paymentmethod/info・/api_v1_system_delivery/info）から引きます。