> 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-memo.md).

# Shipment Memo — 出荷メモ

出荷作業の各 shipment（[Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md) の `sot.lm_fulfillment_shipments` = 注文 × 出荷元）に、オペレーターが時系列で残す**手書きメモ**を追記します。出荷詳細ページのタイムライン（システムイベント + 手書きメモ）に新しい順で表示されます。**追記のみ**（編集・削除なし = 完全な記録 / 監査ログ）。

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

> `/api/routing/shipment/memo` は機械間 secret（`x-ingest-secret`）と倉庫スタッフの operator JWT のどちらでも呼べます（系統はヘッダの有無で明示判別。[詳細](https://lmile.gitbook.io/lmile-docs/fulfillment-api/pages/7cB70I8yeRnMpvcdLkNu#routing-write-の-2-系統認証)）。operator JWT 経由は投稿者（`author_user_id` = 検証済スタッフ ID）を記録し、body の `authorUserId` より優先します。

> メモの**一覧取得 API はありません**。`body` / 投稿者はマーチャント私的注釈（PII 相当）のため、表示は merchant 管理 UI（出荷詳細ページ）が `service_role` で直読します。`agent_read` / LLM agent には露出しません。

## エンドポイント

| Method | Path                         | 用途                      |
| ------ | ---------------------------- | ----------------------- |
| `POST` | `/api/routing/shipment/memo` | 出荷メモの追記（1 回 = 1 行・追記のみ） |

***

## `POST` /api/routing/shipment/memo

指定 shipment に手書きメモを 1 件追記します。投稿のたびに新しい行を append します（編集・削除はありません）。

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "shipmentId": "11494bc4-f45f-4d0b-9d68-fd26c1a503ec",
  "body": "お客様より時間指定の希望あり（午前中）。",
  "authorEmail": "ops@demo-store.example"
}
```

### ボディパラメータ

| パラメータ          | 型             |  必須 | 説明                                                             |
| -------------- | ------------- | :-: | -------------------------------------------------------------- |
| `shop`         | string        |  ✓  | 店舗ドメイン（API キーで呼ぶ場合は省略できます）                                     |
| `shipmentId`   | string (uuid) |  ✓  | 対象 shipment（`sot.lm_fulfillment_shipments.id`）。同一 shop に実在すること |
| `body`         | string        |  ✓  | メモ本文（1〜2000 文字。前後空白は trim）                                     |
| `authorUserId` | string (uuid) |     | 投稿者の user id（監査用）。operator JWT 経由は検証済スタッフ ID が記録され、この値より優先されます |
| `authorEmail`  | string        |     | 投稿者のメール（表示用）                                                   |

### レスポンス

```json
{
  "ok": true,
  "memo": {
    "id": "a1b2c3d4-1111-2222-3333-444455556666",
    "body": "お客様より時間指定の希望あり（午前中）。",
    "author_email": "ops@demo-store.example",
    "created_at": "2026-06-21T10:30:00.000Z"
  }
}
```

| フィールド               | 説明                                     |
| ------------------- | -------------------------------------- |
| `memo.id`           | 追記したメモの id                             |
| `memo.body`         | 保存された本文                                |
| `memo.author_email` | 投稿者メール（表示用。投稿者 user id は PII のため返しません） |
| `memo.created_at`   | 追記時刻（タイムラインの並び順キー）                     |

### 挙動・冪等性

* **追記のみ（非冪等）**: 呼ぶたびに `sot.lm_shipment_memos` へ 1 行 append します（同じ `body` の再 POST も別の行になります）。編集・削除の API はありません（完全な記録 / 監査ログ）。
* **投稿者**: operator JWT 経由は検証済の `staff_user_id`（`auth.users.id`）を `author_user_id` に記録し、body の `authorUserId` より優先します。機械間 secret 経由は `author_user_id` = NULL（body の `authorUserId` を使用）。
* **cross-tenant ガード**: `shipmentId` が**同一 shop に実在しない**場合は `404 shipment_not_found`（別 shop の shipment にメモは付けられません）。
* **表示**: 一覧取得 API はありません。出荷詳細ページ（inventory-agent `/mypage/routing/shipments/:shipmentId`）が `service_role` で `shop + shipment_id` 絞り込みの直読を行い、`created_at` 降順でタイムラインに表示します。`agent_read` / LLM agent には露出しません（`body` / 投稿者 = PII 相当）。

## エラー

エンドポイント固有:

| Status | 条件                                                         | レスポンス例                                                                                              |
| :----: | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|  `400` | バリデーション失敗（`body` 空 / 2000 文字超 / `shipmentId` が uuid でない 等） | `{ "ok": false, "error_kind": "invalid_input", "details": [{ "path": "body", "message": "..." }] }` |
|  `404` | `shipmentId` が同一 shop に存在しない                               | `{ "ok": false, "error_kind": "shipment_not_found", "error": "shipment not found for shop" }`       |

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

## データモデル

* `sot.lm_shipment_memos` — 出荷（shipment）単位の手書きメモ。`shipment_id`（→ `sot.lm_fulfillment_shipments(id)`・`ON DELETE CASCADE`）/ `body`（自由記述）/ `author_user_id` / `author_email` / `created_at`。**追記のみ**（`updated_at` なし）。`body` / 投稿者は PII 相当のため `service_role` 専用（公開 view / `agent_read` 非公開・`agent_readonly` grant なし）。INDEX `(shop, shipment_id, created_at DESC)`。
* `sot.lm_fulfillment_shipments` — メモの対象（出荷元ヘッダ。[Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md)）。shipment 削除時はメモも CASCADE で削除されます。


---

# 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-memo.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.