API dự án

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

Endpoint

Phương thức	Đường dẫn	Mô tả
GET	/projects	Liệt kê mọi dự án (dạng tóm tắt)
GET	/projects/:id	Lấy một dự án kèm nguyên công và bước gia công
POST	/projects	Tạo dự án
PATCH	/projects/:id	Cập nhật dự án
DELETE	/projects/:id	Xóa dự án
GET	/projects/search	Tìm dự án theo tên

Đối tượng dự án (dạng chi tiết)

{
  "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" }
      ]
    }
  ]
}

Phản hồi danh sách

Endpoint danh sách GET /projects trả về bản tóm tắt gọn — không phải cấu trúc lồng nhau đầy đủ:

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

Tham số

Tạo / cập nhật

Tham số	Kiểu	Mô tả
name	string	Tên dự án
description	string	Mô tả dự án
status	string	Một trong các giá trị draft, released, approved, active, archived. Phê duyệt một dự án đã phát hành sẽ sao chép các sản phẩm của mô hình dụng cụ thành hàng hóa do người tạo dự án tạo, nên người dùng của khóa cũng phải được phép tạo các hàng hóa đó và cập nhật các hàng hóa đã có; nếu không sẽ nhận 401
multiple_setup	boolean	Dự án có ghép nhiều lần gá trên máy hay không
picture	string	Ảnh dự án dạng PNG mã hóa Base64
jobs_attributes	array	Các nguyên công lồng bên trong (xem bên dưới)

Khác với chi tiết và máy gia công, dự án tự lấy tổ chức từ đoạn đường dẫn :organization_id — bạn không cần (và không thể, vì organization_id không phải tham số được chấp nhận) truyền lại trong thân yêu cầu. Điều này cũng áp dụng cho từng nguyên công trong jobs_attributes.

Thuộc tính nguyên công (jobs_attributes)

Tham số	Kiểu	Mô tả
id	integer	Bắt buộc khi cập nhật một nguyên công đã có
name	string	Tên nguyên công
order	integer	Thứ tự hiển thị
machine_id	integer	Máy gia công được gán
part_id	integer	Chi tiết gia công
status	string	Trạng thái nguyên công
_destroy	boolean	Truyền true để xóa nguyên công
operations_attributes	array	Các bước gia công lồng bên trong (xem bên dưới)

Thuộc tính bước gia công (operations_attributes)

Tham số	Kiểu	Mô tả
id	integer	Bắt buộc khi cập nhật một bước gia công đã có
name	string	Tên bước gia công
order	integer	Thứ tự hiển thị trong nguyên công
cycle_time	integer	Thời gian chu kỳ ước tính. Phải là số nguyên — numericality: only_integer: true từ chối số thập phân với mã 422
tool_number	integer	Số T trong chương trình NC
tool_assembly_id	integer	Mô hình dụng cụ được gán
_destroy	boolean	Truyền true để xóa bước gia công

Bộ lọc danh sách / tìm kiếm

Tham số	Kiểu	Mô tả
status	string	Lọc theo trạng thái (endpoint danh sách). Đồng thời ngầm lọc locked: false — truyền status sẽ loại các dự án đã khóa dù bạn không yêu cầu bộ lọc đó. Bỏ status nếu bạn cần lấy cả dự án đã khóa.
q	string	Khớp chuỗi con trong tên dự án, không phân biệt chữ hoa chữ thường (endpoint tìm kiếm)

Ví dụ

# 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"

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']}")

Lỗi thường gặp

Mã trạng thái	Nguyên nhân
401	Người dùng của khóa không được phép thực hiện thay đổi đó: ví dụ phê duyệt một dự án đã phát hành khi không có quyền thay đổi các hàng hóa mà việc phê duyệt tạo hoặc cập nhật
404	Không tìm thấy ID dự án, máy gia công hoặc chi tiết
422	Thiếu trường bắt buộc hoặc giá trị trạng thái không hợp lệ

Bài viết liên quan

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