> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/transfer-api/receive.md).

# Transfer Receive — 宛先側の入荷照合

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

> **Base URL** `https://api.lmile.io` · **認証** operator JWT（`Authorization: Bearer`）（[詳細](https://lmile.gitbook.io/lmile-docs/transfer-api/pages/7cB70I8yeRnMpvcdLkNu#operator-jwt-認証)） · `shop` はリクエストボディに含めます

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

> スキャン照合とは別に、返送ラベルの配送完了（キャリアの delivered）を検知した `dispatched` バルクは**ステータスのみ** `received` に自動遷移します（unit を `allocated` に戻す再フルフィルメントは行いません）。詳細は [Transfer Batches](/lmile-docs/transfer-api/batches.md) を参照。

## エンドポイント

| 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

### リクエスト

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

```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        |     | ケースに残すメモ（任意）                  |

### レスポンス

```json
{
  "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](/lmile-docs/transfer-api/batches.md) と同じ `shipmentId → 注文 → 同 barcode の単位` の経路で、**当該バルク所属**のケースだけが照合対象です。
* 受領済み単位の再スキャンは `200` の no-op（`received: false, alreadyReceived: true`）。
* バルクが `open`（未発送）の場合は `409 batch_not_dispatched`。
* 受領で現在在庫が新拠点に確定し、新拠点が自己在庫（MFC）なら `available` の再計算 + [在庫変動 webhook](/lmile-docs/webhooks/source-inventory.md) が発火します。**現物の棚への配置（棚入庫）は本 API では行いません** — [Shelf Inventory](/lmile-docs/shelf-api/inventory.md) / [MFC Inventory](/lmile-docs/ingestion-api/mfc-inventory.md) で別途反映してください。

## エラー

エンドポイント固有:

| 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](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

* `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` = 新拠点。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lmile.gitbook.io/lmile-docs/transfer-api/receive.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.