# API máy gia công

Liệt kê, tạo, cập nhật, xóa và tìm kiếm máy gia công. Lấy ổ dao hiện tại của một máy.

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

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

## Endpoint

| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
| `GET` | `/machines` | Liệt kê mọi máy |
| `GET` | `/machines/:id` | Lấy một máy |
| `POST` | `/machines` | Tạo máy |
| `PATCH` | `/machines/:id` | Cập nhật máy |
| `DELETE` | `/machines/:id` | Xóa máy |
| `GET` | `/machines/search` | Tìm theo ký hiệu |
| `GET` | `/machines/:id/tool_crib` | Lấy các dụng cụ đang có tại máy |

## Đối tượng máy gia công

```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
    }
  ]
}
```

## Tham số

### Tạo / cập nhật

| Tham số | Kiểu | Mô tả |
|---|---|---|
| `name` | string | Tên hiển thị |
| `designation` | string | Mã máy. **Luôn truyền tường minh trường này.** |
| `builder` | string | Tên hãng chế tạo |
| `model` | string | Kiểu máy |
| `serial_number` | string | Số sê-ri |
| `hour_rate` | decimal | Chi phí mỗi giờ máy chạy |
| `target_oee` | decimal | OEE mục tiêu (0–100) |
| `warehouse_access_point_id` | integer | WAP mà máy thuộc về. Nếu bỏ trống, mặc định là WAP đầu tiên của tổ chức. |
| `organization_id` | integer | **Bắt buộc có trong thân yêu cầu khi tạo**, không chỉ trong URL. Đoạn đường dẫn `:organization_id` dùng để phân quyền cho yêu cầu nhưng tự nó không gắn máy mới vào tổ chức đó — hãy truyền lại trong thân yêu cầu. |
| `user_id` | integer | Gắn bản ghi với một người dùng cụ thể để giới hạn phạm vi theo vai trò (xem [Xác thực](https://support.toolingmetrics.com/vi/api/authentication/)). Để trống trừ khi bạn biết mình cần. |

Giống [chi tiết](https://support.toolingmetrics.com/vi/api/reference/parts/), máy gia công tự sinh `designation` theo chuỗi đánh số của tổ chức khi để trống — `number` là bí danh của `designation` trên model Machine, nên cách xử lý `designation` trống áp dụng cho chi tiết cũng dùng được ở đây.

### Tìm kiếm

| Tham số | Kiểu | Mô tả |
|---|---|---|
| `designation` | string | Khớp chính xác theo ký hiệu máy |

## Ví dụ

```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}%")
```

## Ổ tích dao

`GET /machines/:id/tool_crib` trả về các dụng cụ đang nằm tại máy, nhóm theo ID mô hình dụng cụ. Mỗi mục chỉ giữ lại một tập trường cố định — lưu ý **`id` không nằm trong số đó**:

```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
    }
  ]
}
```

Các khóa là ID mô hình dụng cụ (số nguyên ở dạng chuỗi). Mỗi giá trị là một mảng bản ghi dụng cụ, sắp xếp giảm dần theo `remain_life_percentage` của cạnh cắt giới hạn. Dụng cụ có cạnh cắt không đặt giới hạn tuổi thọ được liệt kê sau cùng.

| Trường | Mô tả |
|---|---|
| `number` | Mã dụng cụ được gán tại trạm lắp ráp |
| `name` | Tên dụng cụ |
| `status` | Trạng thái hiện tại |
| `completed` | Dụng cụ đã lắp đủ mọi thành phần hay chưa |
| `weight` | Khối lượng dụng cụ |
| `usage_at` | Mốc thời gian của lần ghi nhận sử dụng gần nhất |
| `cutting_edges` | Mọi cạnh cắt cùng vị trí cạnh hiện tại, tình trạng, mức đã dùng, giới hạn tuổi thọ, đơn vị tuổi thọ, phần trăm tuổi thọ còn lại, trạng thái lắp đủ, số lượng và dữ liệu CRP |
| `component_id` | Bộ phận máy (đầu trục chính/đài dao/dàn dao, lấy từ `components` trong đối tượng máy) mà dụng cụ được nạp vào. **Chỉ có khi dụng cụ đã được gán vị trí dao** — dụng cụ đã ở tại máy nhưng chưa được đưa vào bộ phận nào sẽ không có trường này và cả `slot_number` |
| `slot_number` | Số vị trí dao trong bộ phận đó (vị trí trên đài dao máy tiện, hoặc vị trí trong ổ dao) |

**`slot_number` không được kiểm tra với định nghĩa vị trí dao của chính bộ phận máy.** Bộ phận máy định nghĩa riêng các vị trí dao thực tế dưới dạng bản ghi vị trí dao (Machine Tool Location), mỗi bản ghi có `slot_number` riêng, duy nhất trong bộ phận — đó là ý nghĩa của mảng `components` trong đối tượng máy gia công ở trên. `slot_number` trả về ở đây lấy từ một bảng chiếm chỗ thứ hai, độc lập (`tool_crib`), chỉ được giữ khớp với các định nghĩa vị trí dao theo quy ước — hai số nguyên trùng nhau, không phải khóa ngoại. Đừng giả định `slot_number` của một mục `tool_crib` nhất định ứng với một vị trí dao đang được định nghĩa trên bộ phận đó; hãy coi nó là "số được ghi lại khi dụng cụ được đưa vào vị trí lần gần nhất", không phải một tham chiếu đã kiểm tra.