API máy gia công

Đườ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

{
  "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). Để trống trừ khi bạn biết mình cần.

Giống chi tiết, 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ụ

# 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}'

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ố đó:

{
  "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.

Bài viết liên quan

• API tổ chức
• API mô hình dụng cụ
• API chi tiết
• API dự án