Transfer Receive — 宛先側の入荷照合

発送確定されたバルクを宛先倉庫が受け取り、箱の中身をユニットQR で 1 点ずつスキャン照合します。1 スキャン = 1 単位の受領で、受領した単位は return_received（unit は allocated に戻り通常フロー再開）になります。遷移は単発の POST /api/routing/change-source の受領（return_received）と同一実装を共用し、現在在庫の新拠点への確定・新出荷元への出荷指示（create dispatch）・自己在庫の再計算まで同じ副作用が走ります。

Base URL https://api.lmile.io · 認証 operator JWT（Authorization: Bearer）（詳細） · shop はリクエストボディに含めます

全所属単位が終端（return_received / cancelled）になった受領で、バルクは自動的に received で締まります。

スキャン照合とは別に、返送ラベルの配送完了（キャリアの delivered）を検知した dispatched バルクはステータスのみ received に自動遷移します（unit を allocated に戻す再フルフィルメントは行いません）。詳細は Transfer Batches を参照。

エンドポイント

Method	Path	用途	テーブル
POST	/api/operator/transfer/batches/receive	宛先側の入荷照合（1 点ずつスキャン受領）	lm_transfer_batches / lm_fulfillment_source_changes / lm_fulfillment_units

---

POST /api/operator/transfer/batches/receive

リクエスト

POST https://api.lmile.io/api/operator/transfer/batches/receive
Authorization: Bearer {OPERATOR_JWT}
Content-Type: application/json

{
  "shop": "demo-store.myshopify.com",
  "batchId": "0d9c5a8e-1234-4abc-9def-0123456789ab",
  "qr": "4912345678901|aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}

ボディパラメータ

パラメータ	型	必須	説明
shop	string	✓	店舗ドメイン（スタッフの束縛 shop 内）
batchId	string (uuid)	✓	受領中のバルク（内容物リストのバルクID バーコードから）
qr	string	✓	ユニットQR の生値（`
note	string		ケースに残すメモ（任意）

レスポンス

{
  "ok": true,
  "batchId": "0d9c5a8e-1234-4abc-9def-0123456789ab",
  "received": true,
  "sourceChangeId": "cccccccc-dddd-eeee-ffff-000000000000",
  "unit": { "id": "…", "barcode": "4912345678901", "lineInstanceNo": 1, "status": "allocated" },
  "order": { "id": "…", "orderNumber": "1001", "sourceSystem": "shopify" },
  "createDispatches": [ { "locationId": "…", "status": "skipped", "attempts": 0 } ],
  "remainingUnits": 3,
  "batchStatus": "dispatched"
}

フィールド	説明
unit.status	受領後は allocated（新出荷元での確保 → 出荷の通常フローへ合流）
createDispatches	新出荷元への出荷指示（WMS 設定が無ければ skipped）
remainingUnits	バルク内の未受領（未終端）単位数。0 でバルクが received に
batchStatus	受領後のバルク status

挙動・冪等性

• 解決は add-unit と同じ shipmentId → 注文 → 同 barcode の単位 の経路で、当該バルク所属のケースだけが照合対象です。
• 受領済み単位の再スキャンは 200 の no-op（received: false, alreadyReceived: true）。
• バルクが open（未発送）の場合は 409 batch_not_dispatched。
• 受領で現在在庫が新拠点に確定し、新拠点が自己在庫（MFC）なら available の再計算 + 在庫変動 webhook が発火します。現物の棚への配置（棚入庫）は本 API では行いません — Shelf Inventory / MFC Inventory で別途反映してください。

エラー

エンドポイント固有:

Status	条件	レスポンス例
404	バルク / shipment / unit が存在しない	{ "ok": false, "error_kind": "batch_not_found" } 等
409	バルクが未発送（open）	{ "ok": false, "error_kind": "batch_not_dispatched" }
422	ユニットQR 形式不正 / 旧規格	{ "ok": false, "error_kind": "invalid_qr" } / { "error_kind": "legacy_qr" }
422	スキャンした単位が当該バルク所属でない	{ "ok": false, "error_kind": "not_in_this_batch" }
409	受領可能（return_in_transit）でない（caseStatuses[] 同梱）	{ "ok": false, "error_kind": "unit_not_receivable", "caseStatuses": [...] }

共通エラー（401 / 400 共通形 / 403 / 405 / 500 / 503）は Error Codes を参照。

データモデル

• sot.lm_transfer_batches — 全単位終端で status='received' / received_at。操作者監査は単位側 lm_fulfillment_source_changes.updated_by_staff_user_id（LM-850）。
• sot.lm_fulfillment_source_changes — 受領ケースが return_received + received_at。
• sot.lm_fulfillment_units — 受領単位が allocated・current_inventory_location_id = 新拠点。