# API chi tiết

Liệt kê, tạo, cập nhật, xóa và tìm kiếm chi tiết gia công.

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

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

## Endpoint

| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
| `GET` | `/parts` | Liệt kê mọi chi tiết |
| `GET` | `/parts/:id` | Lấy một chi tiết |
| `POST` | `/parts` | Tạo chi tiết |
| `PATCH` | `/parts/:id` | Cập nhật chi tiết |
| `DELETE` | `/parts/:id` | Xóa chi tiết |
| `GET` | `/parts/search` | Tìm theo mã chi tiết và/hoặc mô tả |

## Đối tượng chi tiết

```json
{
  "id": 5,
  "number": "P-0042",
  "description": "Cylinder Block",
  "customer_number": "CB-100",
  "created_at": "2025-03-01T08:00:00Z",
  "updated_at": "2025-06-01T10:00:00Z",
  "material": {
    "id": 2,
    "name": "42CrMo4",
    "iso_code": "P20",
    "vdi_code": "1.7225"
  },
  "created_by": { "id": 7, "email": "user@example.com" }
}
```

## Tham số

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

| Tham số | Kiểu | Mô tả |
|---|---|---|
| `number` | string | Mã chi tiết. Nếu để trống khi tạo, hệ thống tự sinh theo chuỗi đánh số chi tiết của tổ chức. |
| `description` | string | Mô tả chi tiết |
| `customer_number` | string | Mã tham chiếu riêng của khách hàng |
| `material_id` | integer | ID của vật liệu trong thư viện vật liệu: vật liệu của chính tổ chức hoặc vật liệu dùng chung. Vật liệu của tổ chức khác trả về `422` |
| `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 chi tiết 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. |
| `picture` | string | Ảnh chi tiết dạng PNG mã hóa Base64 |
| `drawing` | string | Bản vẽ 2D dạng DXF mã hóa Base64 |
| `model` | string | Mô hình 3D dạng tệp STEP mã hóa Base64 |

### Tìm kiếm

| Tham số | Kiểu | Mô tả |
|---|---|---|
| `number` | string | Khớp chính xác theo mã chi tiết |
| `description` | string | Khớp chính xác theo mô tả, không phân biệt chữ hoa chữ thường |

Có thể kết hợp cả hai tham số để thu hẹp kết quả.

## Tệp đính kèm

Hình ảnh, bản vẽ và mô hình STEP được tải lên dưới dạng chuỗi mã hóa Base64 trong thân yêu cầu JSON. Tệp được lưu trong kho lưu trữ đối tượng và gắn với bản ghi chi tiết sau khi lưu.

```json
{
  "number": "P-0042",
  "description": "Cylinder Block",
  "model": "<base64-encoded-step-content>"
}
```

## Ví dụ

```bash
# Search by part number
curl "https://api.toolingmetrics.com/v1/organizations/12/parts/search?number=P-0042" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create a part — organization_id is required in the body, not just the URL
curl -X POST "https://api.toolingmetrics.com/v1/organizations/12/parts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number": "P-0042", "description": "Cylinder Block", "material_id": 2, "organization_id": 12}'
```

```python
import requests
import base64

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

# Create a part with a STEP model attached
with open("cylinder_block.stp", "rb") as f:
    model_b64 = base64.b64encode(f.read()).decode()

response = requests.post(
    f"{BASE}/organizations/12/parts",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "number": "P-0042",
        "description": "Cylinder Block",
        "material_id": 2,
        "organization_id": 12,
        "model": model_b64,
    },
)
response.raise_for_status()
part = response.json()
print(f"Created part #{part['id']}: {part['number']}")
```