# API mô hình dụng cụ

Liệt kê và lấy các mô hình dụng cụ. Xuất toàn bộ thư viện thành gói Fusion 360.

Source: https://support.toolingmetrics.com/vi/api/reference/tool-assemblies/
Updated: 2026-10-29

Đường dẫn gốc: `/v1/organizations/:organization_id/tool_assemblies`

## Endpoint

| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
| `GET` | `/tool_assemblies` | Liệt kê các mô hình dụng cụ đã sẵn sàng để xuất |
| `GET` | `/tool_assemblies/:id` | Lấy một mô hình dụng cụ |
| `GET` | `/tool_library/:vendor` | Xuất thư viện thành gói cho phần mềm được chỉ định |

Mô hình dụng cụ là tài nguyên chỉ đọc qua API — không có route `POST`, `PATCH` hay `DELETE` cho tài nguyên này. Tạo và quản lý mô hình dụng cụ trong ứng dụng, tại **Thư viện → Mô hình dụng cụ**.

## Đối tượng mô hình dụng cụ

```json
{
  "id": 42,
  "name": "Face Mill Ø80 — ADKT",
  "designation": "TA-042",
  "status": "released",
  "created_at": "2025-01-10T08:00:00Z",
  "updated_at": "2025-06-01T10:00:00Z",
  "category": { "id": 3, "name": "Face Mills", "code": "FM" },
  "created_by": { "id": 7, "email": "user@example.com", "firstname": "Long", "lastname": "Han" },
  "cutting_data": [
    {
      "id": "b1e1f7a0-1c2d-4e3f-9a8b-7c6d5e4f3a2b",
      "material_id": 2,
      "name": "42CrMo4 — Face milling",
      "operation": "milling_face",
      "parameters": { "cutting_speed": 180, "feed_per_tooth": 0.12 },
      "unit_system": "metric",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-10T08:00:00Z"
    }
  ]
}
```

Lưu ý trường dùng để nhận diện là `designation`, không phải `number`. `cutting_data[].parameters` là một đối tượng JSON tự do — các khóa của nó phụ thuộc vào `operation` và không được schema cố định; hãy coi nó là một tập thông số cắt không cố định cấu trúc, đừng xem là một hợp đồng ổn định.

## Cách lọc danh sách

`GET /tool_assemblies` chỉ trả về những mô hình dụng cụ:

- Có `status` nằm trong các trạng thái "có thể xuất thư viện dụng cụ" mà tổ chức đã cấu hình — nhóm ô chọn **Thư viện mô hình dụng cụ trung tâm** (Nháp/Đã phát hành/Đang sử dụng/Chờ lưu trữ/Đã lưu trữ) trong **Trung tâm quản trị → Tổ chức → Tùy chọn**, là một tùy chọn cấp tổ chức (`organizations.preferences["engineering"]["tool_library_exportable"]`), không phải một danh sách trạng thái cố định. Đây là một tiêu chí tách biệt với `status` trong quy trình phát hành của mô hình dụng cụ — tổ chức tự quyết định thế nào là "dùng được cho CAM", không phụ thuộc vào việc máy trạng thái gọi gì là "released"
- Có `assets_builded: true` (các tệp 3D/STEP đã xử lý xong)

Một mô hình dụng cụ đã có và hiển thị trong giao diện ứng dụng có thể chưa xuất hiện ở đây nếu chưa thỏa một trong hai điều kiện trên.

Khác với endpoint danh sách, `GET /tool_assemblies/:id` không có bộ lọc này — nó trả về bất kỳ mô hình dụng cụ nào của tổ chức theo ID, trong giới hạn phạm vi phân quyền thông thường (xem [Xác thực](https://support.toolingmetrics.com/vi/api/authentication/)).

## Xuất thư viện

```
GET /v1/organizations/:organization_id/tool_library/:vendor
```

Hiện `:vendor` chỉ được hỗ trợ với giá trị `fusion` (định dạng JSON thư viện dụng cụ của Autodesk Fusion 360, dựng từ cùng bộ lọc trạng thái/tệp như endpoint danh sách). Mọi giá trị vendor khác đều trả về `200 OK` với thân `null` thay vì lỗi — hãy kiểm tra phản hồi rỗng/null thay vì trông vào mã lỗi. Để kết nối Autodesk Fusion, xem [ToolingMetrics CAM Connect cho Autodesk Fusion](https://support.toolingmetrics.com/vi/integrations/cam-connect/autodesk-fusion/).

## Ví dụ

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

# Get a specific tool assembly with cutting data
curl "https://api.toolingmetrics.com/v1/organizations/12/tool_assemblies/42" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Export the full library as a Fusion 360 package
curl "https://api.toolingmetrics.com/v1/organizations/12/tool_library/fusion" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o tool_library.json
```

```python
import requests
import json

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

# Fetch all exportable tool assemblies and index them by designation for lookup
assemblies = requests.get(
    f"{BASE}/organizations/12/tool_assemblies",
    headers=HEADERS,
).json()

by_designation = {a["designation"]: a for a in assemblies}
ta = by_designation.get("TA-042")
if ta:
    print(f"{ta['name']} — status: {ta['status']}")

# Download the Fusion 360 library package
fusion_pkg = requests.get(
    f"{BASE}/organizations/12/tool_library/fusion",
    headers=HEADERS,
).json()

if fusion_pkg:
    with open("tool_library.json", "w") as f:
        json.dump(fusion_pkg, f, indent=2)
    print("Fusion 360 library exported.")
else:
    print("Nothing exported — no exportable tool assemblies, or the vendor value isn't supported.")
```

## Lỗi thường gặp

| Mã trạng thái | Nguyên nhân |
|---|---|
| `401` | Không có quyền xem mô hình dụng cụ trong tổ chức này, hoặc không có tổ chức nào có mã này |
| `404` | `GET /tool_assemblies/:id`: tổ chức này không có mô hình dụng cụ nào có mã này. Thân phản hồi dùng khóa `error` số ít, như với chi tiết, dự án và máy gia công (xem [Lỗi](https://support.toolingmetrics.com/vi/api/errors/)) |
| `422` | Chỉ với Xuất thư viện: tệp xuất không dựng được dù đã bỏ các mô hình dụng cụ không dựng được (thông thường các mô hình đó chỉ bị bỏ khỏi thư viện và người dùng của chúng được thông báo); `errors` cho biết lý do |
| `500` | Chỉ với Xuất thư viện: tệp xuất thất bại ngoài dự kiến; `errors` chứa `"The tool library export failed"` |