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

# Transfer Dispatch — 発送確定・内容物リスト

[バルク](/lmile-docs/transfer-api/batches.md)の発送確定です。`open` のバルクの内容物を確定して**内容物リスト PDF**（バルクID バーコード + 明細 + 受領チェック欄）を生成・保存し、所属する全単位を一括で `return_in_transit`（unit は `source_change_in_transit`）へ進めます。遷移は単発の [`POST /api/routing/change-source`](/lmile-docs/oversell-api/source-change.md) と同一実装を共用します。

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

> キャリアの配送ラベルは生成しません（内容物リストのみ）。返送便のキャリアラベルが必要な運用は既存の[返送ラベルのバッチ生成](/lmile-docs/oversell-api/source-change.md)（`/api/routing/return-label/generate-batch`）が担いますが、**バルク所属の単位はそのバッチ対象から除外**されます（二重手配防止）。

## エンドポイント

| Method | Path                                      | 用途                       | テーブル                                                                                                    |
| ------ | ----------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `POST` | `/api/operator/transfer/batches/dispatch` | 発送確定（内容物確定 + PDF + 一括遷移） | `lm_transfer_batches` / `lm_fulfillment_source_changes` / `lm_fulfillment_units` / `lm_shelf_inventory` |

***

## `POST` /api/operator/transfer/batches/dispatch

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "batchId": "0d9c5a8e-1234-4abc-9def-0123456789ab"
}
```

### ボディパラメータ

| パラメータ     | 型             |  必須 | 説明                     |
| --------- | ------------- | :-: | ---------------------- |
| `shop`    | string        |  ✓  | 店舗ドメイン（スタッフの束縛 shop 内） |
| `batchId` | string (uuid) |  ✓  | 発送確定するバルク              |

### レスポンス

```json
{
  "ok": true,
  "batchId": "0d9c5a8e-1234-4abc-9def-0123456789ab",
  "status": "dispatched",
  "dispatchedAt": "2026-06-12T10:00:00.000Z",
  "unitCount": 12,
  "transitioned": 12,
  "alreadyInTransit": 0,
  "cancelledExcluded": 1,
  "pdfPath": "demo-store.myshopify.com/transfer-manifest/0d9c5a8e-….pdf",
  "pdfUrl": "https://…/storage/v1/object/public/picking-lists/…/transfer-manifest/….pdf"
}
```

| フィールド               | 説明                                        |
| ------------------- | ----------------------------------------- |
| `unitCount`         | 内容物（中止以外の所属単位）数                           |
| `transitioned`      | 今回 `return_in_transit` へ進めた単位数            |
| `alreadyInTransit`  | 既に返送中だった単位数（途中失敗からの再実行時）                  |
| `cancelledExcluded` | 中止済みで内容物から除外した単位数                         |
| `pdfUrl`            | 内容物リスト PDF の public URL（iOS はこれを開いて印刷/表示） |

### 挙動・冪等性

* 処理順は **PDF 生成 → 単位の一括遷移 → バルク確定**。PDF 生成に失敗した場合は何も変異させず失敗します。途中で失敗した場合はバルクが `open` のまま残り、再実行が `change_requested` の残りから再開します（遷移済みは skip）。
* `dispatched` / `received` 済みへの再実行は `200` + 既存 `pdfUrl` の no-op（`alreadyDispatched: true`）。
* 内容物が 0 件（空、または全て中止）は `422 empty_batch`。
* 並行して単発 API で状態が進んでいた単位は `409 unit_not_dispatchable` で中断します（黙認しません）。
* **在庫**: 現物が棚から箱へ移るため、旧拠点（自己在庫 MFC）の棚数量を単位ごとに 1 減らし、自己在庫の `available` を再計算して[在庫変動 webhook](/lmile-docs/webhooks/source-inventory.md) を発火します。ピック済み（`picked_at` あり）の単位はピック時に減算済みのため二重減算しません。棚を持たない拠点（同期拠点）は no-op です。
* PDF は public bucket（picking-lists・[Picking List](/lmile-docs/fulfillment-api/picking-list.md) と同じ）にパス `{shop}/transfer-manifest/{batchId}.pdf` で保存され、再実行では上書きされます。

## エラー

エンドポイント固有:

| Status | 条件                                   | レスポンス例                                                                      |
| :----: | ------------------------------------ | --------------------------------------------------------------------------- |
|  `404` | バルクが存在しない                            | `{ "ok": false, "error_kind": "batch_not_found" }`                          |
|  `422` | 内容物が 0 件（空 / 全て中止）                   | `{ "ok": false, "error_kind": "empty_batch", "cancelledCount": 1 }`         |
|  `409` | 並行更新で単位が `source_change_pending` でない | `{ "ok": false, "error_kind": "unit_not_dispatchable", "transitioned": 3 }` |

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

## データモデル

* `sot.lm_transfer_batches` — `status='dispatched'` / `dispatched_at` / `pdf_storage_path`。操作者監査は単位側 `lm_fulfillment_source_changes.updated_by_staff_user_id`（LM-850）。
* `sot.lm_fulfillment_source_changes` — 所属ケースが `return_in_transit` + `in_transit_at`。
* `sot.lm_fulfillment_units` — 所属単位が `source_change_in_transit`。
* `sot.lm_shelf_inventory` — 旧拠点の棚数量 −1（reason=`pick`、[Shelf Inventory](/lmile-docs/shelf-api/inventory.md) のログに記録）。


---

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