# API設計書

## 概要

本ドキュメントは、InvenTree Flutterモバイルアプリケーションが使用するInvenTree REST APIのエンドポイント仕様を記載したAPI設計書です。このアプリケーションはInvenTreeサーバーのREST APIクライアントとして動作し、在庫管理、部品管理、注文管理などの機能を提供します。

## 共通仕様

### ベースURL

```
{server_address}/api/
```

サーバーアドレスはユーザープロファイルで設定され、`/api/`がベースパスとして使用されます。

### 認証方式

Token認証（Token-based Authentication）

認証フローは以下の通り:
1. ユーザー名とパスワードでBasic認証を使用してトークンを取得
2. 取得したトークンを使用して以降のリクエストで認証

### 共通ヘッダー

| ヘッダー名 | 必須 | 説明 |
| --- | --- | --- |
| Authorization | ○ | `Token {token}` 形式の認証トークン |
| Content-Type | ○ | application/json |
| Accept | ○ | application/json |
| Accept-Language | - | ロケールコード（例: en, ja） |

### 共通エラーレスポンス

| ステータスコード | 説明 |
| --- | --- |
| 400 | Bad Request - リクエストパラメータ不正 |
| 401 | Unauthorized - 認証エラー |
| 403 | Forbidden - 権限エラー |
| 404 | Not Found - リソース未検出 |
| 500 | Internal Server Error - サーバーエラー |
| 502 | Bad Gateway - ゲートウェイエラー |
| 503 | Service Unavailable - サービス利用不可 |
| 504 | Gateway Timeout - ゲートウェイタイムアウト |

### ページネーション

リスト取得エンドポイントはページネーションをサポートします。

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| limit | integer | - | - | 取得件数上限 |
| offset | integer | - | 0 | 取得開始位置 |

**レスポンス形式:**

```json
{
  "count": 100,
  "results": [...]
}
```

## API一覧

| カテゴリ | エンドポイント | メソッド | 説明 |
| --- | --- | --- | --- |
| 認証 | /api/user/token/ | GET | 認証トークンを取得 |
| 認証 | /api/user/me/ | GET | 現在のユーザー情報を取得 |
| 認証 | /api/user/roles/ | GET | ユーザーロール・権限を取得 |
| 部品 | /api/part/ | GET | 部品一覧を取得 |
| 部品 | /api/part/{id}/ | GET | 部品詳細を取得 |
| 部品 | /api/part/{id}/ | PATCH | 部品を更新 |
| 部品 | /api/part/ | POST | 部品を作成 |
| 部品 | /api/part/{id}/ | DELETE | 部品を削除 |
| 部品 | /api/part/{id}/pricing/ | GET | 部品の価格情報を取得 |
| 部品 | /api/part/{id}/requirements/ | GET | 部品の要件情報を取得 |
| 部品カテゴリ | /api/part/category/ | GET | 部品カテゴリ一覧を取得 |
| 部品カテゴリ | /api/part/category/{id}/ | GET | 部品カテゴリ詳細を取得 |
| 部品カテゴリ | /api/part/category/ | POST | 部品カテゴリを作成 |
| 部品カテゴリ | /api/part/category/{id}/ | PATCH | 部品カテゴリを更新 |
| 部品テストテンプレート | /api/part/test-template/ | GET | テストテンプレート一覧を取得 |
| 在庫 | /api/stock/ | GET | 在庫アイテム一覧を取得 |
| 在庫 | /api/stock/{id}/ | GET | 在庫アイテム詳細を取得 |
| 在庫 | /api/stock/ | POST | 在庫アイテムを作成 |
| 在庫 | /api/stock/{id}/ | PATCH | 在庫アイテムを更新 |
| 在庫 | /api/stock/{id}/ | DELETE | 在庫アイテムを削除 |
| 在庫操作 | /api/stock/transfer/ | POST | 在庫を移動 |
| 在庫操作 | /api/stock/count/ | POST | 在庫を棚卸 |
| 在庫操作 | /api/stock/add/ | POST | 在庫を追加 |
| 在庫操作 | /api/stock/remove/ | POST | 在庫を削減 |
| 在庫テスト | /api/stock/test/ | GET | 在庫テスト結果一覧を取得 |
| 在庫テスト | /api/stock/test/ | POST | 在庫テスト結果を作成 |
| 在庫履歴 | /api/stock/track/ | GET | 在庫履歴一覧を取得 |
| 在庫ロケーション | /api/stock/location/ | GET | ロケーション一覧を取得 |
| 在庫ロケーション | /api/stock/location/{id}/ | GET | ロケーション詳細を取得 |
| 在庫ロケーション | /api/stock/location/ | POST | ロケーションを作成 |
| 在庫ロケーション | /api/stock/location/{id}/ | PATCH | ロケーションを更新 |
| 会社 | /api/company/ | GET | 会社一覧を取得 |
| 会社 | /api/company/{id}/ | GET | 会社詳細を取得 |
| 会社 | /api/company/ | POST | 会社を作成 |
| 会社 | /api/company/{id}/ | PATCH | 会社を更新 |
| サプライヤー部品 | /api/company/part/ | GET | サプライヤー部品一覧を取得 |
| サプライヤー部品 | /api/company/part/{id}/ | GET | サプライヤー部品詳細を取得 |
| サプライヤー部品 | /api/company/part/ | POST | サプライヤー部品を作成 |
| サプライヤー部品 | /api/company/part/{id}/ | PATCH | サプライヤー部品を更新 |
| メーカー部品 | /api/company/part/manufacturer/ | GET | メーカー部品一覧を取得 |
| メーカー部品 | /api/company/part/manufacturer/{id}/ | GET | メーカー部品詳細を取得 |
| 購買発注 | /api/order/po/ | GET | 購買発注一覧を取得 |
| 購買発注 | /api/order/po/{id}/ | GET | 購買発注詳細を取得 |
| 購買発注 | /api/order/po/ | POST | 購買発注を作成 |
| 購買発注 | /api/order/po/{id}/ | PATCH | 購買発注を更新 |
| 購買発注 | /api/order/po/{id}/issue/ | POST | 購買発注を発行 |
| 購買発注 | /api/order/po/{id}/cancel/ | POST | 購買発注をキャンセル |
| 購買発注 | /api/order/po/{id}/receive/ | POST | 購買発注を受領 |
| 購買発注明細 | /api/order/po-line/ | GET | 購買発注明細一覧を取得 |
| 購買発注明細 | /api/order/po-line/{id}/ | GET | 購買発注明細詳細を取得 |
| 購買発注追加明細 | /api/order/po-extra-line/ | GET | 購買発注追加明細一覧を取得 |
| 販売注文 | /api/order/so/ | GET | 販売注文一覧を取得 |
| 販売注文 | /api/order/so/{id}/ | GET | 販売注文詳細を取得 |
| 販売注文 | /api/order/so/ | POST | 販売注文を作成 |
| 販売注文 | /api/order/so/{id}/ | PATCH | 販売注文を更新 |
| 販売注文 | /api/order/so/{id}/issue/ | POST | 販売注文を発行 |
| 販売注文 | /api/order/so/{id}/cancel/ | POST | 販売注文をキャンセル |
| 販売注文 | /api/order/so/{id}/allocate/ | POST | 在庫を販売注文に割当 |
| 販売注文明細 | /api/order/so-line/ | GET | 販売注文明細一覧を取得 |
| 販売注文明細 | /api/order/so-line/{id}/ | GET | 販売注文明細詳細を取得 |
| 販売注文追加明細 | /api/order/so-extra-line/ | GET | 販売注文追加明細一覧を取得 |
| 販売注文出荷 | /api/order/so/shipment/ | GET | 出荷一覧を取得 |
| 販売注文出荷 | /api/order/so/shipment/{id}/ | GET | 出荷詳細を取得 |
| 販売注文出荷 | /api/order/so/shipment/{id}/ship/ | POST | 出荷を実行 |
| 販売注文割当 | /api/order/so-allocation/ | GET | 割当一覧を取得 |
| バーコード | /api/barcode/ | POST | バーコードをスキャン |
| バーコード | /api/barcode/link/ | POST | バーコードをリンク |
| バーコード | /api/barcode/unlink/ | POST | バーコードのリンクを解除 |
| 添付ファイル | /api/attachment/ | GET | 添付ファイル一覧を取得 |
| 添付ファイル | /api/attachment/ | POST | 添付ファイルをアップロード |
| 添付ファイル | /api/attachment/{id}/ | DELETE | 添付ファイルを削除 |
| 通知 | /api/notifications/ | GET | 通知一覧を取得 |
| 通知 | /api/notifications/{id}/ | PATCH | 通知を既読にする |
| 設定 | /api/settings/global/ | GET | グローバル設定を取得 |
| 設定 | /api/settings/user/ | GET | ユーザー設定を取得 |
| プラグイン | /api/plugins/ | GET | プラグイン一覧を取得 |
| ラベル印刷 | /api/label/print/ | POST | ラベルを印刷 |
| ステータス | /api/stock/status/ | GET | 在庫ステータス一覧を取得 |
| ステータス | /api/stock/track/status/ | GET | 在庫履歴ステータス一覧を取得 |
| ステータス | /api/order/po/status/ | GET | 購買発注ステータス一覧を取得 |
| ステータス | /api/order/so/status/ | GET | 販売注文ステータス一覧を取得 |
| ロケート | /api/locate/ | POST | アイテムまたはロケーションを特定 |

## 各APIエンドポイント定義

### 認証

#### 1. トークン取得

認証トークンを取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/user/token/` |
| 認証 | Basic認証（ユーザー名:パスワード） |
| 権限 | 不要 |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | トークン名（デバイス識別用） |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "token": "xxxxxxxxxxxxxxxxxxxx"
}
```

#### 2. ユーザー情報取得

現在の認証ユーザー情報を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/user/me/` |
| 認証 | 必要 |
| 権限 | 不要 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "pk": 1,
  "username": "admin"
}
```

#### 3. ユーザーロール取得

ユーザーのロールと権限を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/user/roles/` |
| 認証 | 必要 |
| 権限 | 不要 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "roles": {
    "part": ["view", "add", "change", "delete"],
    "stock": ["view", "add", "change", "delete"],
    "purchase_order": ["view", "add", "change", "delete"],
    "sales_order": ["view", "add", "change", "delete"]
  },
  "permissions": {
    "company": ["view", "add", "change", "delete"]
  }
}
```

---

### 部品

#### 4. 部品一覧取得

部品の一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/part/` |
| 認証 | 必要 |
| 権限 | part.view |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| category_detail | boolean | - | false | カテゴリ詳細を含める |
| search | string | - | - | 検索文字列 |
| category | integer | - | - | カテゴリIDでフィルタ |
| active | boolean | - | - | アクティブ状態でフィルタ |
| assembly | boolean | - | - | 組立品でフィルタ |
| component | boolean | - | - | コンポーネントでフィルタ |
| purchaseable | boolean | - | - | 購入可能でフィルタ |
| salable | boolean | - | - | 販売可能でフィルタ |
| trackable | boolean | - | - | 追跡可能でフィルタ |
| limit | integer | - | - | 取得件数上限 |
| offset | integer | - | 0 | 取得開始位置 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "count": 100,
  "results": [
    {
      "pk": 1,
      "name": "Resistor 10k",
      "description": "10k Ohm Resistor",
      "IPN": "RES-10K",
      "revision": "A",
      "category": 5,
      "category_detail": {
        "pk": 5,
        "name": "Resistors",
        "description": "Resistor components",
        "pathstring": "Electronics/Passive/Resistors"
      },
      "image": "/media/part_images/resistor.png",
      "thumbnail": "/media/part_images/resistor.thumbnail.png",
      "active": true,
      "assembly": false,
      "component": true,
      "purchaseable": true,
      "salable": false,
      "trackable": false,
      "virtual": false,
      "is_template": false,
      "units": "pcs",
      "in_stock": 1000,
      "total_in_stock": 1000,
      "unallocated_stock": 950,
      "ordering": 100,
      "building": 0,
      "suppliers": 3,
      "starred": false
    }
  ]
}
```

#### 5. 部品詳細取得

特定の部品の詳細を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/part/{id}/` |
| 認証 | 必要 |
| 権限 | part.view |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 部品ID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "pk": 1,
  "name": "Resistor 10k",
  "description": "10k Ohm Resistor",
  "IPN": "RES-10K",
  "revision": "A",
  "full_name": "RES-10K | Resistor 10k | A",
  "category": 5,
  "default_location": 10,
  "image": "/media/part_images/resistor.png",
  "thumbnail": "/media/part_images/resistor.thumbnail.png",
  "active": true,
  "assembly": false,
  "component": true,
  "purchaseable": true,
  "salable": false,
  "trackable": false,
  "testable": false,
  "virtual": false,
  "is_template": false,
  "units": "pcs",
  "keywords": "resistor passive",
  "link": "https://example.com/datasheet.pdf",
  "notes": "Standard resistor",
  "in_stock": 1000,
  "total_in_stock": 1000,
  "unallocated_stock": 950,
  "ordering": 100,
  "building": 0,
  "suppliers": 3,
  "used_in": 5,
  "starred": false,
  "variant_of": null,
  "barcode_hash": ""
}
```

#### 6. 部品更新

部品情報を更新します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `PATCH /api/part/{id}/` |
| 認証 | 必要 |
| 権限 | part.change |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 部品ID |

**リクエストボディ**

```json
{
  "name": "Resistor 10k",
  "description": "10k Ohm Resistor",
  "IPN": "RES-10K",
  "revision": "A",
  "category": 5,
  "default_location": 10,
  "active": true,
  "assembly": false,
  "component": true,
  "purchaseable": true,
  "salable": false,
  "trackable": false,
  "is_template": false,
  "virtual": false,
  "units": "pcs",
  "keywords": "resistor passive",
  "link": "https://example.com/datasheet.pdf"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | max:100 | 部品名 |
| description | string | - | max:250 | 説明 |
| IPN | string | - | max:100 | 内部部品番号 |
| revision | string | - | max:100 | リビジョン |
| category | integer | - | - | カテゴリID |
| default_location | integer | - | - | デフォルトロケーションID |
| active | boolean | - | - | アクティブフラグ |
| assembly | boolean | - | - | 組立品フラグ |
| component | boolean | - | - | コンポーネントフラグ |
| purchaseable | boolean | - | - | 購入可能フラグ |
| salable | boolean | - | - | 販売可能フラグ |
| trackable | boolean | - | - | 追跡可能フラグ |
| is_template | boolean | - | - | テンプレートフラグ |
| virtual | boolean | - | - | 仮想部品フラグ |
| units | string | - | max:20 | 単位 |
| keywords | string | - | - | キーワード |
| link | string | - | - | 外部リンク |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "pk": 1,
  "name": "Resistor 10k",
  ...
}
```

#### 7. 部品価格情報取得

部品の価格情報を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/part/{id}/pricing/` |
| 認証 | 必要 |
| 権限 | part.view |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 部品ID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "currency": "USD",
  "overall_min": 0.01,
  "overall_max": 0.05,
  "override_min": null,
  "override_max": null,
  "bom_cost_min": null,
  "bom_cost_max": null,
  "purchase_cost_min": 0.01,
  "purchase_cost_max": 0.02,
  "internal_cost_min": null,
  "internal_cost_max": null,
  "supplier_price_min": 0.01,
  "supplier_price_max": 0.05,
  "variant_cost_min": null,
  "variant_cost_max": null,
  "sale_price_min": null,
  "sale_price_max": null,
  "sale_history_min": null,
  "sale_history_max": null
}
```

#### 8. 部品要件情報取得

部品の要件情報を取得します（API v350以上）。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/part/{id}/requirements/` |
| 認証 | 必要 |
| 権限 | part.view |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 部品ID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "can_build": 100.0,
  "ordering": 50.0,
  "building": 10.0,
  "scheduled_to_build": 20.0,
  "required_for_build_orders": 30.0,
  "allocated_to_build_orders": 25.0,
  "required_for_sales_orders": 15.0,
  "allocated_to_sales_orders": 10.0
}
```

---

### 在庫

#### 9. 在庫アイテム一覧取得

在庫アイテムの一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/stock/` |
| 認証 | 必要 |
| 権限 | stock.view |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| part_detail | boolean | - | false | 部品詳細を含める |
| location_detail | boolean | - | false | ロケーション詳細を含める |
| supplier_detail | boolean | - | false | サプライヤー詳細を含める |
| supplier_part_detail | boolean | - | false | サプライヤー部品詳細を含める |
| cascade | boolean | - | false | サブロケーションを含める |
| part | integer | - | - | 部品IDでフィルタ |
| location | integer | - | - | ロケーションIDでフィルタ |
| in_stock | boolean | - | - | 在庫ありでフィルタ |
| search | string | - | - | 検索文字列 |
| limit | integer | - | - | 取得件数上限 |
| offset | integer | - | 0 | 取得開始位置 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "count": 50,
  "results": [
    {
      "pk": 1,
      "part": 1,
      "part_detail": {
        "pk": 1,
        "name": "Resistor 10k",
        "description": "10k Ohm Resistor",
        "thumbnail": "/media/part_images/resistor.thumbnail.png"
      },
      "location": 10,
      "location_detail": {
        "pk": 10,
        "name": "Bin A1",
        "pathstring": "Warehouse/Shelf 1/Bin A1"
      },
      "quantity": 100,
      "allocated": 10,
      "serial": "",
      "batch": "2024-01",
      "status": 10,
      "status_text": "OK",
      "purchase_price": "0.01",
      "purchase_price_currency": "USD",
      "packaging": "Tape",
      "link": "",
      "purchase_order": null,
      "supplier_part": 1,
      "in_stock": true,
      "is_building": false,
      "expiry_date": null,
      "stocktake_date": "2024-01-15",
      "updated": "2024-01-20T10:00:00Z",
      "tracking_items": 0,
      "barcode_hash": "",
      "stale": false,
      "expired": false
    }
  ]
}
```

#### 10. 在庫移動

在庫アイテムを別のロケーションに移動します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/stock/transfer/` |
| 認証 | 必要 |
| 権限 | stock.change |

**リクエストボディ**

```json
{
  "items": [
    {
      "pk": 1,
      "quantity": 50,
      "status": 10,
      "packaging": "Tape"
    }
  ],
  "location": 20,
  "notes": "Transfer to new location"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| items | array | ○ | - | 移動するアイテムのリスト |
| items[].pk | integer | ○ | - | 在庫アイテムID |
| items[].quantity | number | ○ | > 0 | 移動数量 |
| items[].status | integer | - | - | ステータスコード（API v133以上） |
| items[].packaging | string | - | - | パッケージング（API v133以上） |
| location | integer | ○ | - | 移動先ロケーションID |
| notes | string | - | - | メモ |

**レスポンス（成功時）**

ステータスコード: `200 OK` / `201 Created`

```json
{
  "success": "Stock items transferred"
}
```

#### 11. 在庫棚卸

在庫数量を確定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/stock/count/` |
| 認証 | 必要 |
| 権限 | stock.change |

**リクエストボディ**

```json
{
  "items": [
    {
      "pk": 1,
      "quantity": 100
    }
  ],
  "notes": "Monthly stocktake"
}
```

**レスポンス（成功時）**

ステータスコード: `200 OK` / `201 Created`

```json
{
  "success": "Stock counted"
}
```

#### 12. 在庫追加

在庫数量を追加します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/stock/add/` |
| 認証 | 必要 |
| 権限 | stock.change |

**リクエストボディ**

```json
{
  "items": [
    {
      "pk": 1,
      "quantity": 50
    }
  ],
  "notes": "Received additional stock"
}
```

**レスポンス（成功時）**

ステータスコード: `200 OK` / `201 Created`

```json
{
  "success": "Stock added"
}
```

#### 13. 在庫削減

在庫数量を削減します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/stock/remove/` |
| 認証 | 必要 |
| 権限 | stock.change |

**リクエストボディ**

```json
{
  "items": [
    {
      "pk": 1,
      "quantity": 10
    }
  ],
  "notes": "Consumed in production"
}
```

**レスポンス（成功時）**

ステータスコード: `200 OK` / `201 Created`

```json
{
  "success": "Stock removed"
}
```

---

### 購買発注

#### 14. 購買発注一覧取得

購買発注の一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/order/po/` |
| 認証 | 必要 |
| 権限 | purchase_order.view |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| supplier_detail | boolean | - | false | サプライヤー詳細を含める |
| supplier | integer | - | - | サプライヤーIDでフィルタ |
| outstanding | boolean | - | - | 未完了でフィルタ |
| search | string | - | - | 検索文字列 |
| limit | integer | - | - | 取得件数上限 |
| offset | integer | - | 0 | 取得開始位置 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "count": 10,
  "results": [
    {
      "pk": 1,
      "reference": "PO-0001",
      "description": "Monthly order",
      "supplier": 1,
      "supplier_detail": {
        "pk": 1,
        "name": "Supplier A",
        "image": "/media/company/supplier_a.png"
      },
      "supplier_reference": "SUP-REF-001",
      "status": 10,
      "status_text": "Pending",
      "creation_date": "2024-01-01",
      "target_date": "2024-01-15",
      "issue_date": null,
      "complete_date": null,
      "line_items": 5,
      "completed_lines": 0,
      "overdue": false,
      "total_price": "500.00",
      "order_currency": "USD",
      "responsible": 1,
      "project_code": 1,
      "destination": 10
    }
  ]
}
```

#### 15. 購買発注発行

購買発注を発行（Placed）状態にします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/order/po/{id}/issue/` |
| 認証 | 必要 |
| 権限 | purchase_order.change |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 購買発注ID |

**レスポンス（成功時）**

ステータスコード: `201 Created`

```json
{
  "pk": 1,
  "status": 20,
  "status_text": "Placed"
}
```

#### 16. 購買発注受領

購買発注の明細を受領します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/order/po/{id}/receive/` |
| 認証 | 必要 |
| 権限 | purchase_order.change, stock.add |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 購買発注ID |

**リクエストボディ**

```json
{
  "items": [
    {
      "line_item": 1,
      "quantity": 100,
      "status": 10,
      "batch_code": "2024-01",
      "barcode": ""
    }
  ],
  "location": 10
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| items | array | ○ | - | 受領するアイテムのリスト |
| items[].line_item | integer | ○ | - | 明細ID |
| items[].quantity | number | ○ | > 0 | 受領数量 |
| items[].status | integer | - | - | ステータスコード |
| items[].batch_code | string | - | - | バッチコード |
| items[].barcode | string | - | - | バーコード |
| location | integer | ○ | - | 受領先ロケーションID |

**レスポンス（成功時）**

ステータスコード: `201 Created`

---

### 販売注文

#### 17. 販売注文一覧取得

販売注文の一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/order/so/` |
| 認証 | 必要 |
| 権限 | sales_order.view |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| customer_detail | boolean | - | false | 顧客詳細を含める |
| customer | integer | - | - | 顧客IDでフィルタ |
| outstanding | boolean | - | - | 未完了でフィルタ |
| search | string | - | - | 検索文字列 |
| limit | integer | - | - | 取得件数上限 |
| offset | integer | - | 0 | 取得開始位置 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "count": 5,
  "results": [
    {
      "pk": 1,
      "reference": "SO-0001",
      "description": "Customer order",
      "customer": 2,
      "customer_detail": {
        "pk": 2,
        "name": "Customer B",
        "image": "/media/company/customer_b.png"
      },
      "customer_reference": "CUST-REF-001",
      "status": 10,
      "status_text": "Pending",
      "creation_date": "2024-01-01",
      "target_date": "2024-01-20",
      "shipment_date": null,
      "line_items": 3,
      "completed_lines": 0,
      "shipments_count": 1,
      "completed_shipments_count": 0,
      "overdue": false,
      "total_price": "1000.00",
      "order_currency": "USD",
      "responsible": 1,
      "project_code": 1
    }
  ]
}
```

#### 18. 販売注文への在庫割当

販売注文の明細に在庫を割り当てます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/order/so/{id}/allocate/` |
| 認証 | 必要 |
| 権限 | sales_order.change |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 販売注文ID |

**リクエストボディ**

```json
{
  "items": [
    {
      "line_item": 1,
      "stock_item": 5,
      "quantity": 10
    }
  ],
  "shipment": 1
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| items | array | ○ | - | 割当するアイテムのリスト |
| items[].line_item | integer | ○ | - | 明細ID |
| items[].stock_item | integer | ○ | - | 在庫アイテムID |
| items[].quantity | number | ○ | > 0 | 割当数量 |
| shipment | integer | ○ | - | 出荷ID |

**レスポンス（成功時）**

ステータスコード: `201 Created`

---

### バーコード

#### 19. バーコードスキャン

バーコードをスキャンしてアイテムを特定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/barcode/` |
| 認証 | 必要 |
| 権限 | 不要 |

**リクエストボディ**

```json
{
  "barcode": "INV-12345"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| barcode | string | ○ | - | バーコードデータ |

**レスポンス（成功時 - マッチあり）**

ステータスコード: `200 OK`

```json
{
  "success": "Barcode matches item",
  "stockitem": {
    "pk": 1
  },
  "barcode_hash": "abc123",
  "barcode_data": "INV-12345"
}
```

**レスポンス（成功時 - マッチなし）**

ステータスコード: `200 OK`

```json
{
  "error": "No match found for barcode",
  "barcode_hash": "abc123",
  "barcode_data": "INV-12345"
}
```

#### 20. バーコードリンク

バーコードをアイテムにリンクします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/barcode/link/` |
| 認証 | 必要 |
| 権限 | 対象モデルのchange権限 |

**リクエストボディ**

```json
{
  "stockitem": "1",
  "barcode": "CUSTOM-BARCODE-123"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| stockitem | string | - | - | 在庫アイテムID |
| part | string | - | - | 部品ID |
| stocklocation | string | - | - | ロケーションID |
| barcode | string | ○ | - | リンクするバーコード |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "success": "Barcode linked"
}
```

#### 21. バーコードリンク解除

アイテムからバーコードのリンクを解除します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/barcode/unlink/` |
| 認証 | 必要 |
| 権限 | 対象モデルのchange権限 |

**リクエストボディ**

```json
{
  "stockitem": 1
}
```

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "success": "Barcode unlinked"
}
```

---

### 添付ファイル

#### 22. 添付ファイルアップロード

ファイルをアップロードします（API v207以上で統合API）。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/attachment/` |
| 認証 | 必要 |
| 権限 | 対象モデルのadd権限 |

**リクエストボディ（multipart/form-data）**

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| attachment | file | ○ | - | アップロードファイル |
| model_type | string | ○ | - | モデルタイプ |
| model_id | integer | ○ | - | モデルID |
| comment | string | - | - | コメント |

**レスポンス（成功時）**

ステータスコード: `201 Created`

```json
{
  "pk": 1,
  "attachment": "/media/attachments/file.pdf",
  "model_type": "part",
  "model_id": 1,
  "comment": "Datasheet",
  "upload_date": "2024-01-15T10:00:00Z"
}
```

---

### 通知

#### 23. 通知一覧取得

通知の一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/notifications/` |
| 認証 | 必要 |
| 権限 | 不要 |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| read | boolean | - | - | 既読/未読でフィルタ |
| limit | integer | - | - | 取得件数上限 |
| offset | integer | - | 0 | 取得開始位置 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "count": 5,
  "results": [
    {
      "pk": 1,
      "message": "Stock item received",
      "creation": "2024-01-15T10:00:00Z",
      "read": false
    }
  ]
}
```

#### 24. 通知既読化

通知を既読状態にします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `PATCH /api/notifications/{id}/` |
| 認証 | 必要 |
| 権限 | 不要 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | 通知ID |

**リクエストボディ**

```json
{
  "read": true
}
```

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### ラベル印刷

#### 25. ラベル印刷

ラベルを印刷します（API v201以上）。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/label/print/` |
| 認証 | 必要 |
| 権限 | 不要 |

**リクエストボディ**

```json
{
  "template": 1,
  "plugin": "inventree-label-printer",
  "items": [1, 2, 3]
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| template | integer | ○ | - | テンプレートID |
| plugin | string | ○ | - | プラグインキー |
| items | array | ○ | - | 印刷対象アイテムIDのリスト |

**レスポンス（成功時）**

ステータスコード: `201 Created`

```json
{
  "pk": 1,
  "complete": false,
  "output": null,
  "errors": null
}
```

---

### アイテムロケート

#### 26. アイテム/ロケーションのロケート

プラグインを使用してアイテムまたはロケーションを特定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/locate/` |
| 認証 | 必要 |
| 権限 | 不要 |

**リクエストボディ**

```json
{
  "plugin": "inventree-locate-plugin",
  "item": 1,
  "location": null
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| plugin | string | ○ | - | プラグインキー |
| item | integer | - | - | 在庫アイテムID |
| location | integer | - | - | ロケーションID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "success": "Locate request sent"
}
```

## 備考

### APIバージョン互換性

このアプリケーションは最小APIバージョン100以上のInvenTreeサーバーが必要です。以下の機能はAPIバージョンによって利用可否が異なります:

| 機能 | 必要APIバージョン |
| --- | --- |
| 統合検索 | 102以上 |
| 返品注文 | 104以上 |
| ステータスラベルAPI | 105以上 |
| 注文バーコード | 107以上 |
| プロジェクトコード | 109以上 |
| 在庫調整追加フィールド | 133以上 |
| バーコードPO受領 | 139以上 |
| バーコードPO明細追加 | 153以上 |
| バーコードSO割当 | 160以上 |
| モダンテスト結果API | 169以上 |
| 会社アクティブステータス | 189以上 |
| モダンラベル印刷API | 201以上 |
| モダン添付ファイルAPI | 207以上 |
| ユーザー権限API | 207以上 |
| PO配送先 | 276以上 |
| 注文開始日 | 306以上 |
| 分割会社検索 | 315以上 |
| 部品要件API | 350以上 |
| モダンパラメータAPI | 429以上 |

### エラーハンドリング

アプリケーションは以下のエラーパターンを処理します:

1. **ネットワークエラー**: SocketException、TimeoutException
2. **証明書エラー**: CertificateException、HandshakeException
3. **認証エラー**: 401/403レスポンス
4. **サーバーエラー**: 500系レスポンス
5. **バリデーションエラー**: 400レスポンス（フィールドエラー含む）

### セキュリティ

- HTTPS通信を推奨（HTTPは自動的にHTTPSへアップグレード）
- 自己署名証明書のオプション許可（設定可能）
- トークンはローカルデータベースに保存
