> 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/routing-api/wms-shipping-request.md).

# WMS Shipping Request — WMS 出荷指示送信

出荷する荷物 1 つぶんの内容（宛先・明細・金額・お届け希望）を送ると、記録を残したうえで倉庫へ出荷指示を出します。倉庫ごとの様式（項目名・日時や電話の書式・手数料や税の計算）への変換はサーバー側で行うので、**送る側は Shopify から取れた値をそのまま渡してください**。整形や既定値の穴埋めは不要です。

出荷指示の取り下げも同じ入口から送ります。送信せず記録だけ行う `shadow` モードがあり、切替前の検証に使えます。

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

## エンドポイント

| Method | Path                                | 用途                          |
| ------ | ----------------------------------- | --------------------------- |
| `POST` | `/api/routing/wms-shipping-request` | 出荷指示（またはその取り下げ）の記録 + 倉庫への送信 |

> 送信の枠組み（`shop` / `order_id` など）は snake\_case、出荷指示の中身（`instruction`）は camelCase です。

***

## `POST` /api/routing/wms-shipping-request

荷物 1 つぶんの出荷指示を受け取り、記録してから倉庫へ送ります。結果は同期レスポンスで返ります。

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "mode": "live",
  "order_id": "6180316217477",
  "order_name": "BJP1026884",
  "attempt": 1,
  "action": "SHIPPING_REQUEST",
  "instruction": {
    "orderNo": "BJP1026884",
    "sourceOrder": {
      "system": "shopify",
      "id": "6180316217477",
      "name": "BJP1026884",
      "createdAt": "2026-08-05T03:47:59Z",
      "fulfillmentOrderId": "7275850662021",
      "note": null,
      "tags": ["1_orders"],
      "customAttributes": [{ "key": "isGiftWrapping", "value": "true" }]
    },
    "billTo": {
      "firstName": "明子", "lastName": "久保", "name": "久保 明子",
      "zip": "233-0013", "country": "JP",
      "province": "神奈川県", "provinceCode": "JP-14",
      "city": "横浜市港南区丸山台", "address1": "2-19-10", "address2": "サンプラザ丸山台D1",
      "phone": null, "company": null
    },
    "shipTo": { "…": "billTo と同じ形" },
    "contactEmail": "buyer@example.com",
    "customerDefaultCompany": null,
    "delivery": { "carrierCode": "佐川急便", "desiredDate": "2026-09-10", "desiredTime": "午前中" },
    "payment": { "gatewayNames": ["shopify_payments"] },
    "amounts": { "orderTotal": "14960.0", "orderShipping": "0.0" },
    "lines": [
      {
        "lineItemId": "gid://shopify/LineItem/1",
        "sku": "SKU-1", "name": "商品名 - グレージュ", "title": "商品名",
        "quantity": 1, "unitPrice": "11440.0",
        "engravingText": null, "preorderText": null
      }
    ],
    "flags": { "overseasRedirect": false }
  }
}
```

取り下げは `action` を変え、`instruction` は伝票番号だけにします。

```json
{
  "shop": "demo-store.myshopify.com",
  "mode": "live",
  "order_id": "6180316217477",
  "order_name": "BJP1026884",
  "action": "SHIPPING_CANCEL",
  "instruction": { "orderNo": "BJP1026884" }
}
```

### ボディパラメータ

| パラメータ         | 型      |  必須 | 説明                                                  |
| ------------- | ------ | :-: | --------------------------------------------------- |
| `shop`        | string |     | ショップドメイン（省略するとキーのアカウント）                             |
| `mode`        | string |  ✓  | `shadow`（記録のみ・倉庫へ送らない）/ `live`（記録 + 送信）             |
| `order_id`    | string |  ✓  | 注文 ID（数値文字列）。記録の検索キー                                |
| `order_name`  | string |  —  | 注文名（例 `BJP1026884`）。記録用                             |
| `attempt`     | number |  —  | 送信側の通番（1 = 初回）。記録用                                  |
| `action`      | string |  ✓  | `SHIPPING_REQUEST`（出荷指示）/ `SHIPPING_CANCEL`（その取り下げ） |
| `instruction` | object |  ✓  | 出荷指示の中身。下記                                          |

#### `instruction` オブジェクト（`SHIPPING_REQUEST`）

**値は整形せずに送ってください。** `null` は `null` のまま、金額は文字列のまま、日時は ISO のまま、姓と名は分けたまま、住所は分割せずに送ります。倉庫の様式に合わせる処理（空文字への穴埋め・JST への変換・電話番号の整形・姓名の並び・住所の分割・送料の按分・税の逆算）はすべてサーバー側で行います。

| パラメータ                    | 型      |  必須 | 説明                                                     |
| ------------------------ | ------ | :-: | ------------------------------------------------------ |
| `orderNo`                | string |  ✓  | 伝票番号。1 注文を複数の荷物に分けるときは 2 本目以降を連番にします（例 `BJP1026884-1`） |
| `sourceOrder`            | object |  ✓  | 注文そのものの情報。下記                                           |
| `billTo`                 | object |  ✓  | 請求先。下記                                                 |
| `shipTo`                 | object |  ✓  | 配送先。`billTo` と同じ形                                      |
| `contactEmail`           | string |  —  | 連絡先メール。請求先・配送先とも同じ値を使います                               |
| `customerDefaultCompany` | string |  —  | 顧客の既定住所の会社名。伝票の備考に印字されます                               |
| `delivery`               | object |  ✓  | 配送方法とお届け希望。下記                                          |
| `payment`                | object |  ✓  | 支払い方法。下記                                               |
| `amounts`                | object |  ✓  | 注文全体の金額。下記                                             |
| `lines`                  | array  |  ✓  | **この荷物に載せる明細だけ**。下記                                    |
| `flags`                  | object |  ✓  | 下記                                                     |

#### `sourceOrder` オブジェクト

| パラメータ                | 型               |  必須 | 説明                                                    |
| -------------------- | --------------- | :-: | ----------------------------------------------------- |
| `system`             | string          |  ✓  | 取込元（`shopify`）                                        |
| `id`                 | string          |  ✓  | 注文 ID（数値文字列。GID ではありません）                              |
| `name`               | string          |  —  | 注文名                                                   |
| `createdAt`          | string          |  —  | 注文日時（ISO 8601 のまま。JST への変換は不要）                        |
| `fulfillmentOrderId` | string          |  ✓  | フルフィルメントオーダー ID（数値文字列）                                |
| `note`               | string          |  —  | 注文メモの原文。加工しないでください（この荷物に刻印品が無ければ、刻印の指示行だけをサーバー側で除きます） |
| `tags`               | array \| string |  —  | 注文タグ。配列でも文字列でも受け付けます                                  |
| `customAttributes`   | array           |  —  | 注文レベルの属性（`{key, value}`）。ギフトラッピングの判定に使います             |

#### `billTo` / `shipTo` オブジェクト

| パラメータ                       | 型      | 説明                                           |
| --------------------------- | ------ | -------------------------------------------- |
| `firstName` / `lastName`    | string | 名 / 姓。**分けたまま**送ってください（並び順は宛先の国で変わります）       |
| `name`                      | string | 氏名。`firstName` / `lastName` が両方空のときの代わりに使います |
| `zip`                       | string | 郵便番号                                         |
| `country`                   | string | 国コード（`JP` など）                                |
| `province` / `provinceCode` | string | 都道府県。`JP-13` のようなコードでも英語表記でも構いません            |
| `city`                      | string | 市区町村。**分割せずに**送ってください                        |
| `address1` / `address2`     | string | 番地 / 建物名・部屋番号                                |
| `phone`                     | string | 電話番号。`+81` 始まりのままで構いません                      |
| `company`                   | string | 会社名                                          |

#### `delivery` / `payment` / `amounts` / `flags`

| パラメータ                    | 型       | 説明                                                 |
| ------------------------ | ------- | -------------------------------------------------- |
| `delivery.carrierCode`   | string  | 配送方法。未指定（`null`）なら既定の配送方法になります                     |
| `delivery.desiredDate`   | string  | お届け希望日。指定が無ければ `null`                              |
| `delivery.desiredTime`   | string  | お届け希望時間帯。指定が無ければ `null`                            |
| `payment.gatewayNames`   | array   | 支払いゲートウェイ名の配列。**語彙の変換は不要**です（代金引換なら手数料もサーバー側で付きます） |
| `amounts.orderTotal`     | string  | 注文合計（送料込み）。**文字列のまま**                              |
| `amounts.orderShipping`  | string  | 送料（割引適用後）。**文字列のまま**                               |
| `flags.overseasRedirect` | boolean | 海外宛の荷物を国内の転送先へ送るとき `true`。転送先の住所はサーバー側の設定です        |

> `amounts` は**注文全体**の金額です。荷物ごとの送料按分と税の逆算に使うため、その荷物に載せた明細だけの合計ではなく、注文の合計を送ってください。

#### `lines[]` オブジェクト

| パラメータ            | 型      |  必須 | 説明                                                           |
| ---------------- | ------ | :-: | ------------------------------------------------------------ |
| `lineItemId`     | string |  ✓  | 明細 ID                                                        |
| `sku`            | string |  ✓  | SKU                                                          |
| `name` / `title` | string |  —  | 表示名。`name` を優先し、無ければ `title` を使います                           |
| `quantity`       | number |  ✓  | この荷物に載せる数量                                                   |
| `unitPrice`      | string |  —  | 単価（割引適用後。無ければ元の単価）。**文字列のまま**                                |
| `engravingText`  | string |  —  | 刻印の指定文字。**指定が無ければ `null`**（空文字ではなく `null`。空文字は「刻印あり」と読まれません） |
| `preorderText`   | string |  —  | 予約商品の納期テキスト。予約でなければ `null`                                   |

> ギフトラッピングや刻印サービスの行を `lines` に足す必要はありません。注文属性と `engravingText` からサーバー側で組み立てます（同じ内容の行が実在する場合は二重に載せません）。

### レスポンス

`live` で送信に成功した場合:

```json
{
  "ok": true,
  "mode": "live",
  "status": "success",
  "request_id": "0d9c7c4e-…",
  "http_status": 200,
  "lambda_response": { "status": "ok" }
}
```

`shadow` の場合:

```json
{ "ok": true, "mode": "shadow", "status": "shadow", "request_id": "0d9c7c4e-…" }
```

| フィールド             | 説明                                   |
| ----------------- | ------------------------------------ |
| `request_id`      | 送信記録の ID。問い合わせ時にこの ID を伝えると記録を特定できます |
| `http_status`     | 倉庫側が返した HTTP ステータス（`live` のみ）        |
| `lambda_response` | 倉庫側のレスポンスボディ（`live` のみ）              |

### 挙動・冪等性

* **1 回の呼び出し = 1 件の送信記録 +（`live` 時）1 回の送信**です。冪等キーはありません。
* **★同じ伝票番号で送り直しても、内容は反映されません。** 倉庫は伝票番号ごとに 1 伝票を持ち、2 回目以降を**無視します**（上書きではありません）。つまり**初回に送った内容がそのまま出荷されます**。送る前に内容を確定させてください。あとから変えたい場合は、取り下げてから別の伝票として作り直すか、倉庫へ直接連絡してください。
* 1 注文を複数の荷物に分けるときは、**荷物ごとに別の伝票番号**で送ります（2 本目以降を `BJP1026884-1` のように連番にする）。同じ番号で 2 回送ると 2 つ目は無視されます。
* 送信は 1 発のみで、この API 自身はリトライしません。失敗したらレスポンスの `error_kind` を確認し、送信側のループで再送してください。**失敗時は倉庫に届いていない**ので、そのまま再送して構いません。
* `shadow` は倉庫へ一切送らず、記録だけを残します。
* 送信先が未設定のままの `live` 呼び出しは、送らずにエラーになります（silent skip しません）。

## エラー

エンドポイント固有:

| Status | `error_kind`                 | 条件                                                             |
| :----: | ---------------------------- | -------------------------------------------------------------- |
|  `502` | `lambda_http_error`          | 倉庫側が HTTP 200 以外を返した                                           |
|  `502` | `lambda_error_response`      | HTTP 200 だが倉庫側がエラー内容を返した（実行エラー / タイムアウト報告 / `status: "error"`） |
|  `502` | `lambda_invalid_json`        | 倉庫側レスポンスが JSON でない                                             |
|  `502` | `lambda_timeout`             | 送信がタイムアウトした（既定 30 秒）                                           |
|  `502` | `network_error`              | 送信先に接続できない                                                     |
|  `502` | `instruction_not_renderable` | `instruction` から出荷指示を組み立てられなかった（必須項目の欠落など）                     |
|  `503` | `wms_url_not_configured`     | サーバー側で送信先が未設定（`live` のみ）                                       |
|  `500` | `db_error`                   | 送信記録の保存に失敗（この場合は送信も行われません）                                     |

エラー時も記録は残り、レスポンスに `request_id` が含まれます（`db_error` を除く）。共通エラー（`401` / `400` 共通形 / `403` / `405` / `500` / `503`）は [Error Codes](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

| テーブル                           | 役割                                                                                                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sot.lm_wms_shipping_requests` | 送信記録（1 呼び出し = 1 行）。`mode` / `status`（`shadow` / `pending` / `success` / `error`）/ `instruction`（受け取った出荷指示）/ `request_payload`（倉庫へ実際に送った本文）/ `response_body` / `error_kind` を保持 |

`instruction` と `request_payload` は配送先・請求先の個人情報を含むため、read 用の公開 view は提供しません。


---

# 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/routing-api/wms-shipping-request.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.