> 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/fulfillment-api/shipment-delivery.md).

# Shipment Delivery — 配達希望日・時間帯

出荷作業の注文に、購入者の**配達希望日**と**時間帯**を設定します。値は注文ヘッダ（`sot.lm_routing_orders`）の `desired_delivery_date` / `desired_delivery_time` に保存され、**ラベル生成時**に Ship\&Co の `setup.date`（配達指定日）/ `setup.time`（佐川時間帯コード）へ載って佐川送り状に印字されます（[Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md) のラベル生成を参照）。

カート側（Shopify メタフィールド `custom.pickup_date` / `pickup_time` 由来）の自動取込は [Routing](/lmile-docs/routing-api/orders.md) の `desiredDeliveryDate` / `desiredDeliveryTime` で行います。本エンドポイントは、出荷詳細ページからオペレーターが**後から手で設定／変更**するための軽量 write です（注文の 2 列だけを部分更新し、再ルーティング・再 dispatch はしません）。

> **Base URL** `https://api.lmile.io` · **認証** `x-ingest-secret` ヘッダー または operator JWT（`Authorization: Bearer`）（[詳細](/lmile-docs/getting-started/authentication.md)） · `shop` はリクエストボディに含めます（API キーで呼ぶ場合は省略できます）

> 設定した値は**既発行の送り状には反映されません**（ラベルは生成時にだけこの値を読みます）。送り状へ反映するには [Address Recovery](/lmile-docs/fulfillment-api/address-recovery.md) の `retry-label`（`force: true`）でラベルを**再発行**します（新しい追跡番号・キャリア再課金）。出荷詳細ページ（inventory-agent）は保存と同時に再発行を実行します。

## エンドポイント

| Method | Path                             | 用途                                 |
| ------ | -------------------------------- | ---------------------------------- |
| `POST` | `/api/routing/shipment/delivery` | 注文の配達希望日・時間帯を設定／変更（部分更新・再ルーティングなし） |

***

## `POST` /api/routing/shipment/delivery

指定注文の `desired_delivery_date` / `desired_delivery_time` だけを更新します。両フィールドとも `null` で指定解除できます。

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "routingOrderId": "11494bc4-f45f-4d0b-9d68-fd26c1a503ec",
  "desiredDeliveryDate": "2026-07-03",
  "desiredDeliveryTime": "12:00-14:00",
  "notifyDelay": true
}
```

### ボディパラメータ

| パラメータ                 | 型              |  必須 | 説明                                                                         |
| --------------------- | -------------- | :-: | -------------------------------------------------------------------------- |
| `shop`                | string         |  ✓  | 店舗ドメイン（API キーで呼ぶ場合は省略できます）                                                 |
| `routingOrderId`      | string (uuid)  |  ✓  | 対象注文（`sot.lm_routing_orders.id`）。同一 shop に実在すること                           |
| `desiredDeliveryDate` | string \| null |  ✓  | 配達希望日（ISO `YYYY-MM-DD`）。`null` で指定解除                                       |
| `desiredDeliveryTime` | string \| null |  ✓  | 配達希望時間帯（元表記。例 `"午前中"` / `"12:00-14:00"`）。`null` で指定解除                      |
| `notifyDelay`         | boolean        |     | `true` にすると、この変更が[遅延](#遅延)のときに購入者へ遅延のお知らせメールを送ります。遅延でない変更では無視します。省略時は送りません |

> `desiredDeliveryTime` は元表記のまま保存し、**佐川コードへの変換はラベル生成時**に行います（`午前中` → `before-noon`、`12:00-14:00` → `12-14` 等）。佐川が認識しない表記は「時間指定なし」扱いになります。佐川の有効スロット: `午前中` / `12:00-14:00` / `14:00-16:00` / `16:00-18:00` / `18:00-20:00` / `18:00-21:00` / `19:00-21:00`。

### レスポンス

```json
{
  "ok": true,
  "routingOrderId": "11494bc4-f45f-4d0b-9d68-fd26c1a503ec",
  "desiredDeliveryDate": "2026-07-03",
  "desiredDeliveryTime": "12:00-14:00",
  "delayed": true,
  "delayNotice": "dispatched"
}
```

| フィールド                 | 説明                                                                                                                                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `routingOrderId`      | 更新した注文の id                                                                                                                                                                              |
| `desiredDeliveryDate` | 保存後の配達希望日（`null` = 指定なし）                                                                                                                                                                |
| `desiredDeliveryTime` | 保存後の配達希望時間帯（`null` = 指定なし）                                                                                                                                                              |
| `delayed`             | この変更が[遅延](#遅延)だったか                                                                                                                                                                      |
| `delayNotice`         | 遅延のお知らせの送信結果。`null` = 送っていない（`notifyDelay` が無い / 遅延ではない）。`dispatched` = メール送信アプリへ渡した。`no_app` = メール送信アプリが設定されていない。`failed` = 渡せなかった。`dispatched` 以外はお知らせが届いていないので、必要なら購入者へ別の方法で連絡してください |

### 挙動・冪等性

* **冪等（部分更新）**: 配達希望日・時間帯を最新値で上書きします。同じ値の再 POST は副作用がありません（同じ値は遅延ではないので、お知らせも送りません）。他のヘッダ列（宛先・channel・tag 等）は一切触らず、**再ルーティング・再 dispatch も行いません**（それが必要な場合は [Routing Update](/lmile-docs/routing-api/cancel-update.md) を使用）。
* **送り状への反映**: この値はラベル生成時にだけ読まれます。既発行の送り状には反映されないため、反映するには `retry-label`（`force: true`）でラベルを再発行します（[Address Recovery](/lmile-docs/fulfillment-api/address-recovery.md)）。
* **cross-tenant ガード**: `routingOrderId` が**同一 shop に実在しない**場合は `404 routing_order_not_found`。
* **キャンセル済み注文**: `409 order_cancelled`（送り状を作り直す意味がないため変更不可）。

### 遅延

配達希望日のある注文を**より遅い日付にする**か、**指定なしにする**と「遅延」として記録します。前倒し・時間帯だけの変更・指定なしから日付を指定する変更は遅延ではありません。

* 遅延として記録すると、購入者のお届け状況ページに「遅延」と、変更前 → いまの予定が出ます。
* 例: 9/25 を 9/28 に、さらに 9/30 に遅らせると、お届け状況ページは「9/25 → 9/30」と出します（変更前は最初に約束した日のまま）。
* 最初の日付（上の例では 9/25）以前に戻すと、遅延の表示は消えます。購入者が自分で日時を選び直したときも消えます。
* `notifyDelay: true` のときは遅延のお知らせメールを 1 通送ります。メールの「変更前」はこの変更で置き換えた日（上の例の 2 回目なら 9/28）、「変更後」は新しい指定日です。指定なしにした場合は、お届け状況ページと同じお届け予定の範囲を載せます。
* お知らせはお届け状況メールと同じ宛先・同じ設定で送ります。お届け状況メールを送っていない注文（通知が無効・外部倉庫だけの注文）には送りません。

## エラー

エンドポイント固有:

| Status | 条件                                                                                  | レスポンス例                                                                                                             |
| :----: | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|  `400` | バリデーション失敗（`desiredDeliveryDate` が `YYYY-MM-DD` でない / `routingOrderId` が uuid でない 等） | `{ "ok": false, "error_kind": "invalid_input", "details": [{ "path": "desiredDeliveryDate", "message": "..." }] }` |
|  `404` | `routingOrderId` が同一 shop に存在しない                                                    | `{ "ok": false, "error_kind": "routing_order_not_found", "error": "routing order not found for shop" }`            |
|  `409` | 注文がキャンセル済み                                                                          | `{ "ok": false, "error_kind": "order_cancelled", "error": "cancelled order cannot be updated" }`                   |

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

## データモデル

* `sot.lm_routing_orders` — 注文ヘッダ。`desired_delivery_date`（date・配達希望日）/ `desired_delivery_time`（text・元表記の時間帯）。ラベル生成時に Ship\&Co `setup.date` / `setup.time` へ透過。指定なしは NULL。遅延の記録は `desired_delivery_prev_date` / `desired_delivery_prev_time`（遅らせる前の日時）/ `delivery_delayed_at`（最後に遅らせた時刻・NULL = 遅延していない）。
* `sot.lm_fulfillment_shipments` — この注文の出荷元ヘッダ（[Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md)）。ラベル（送り状）はこの shipment 単位で生成され、生成時に上記 2 列を読みます。


---

# 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/fulfillment-api/shipment-delivery.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.