# 機械API

機械の一覧、作成、更新、削除、検索と、機械の現在の工具収納部の取得。

Source: https://support.toolingmetrics.com/ja/api/reference/machines/
Updated: 2026-10-29

ベースパス：`/v1/organizations/:organization_id/machines`

<a id="endpoints"></a>

## エンドポイント

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/machines` | すべての機械の一覧 |
| `GET` | `/machines/:id` | 機械を取得 |
| `POST` | `/machines` | 機械を作成 |
| `PATCH` | `/machines/:id` | 機械を更新 |
| `DELETE` | `/machines/:id` | 機械を削除 |
| `GET` | `/machines/search` | 呼称で検索 |
| `GET` | `/machines/:id/tool_crib` | 現在機械にあるセット工具を取得 |

<a id="machine-object"></a>

## 機械オブジェクト

```json
{
  "id": 1,
  "name": "DMG 5-axis",
  "designation": "DMG-001",
  "builder": "DMG Mori",
  "model": "DMU 50",
  "serial_number": "SN123456",
  "hour_rate": 120.0,
  "target_oee": 85,
  "created_at": "2025-01-15T08:00:00Z",
  "updated_at": "2025-06-01T10:00:00Z",
  "warehouse_access_point": { "id": 3, "name": "CNC Area" },
  "created_by": { "id": 7, "email": "user@example.com" },
  "components": [
    {
      "id": 44,
      "component_type": "spindle",
      "name": "Main Spindle",
      "interfaces": [{ "code": "HSK01C0630****" }],
      "data": {},
      "tool_crib": false
    }
  ]
}
```

<a id="parameters"></a>

## パラメータ

<a id="create--update"></a>

### 作成・更新

| パラメータ | 型 | 説明 |
|---|---|---|
| `name` | string | 表示名 |
| `designation` | string | 機械の呼称（機械コード）。**必ず明示的に指定してください。** |
| `builder` | string | 機械メーカー名 |
| `model` | string | 機械モデル |
| `serial_number` | string | シリアル番号 |
| `hour_rate` | decimal | 稼働1時間当たりの原価 |
| `target_oee` | decimal | 目標OEE（0–100） |
| `warehouse_access_point_id` | integer | 機械が属するWAP。省略すると組織内の最初のWAPを使います。 |
| `organization_id` | integer | URLだけでなく、**作成時は本文にも必須**です。`:organization_id`のパス要素は権限を確認しますが、それだけで機械を組織に関連付けるわけではありません。本文でも指定してください。 |
| `user_id` | integer | 権限によるアクセス範囲のため、特定のユーザーに関連付けます。[認証](https://support.toolingmetrics.com/ja/api/authentication/)を参照してください。必要と分かっている場合以外は指定しません。 |

[加工部品](https://support.toolingmetrics.com/ja/api/reference/parts/)と同様に、機械も`designation`が空の場合は組織の採番設定から自動生成されます。Machineモデルでは`number`が`designation`の別名になっているため、加工部品で使える`designation`空欄時の処理がここでも同じように働きます。

<a id="search"></a>

### 検索

| パラメータ | 型 | 説明 |
|---|---|---|
| `designation` | string | 機械の呼称の完全一致 |

<a id="examples"></a>

## 使用例

```bash
# List all machines
curl "https://api.toolingmetrics.com/v1/organizations/12/machines" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Find a machine by designation
curl "https://api.toolingmetrics.com/v1/organizations/12/machines/search?designation=DMG-001" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get the live tool crib for a machine
curl "https://api.toolingmetrics.com/v1/organizations/12/machines/1/tool_crib" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create a machine — organization_id is required in the body, not just the URL
curl -X POST "https://api.toolingmetrics.com/v1/organizations/12/machines" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mazak 3-axis", "designation": "MAZ-002", "builder": "Mazak", "model": "VCN-430A", "organization_id": 12}'
```

```python
import requests

BASE = "https://api.toolingmetrics.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_TOKEN"}

# Check which tools are loaded at a machine before a setup
crib = requests.get(
    f"{BASE}/organizations/12/machines/1/tool_crib",
    headers=HEADERS,
).json()

for assembly_id, tools in crib.items():
    for tool in tools:
        remaining = [edge["remain_life_percentage"] for edge in tool["cutting_edges"] if edge["remain_life_percentage"] is not None]
        print(f"  T{tool['number']} — {tool['name']} — remaining {min(remaining) if remaining else 0}%")
```

<a id="tool-crib"></a>

## 工具収納部

`GET /machines/:id/tool_crib`は、現在機械に保管されているセット工具を、工具アセンブリIDごとにまとめて返します。各工具は固定の項目に絞られ、**`id`は含まれません**。

```json
{
  "42": [
    {
      "number": "T-001",
      "name": "Face Mill Ø80",
      "status": "active",
      "completed": true,
      "updated_at": "2025-06-01T08:00:00Z",
      "weight": 1.8,
      "usage_at": "2026-05-30T14:00:00Z",
      "cutting_edges": [
        {
          "id": 12,
          "item_id": 84,
          "condition": "used",
          "usage_life": 4.5,
          "life_limit": 20.0,
          "remain_life_percentage": 77.5,
          "completed": true
        }
      ],
      "component_id": 44,
      "slot_number": 3
    }
  ]
}
```

キーは工具アセンブリIDを文字列にしたものです。各値は、寿命を制限する切れ刃の`remain_life_percentage`が高い順に並ぶ工具配列です。切れ刃に寿命上限がない工具は最後になります。

| 項目 | 説明 |
|---|---|
| `number` | 組立ステーションで付与した工具番号 |
| `name` | 工具名 |
| `status` | 現在の状態 |
| `completed` | 構成部品がすべて揃っているか |
| `weight` | 工具の重量 |
| `usage_at` | 最後の使用記録の日時 |
| `cutting_edges` | すべての切れ刃と、その現在刃先番号、状態、使用時間、寿命上限、寿命の単位、残り寿命の割合、刃先構成の完了状態、数量、CRPデータ |
| `component_id` | 工具を配置した機械構成部品。機械オブジェクトの`components`にある主軸ヘッド、タレット、くし刃台のいずれかです。**工具位置を割り当てた場合のみ表示**します。実物は機械にあっても、まだ構成部品のスロットに割り当てられていない工具では、この項目と`slot_number`はどちらも省略されます。 |
| `slot_number` | 構成部品内の位置番号。旋盤のタレット位置やマガジンのスロット。 |

**`slot_number`は構成部品の工具位置定義に対して検証しません。** 機械構成部品は別途、工具位置レコードとして実物の位置を定義し、それぞれ構成部品内で一意な`slot_number`を持ちます。上記の機械オブジェクトの`components`配列がこの定義を表します。ここで返す`slot_number`は独立した配置表`tool_crib`から取得し、外部キーではなく番号を合わせる運用で位置定義と対応させます。現在存在する工具位置を参照していると決めつけず、「最後に配置した際に記録した番号」として扱ってください。