# Bắt đầu với API

Tạo khóa API và gửi yêu cầu API đầu tiên trong chưa đầy 5 phút.

Source: https://support.toolingmetrics.com/vi/api/getting-started/
Updated: 2026-10-29

**Bạn cần:** Một tài khoản Tooling Metrics có quyền truy cập ít nhất một tổ chức.

API của Tooling Metrics là một JSON REST API chạy trên HTTPS. Mọi yêu cầu đều cần một Bearer token.

## Bước 1: Tạo khóa API

1. Trong Tooling Metrics, nhấp ảnh đại diện ở cuối thanh bên → **Cài đặt** → tab **Khóa API**.
2. Chọn **Tạo khóa API**.
3. Nhập tên cho khóa này (ví dụ: `erp-integration`, `cam-plugin`).
4. Chọn **Tạo** — khóa chỉ hiển thị một lần. Sao chép ngay, vì khóa sẽ không hiển thị lại.

## Bước 2: Tìm ID tổ chức

Phần lớn endpoint của API cần tham số đường dẫn `organization_id`. Lấy ID của bạn:

```bash
curl https://api.toolingmetrics.com/v1/organizations \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Phản hồi — một ánh xạ từ tên tổ chức sang ID dạng số:

```json
{
  "Acme Manufacturing": 12,
  "Acme Tooling": 15
}
```

Dùng ID dạng số này trong mọi yêu cầu tiếp theo.

## Bước 3: Gửi yêu cầu đầu tiên

Liệt kê các máy gia công trong tổ chức của bạn:

```bash
curl https://api.toolingmetrics.com/v1/organizations/12/machines \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Nhận được `200 OK` kèm một mảng JSON nghĩa là xác thực và phạm vi tổ chức đều hoạt động đúng.

## Bước 4: Xử lý lỗi

Mọi lỗi của API đều trả về JSON. Phần lớn dùng mảng `errors`:

```json
{ "errors": ["Description of what went wrong"] }
```

| Mã trạng thái | Nguyên nhân | Cách xử lý |
|---|---|---|
| `401` | Thiếu khóa hoặc khóa không hợp lệ, **hoặc** khóa hợp lệ nhưng không được phép truy cập tài nguyên này, kể cả với một `organization_id` không tồn tại | Đọc thông báo lỗi: khi thiếu khóa, thông báo yêu cầu bạn xác thực; khi không đủ quyền, thông báo là "You are not authorized to perform this action" |
| `404` | Không tìm thấy bản ghi hoặc bản ghi thuộc tổ chức khác | Kiểm tra lại ID, và bản ghi có thuộc tổ chức `organization_id` trong URL không; một `organization_id` không tồn tại trả về `401`. Lưu ý: thân phản hồi của lỗi này dùng khóa số ít `error`, không phải `errors` |
| `422` | Kiểm tra dữ liệu không đạt | Đọc mảng `errors` trong phản hồi |
| `429` | Vượt giới hạn tần suất | Chờ số giây ghi trong `Retry-After` rồi thử lại |

API này không dùng mã `403` — cả khóa thiếu/không hợp lệ lẫn khóa hợp lệ nhưng không đủ quyền đều trả về `401`, chỉ phân biệt qua thông báo lỗi. Xem [Lỗi](https://support.toolingmetrics.com/vi/api/errors/) để nắm toàn bộ, kể cả điểm không nhất quán giữa khóa `error` và `errors`.

Xem [Lỗi](https://support.toolingmetrics.com/vi/api/errors/) để có tham chiếu đầy đủ.

## Bước tiếp theo

- [Khái niệm](https://support.toolingmetrics.com/vi/api/concepts/) — phạm vi tổ chức, phân trang, định dạng ngày và các tài nguyên chỉ đọc
- Hướng dẫn (sắp ra mắt) — các mẫu từng bước cho tích hợp CAM, đồng bộ ERP và tự động hóa sản xuất. Trong lúc chờ, xem [Khái niệm](https://support.toolingmetrics.com/vi/api/concepts/) để biết phạm vi hiện tại của API.
- [Tham khảo](https://support.toolingmetrics.com/vi/api/reference/) — tài liệu đầy đủ về các endpoint