# プロジェクトAPI

ジョブと工程をネストした工程設計プロジェクトの一覧、作成、更新、削除、検索。

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

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

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

## エンドポイント

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/projects` | プロジェクト一覧（概要） |
| `GET` | `/projects/:id` | ジョブと工程を含むプロジェクトを取得 |
| `POST` | `/projects` | プロジェクトを作成 |
| `PATCH` | `/projects/:id` | プロジェクトを更新 |
| `DELETE` | `/projects/:id` | プロジェクトを削除 |
| `GET` | `/projects/search` | プロジェクトを名称で検索 |

<a id="project-object-detail"></a>

## プロジェクトオブジェクト（詳細）

```json
{
  "id": 8,
  "name": "Cylinder Block Rev2",
  "description": "...",
  "status": "released",
  "multiple_setup": false,
  "created_at": "2025-04-01T08:00:00Z",
  "updated_at": "2025-06-01T10:00:00Z",
  "created_by": { "id": 7, "email": "user@example.com" },
  "jobs": [
    {
      "id": 12,
      "name": "Op 10 — Facing",
      "order": 1,
      "status": "draft",
      "locked": false,
      "machine": { "id": 1, "designation": "DMG-001", "name": "DMG 5-axis" },
      "part": { "id": 5, "number": "P-0042", "description": "Cylinder Block" },
      "operations": [
        { "id": 20, "name": "Face milling" }
      ]
    }
  ]
}
```

<a id="list-response"></a>

## 一覧レスポンス

`GET /projects`の一覧は、完全なネスト構造ではなく簡潔な概要を返します。

```json
[
  { "id": 8, "name": "Cylinder Block Rev2", "status": "released", "locked": false },
  { "id": 9, "name": "Shaft Housing", "status": "draft", "locked": false }
]
```

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

## パラメータ

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

### 作成・更新

| パラメータ | 型 | 説明 |
|---|---|---|
| `name` | string | プロジェクト名 |
| `description` | string | プロジェクトの説明 |
| `status` | string | `draft`、`released`、`approved`、`active`、`archived`のいずれか。リリース済みのプロジェクトを承認すると、工具アセンブリのカタログ品をプロジェクトの作成者の在庫品目としてコピーするため、キーのユーザーにはその在庫品目を作成し、既存の在庫品目を更新する権限も必要です。ない場合は`401` |
| `multiple_setup` | boolean | 複数の機械段取りを使うか |
| `picture` | string | Base64エンコードしたPNG画像 |
| `jobs_attributes` | array | ネストしたジョブ。下記を参照。 |

[加工部品](https://support.toolingmetrics.com/ja/api/reference/parts/)や[機械](https://support.toolingmetrics.com/ja/api/reference/machines/)と異なり、プロジェクトの組織は`:organization_id`のパス要素から自動で設定されます。本文で再度指定する必要はありません（`organization_id`は受け付けるパラメータではないため、指定することもできません）。`jobs_attributes`内の各ジョブも同様です。

<a id="jobs-attributes"></a>

### ジョブの属性

| パラメータ | 型 | 説明 |
|---|---|---|
| `id` | integer | 既存ジョブの更新時に必須 |
| `name` | string | ジョブ名 |
| `order` | integer | 表示順 |
| `machine_id` | integer | 割り当てる機械 |
| `part_id` | integer | 加工部品 |
| `status` | string | ジョブの状態 |
| `_destroy` | boolean | ジョブを削除する場合は`true` |
| `operations_attributes` | array | ネストした工程。下記を参照。 |

<a id="operations-attributes"></a>

### 工程の属性

| パラメータ | 型 | 説明 |
|---|---|---|
| `id` | integer | 既存工程の更新時に必須 |
| `name` | string | 工程名 |
| `order` | integer | ジョブ内の表示順 |
| `cycle_time` | integer | 推定サイクルタイム。**整数である必要があります**。`numericality: only_integer: true`により、小数は`422`で拒否されます。 |
| `tool_number` | integer | NCプログラムの工具番号（T番号） |
| `tool_assembly_id` | integer | 割り当てる工具アセンブリ |
| `_destroy` | boolean | 工程を削除する場合は`true` |

<a id="list--search-filters"></a>

### 一覧・検索の絞り込み

| パラメータ | 型 | 説明 |
|---|---|---|
| `status` | string | 状態で絞り込みます（一覧エンドポイント）。**暗黙に`locked: false`でも絞り込みます**。`status`を指定すると、明示していなくてもロック済みのプロジェクトは除外されます。ロック済みのプロジェクトも含める必要がある場合は、`status`を省略してください。 |
| `q` | string | プロジェクト名の部分一致（大文字・小文字を区別しない、検索エンドポイント） |

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

## 使用例

```bash
# Search projects by name
curl "https://api.toolingmetrics.com/v1/organizations/12/projects/search?q=Cylinder" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get a project with full job and operation detail
curl "https://api.toolingmetrics.com/v1/organizations/12/projects/8" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```python
import requests

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

# Create a project with one job and one operation (CAM post-processor integration)
payload = {
    "name": "Cylinder Block Rev2",
    "status": "draft",
    "jobs_attributes": [
        {
            "name": "Op 10 — Facing",
            "order": 1,
            "machine_id": 1,
            "part_id": 5,
            "operations_attributes": [
                {
                    "name": "Face milling",
                    "order": 1,
                    "cycle_time": 750,
                    "tool_number": 1,
                    "tool_assembly_id": 42,
                }
            ],
        }
    ],
}

response = requests.post(
    f"{BASE}/organizations/12/projects",
    headers={**HEADERS, "Content-Type": "application/json"},
    json=payload,
)
response.raise_for_status()
project = response.json()
print(f"Created project #{project['id']}: {project['name']}")
```

<a id="common-errors"></a>

## よくあるエラー

| ステータス | 原因 |
|---|---|
| `401` | キーのユーザーにその変更の権限がない（例：承認で作成・更新される在庫品目を変更する権限なしに、リリース済みのプロジェクトを承認した） |
| `404` | プロジェクト、機械、加工部品のIDが見つからない |
| `422` | 必須項目の未指定、無効な`status`の値 |