> 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/inbound.md).

# Transfer Inbound — 出荷元への入荷転送

在庫のある拠点と実際に出荷する拠点が違うとき、現物を**出荷元へ運んでから出荷する**注文があります（刻印加工のための倉庫送り、海外発送のための国内 MFC 集約など）。この API は、その移動区間を拠点間移動として記録し、**荷物がいまどこにあるか**を注文の進捗として追えるようにします。

送るのは「すでに発送した便の追跡番号」です。本 API は**配送ラベルを発行しません**（移動元がすでに発行済みの便を登録するだけ）。登録すると、その注文は移動が終わるまで「移動中」として扱われ、荷物が出荷元に届いた時点で自動的に出荷準備中へ進みます。

> **Base URL** `https://api.lmile.io` · **認証** `x-ingest-secret` ヘッダー（[詳細](/lmile-docs/getting-started/authentication.md)） · `shop` はリクエストボディに含めます（省略するとキーのアカウント）

移動元 → 出荷元へ運ぶ「入荷転送」と、出荷元 → 倉庫へ送り返す [返送バルク](/lmile-docs/transfer-api/batches.md) は別物です。返送バルクは返送ラベルを発行しますが、入荷転送は発行しません。

## エンドポイント

| Method | Path                            | 用途             | テーブル                                                                                 |
| ------ | ------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| `POST` | `/api/routing/transfer/inbound` | 出荷元への入荷転送を登録する | `lm_transfer_batches` / `lm_fulfillment_source_changes` / `lm_fulfillment_shipments` |

***

## `POST` /api/routing/transfer/inbound

対象の出荷（`shipmentId`）に載っている有効な単位すべてを 1 つの移動としてまとめ、転送便の追跡番号を紐づけます。

### リクエスト

```http
POST https://api.lmile.io/api/routing/transfer/inbound
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{
  "shop": "demo-store.myshopify.com",
  "shipmentId": "ed947efd-cb80-4528-be16-5324224ef173",
  "fromInventoryLocationId": "b179515a-6ca9-4ffa-a40b-0664ccc74366",
  "fromSourceLocationId": "b179515a-6ca9-4ffa-a40b-0664ccc74366",
  "toInventoryLocationId": "343ff919-6f3a-473e-9091-75f80db718bc",
  "toSourceLocationId": "343ff919-6f3a-473e-9091-75f80db718bc",
  "trackingNumber": "363663500863",
  "carrierCode": "Sagawa (JA)",
  "dispatchedAt": "2026-08-17T01:02:01.795Z",
  "reason": "overseas forward"
}
```

### ボディパラメータ

| パラメータ                     | 型                 |  必須 | 説明                                                             |
| ------------------------- | ----------------- | :-: | -------------------------------------------------------------- |
| `shop`                    | string            |     | 店舗ドメイン（省略するとキーのアカウント）                                          |
| `shipmentId`              | string (uuid)     |  ✓  | 現物の到着を待っている出荷                                                  |
| `fromInventoryLocationId` | string (uuid)     |  ✓  | 現物がいまある拠点（移動元）                                                 |
| `fromSourceLocationId`    | string (uuid)     |  ✓  | 移動元の出荷元拠点                                                      |
| `toInventoryLocationId`   | string (uuid)     |  ✓  | 現物を運ぶ先の拠点（移動先 = 受け取る側）                                         |
| `toSourceLocationId`      | string (uuid)     |  ✓  | 移動先の出荷元拠点。`fromSourceLocationId` と同じ値は送れません                    |
| `trackingNumber`          | string            |  ✓  | 転送便の追跡番号                                                       |
| `carrierCode`             | string            |  ✓  | 転送便のキャリア（`Sagawa (JA)` / `yamato` / `ups_saver` など表記揺れは吸収されます） |
| `dispatchedAt`            | string (ISO 8601) |     | 転送便を発送した時刻。省略すると受信時刻                                           |
| `reason`                  | string            |     | 記録用のメモ（最大 500 文字）                                              |

### レスポンス

```json
{
  "ok": true,
  "created": true,
  "batchId": "1a2b3c4d-5e6f-4708-9abc-def012345678",
  "sourceChangeIds": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"],
  "trackingNumber": "363663500863",
  "carrierCode": "Sagawa (JA)",
  "dispatchedAt": "2026-08-17T01:02:01.795Z"
}
```

| フィールド             | 説明                                     |
| ----------------- | -------------------------------------- |
| `created`         | 新しく登録したか。`false` は同じ出荷にすでに移動が登録済み（再送時） |
| `batchId`         | 登録した移動（1 便 = 1 件）                      |
| `sourceChangeIds` | 移動に載せた単位ごとの記録                          |

### 挙動・冪等性

* 登録すると、その出荷は**移動中**になります。倉庫アプリの作業リストからは外れ（現物がまだ届いていないため）、管理画面の出荷一覧には残ります。
* **追跡番号とキャリアは必須**です。追跡できない移動を作らないための制約で、欠けていると `422` を返します。
* **同じ `shipmentId` に対して再送しても二重に登録されません。** すでに有効な移動があれば `created: false` と既存の `batchId` を返すので、そのまま再送してかまいません（イベントの再配信で移動が増えることはありません）。
* 中止済みの移動しか残っていない場合は、新しく登録し直せます。
* 移動は登録した時点で「発送済み」の状態で作られます（すでに現物が出発しているため）。倉庫への発送通知や返送ラベルの発行は行いません。
* **受け取りの登録は不要です。** サーバーが約 1 時間ごとに配送状況を確認し、**配達完了を検知した時点で自動的に受領扱いにして、その注文を出荷準備中へ進めます**。倉庫アプリでのスキャン受領はこの移動には使えません（`409 inbound_batch_not_manually_receivable`）。
* 配送状況は確認のたびに記録され、「いまどこまで運ばれているか」として参照できます。発送直後はキャリア側にまだ反映されておらず状況が取れないことがありますが、これは異常ではありません。24 時間を超えても取れない場合や、いったん進んだあとに異常が出た場合だけ警告として記録されます。
* この登録で在庫の数量は動きません。動くのは「現物がどこにあるか」の記録だけです。

## エラー

エンドポイント固有:

| Status | 条件             | レスポンス例                                                          |
| :----: | -------------- | --------------------------------------------------------------- |
|  `404` | 出荷が存在しない       | `{ "ok": false, "error_kind": "shipment_not_found" }`           |
|  `409` | 出荷が取消済み        | `{ "ok": false, "error_kind": "shipment_cancelled" }`           |
|  `422` | 移動元と移動先の出荷元が同じ | `{ "ok": false, "error_kind": "inbound_transfer_same_source" }` |
|  `422` | 出荷に有効な単位が無い    | `{ "ok": false, "error_kind": "no_active_units" }`              |

共通エラー（`401` / `400` 共通形 / `403` / `405` / `500` / `503`）は [Error Codes](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

* `sot.lm_transfer_batches` — `kind='inbound'` の移動 1 件。登録時から `status='dispatched'`。配送状況のスナップショット（`tracking_status` / `tracking_checked_at` / `tracking_last_event`）を保持し、配達完了で `received` + `received_at`。
* `sot.lm_fulfillment_source_changes` — 単位ごとの記録。`leg_mode='inbound'` / `status='return_in_transit'` / `return_tracking_number`・`return_carrier_code` に転送便の追跡番号。
* `sot.lm_fulfillment_shipments` — `is_inbound_transit` が移動中フラグ。配達完了で解除され、単位に `picked_at` が入って出荷準備中になります。


---

# 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/inbound.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.