# Khái niệm Phạm vi tổ chức, cấu trúc yêu cầu/phản hồi, định dạng ngày, tệp đính kèm và những gì chưa có. Source: https://support.toolingmetrics.com/vi/api/concepts/ Updated: 2026-10-28 ## URL gốc API chạy trên tên miền phụ riêng, không phải một đường dẫn bên dưới ứng dụng chính: ``` https://api.toolingmetrics.com/v1 ``` Mọi yêu cầu và phản hồi đều dùng JSON. Đặt `Content-Type: application/json` cho các yêu cầu ghi. ## Phạm vi tổ chức Mọi tài nguyên trong Tooling Metrics đều thuộc về một tổ chức. Phần lớn endpoint cần đoạn đường dẫn `organization_id`: ``` GET /v1/organizations/:organization_id/machines GET /v1/organizations/:organization_id/parts ``` Lấy ID tổ chức của bạn từ `GET /v1/organizations`. Một `organization_id` không tồn tại nhận `401 Unauthorized`, với cùng thân phản hồi như một tổ chức mà khóa của bạn không truy cập được, nên API không cho biết mã tổ chức nào tồn tại. Bản ghi chỉ được tìm trong tổ chức mà URL chỉ định: một bản ghi của tổ chức khác trả về `404 Not Found` với cùng thân phản hồi như một mã không tồn tại, kể cả khi khóa của bạn đọc được bản ghi đó dưới mã tổ chức của chính nó. Truyền đúng một `organization_id` mà bạn là thành viên vẫn chưa đủ — vai trò của bạn với từng loại tài nguyên còn giới hạn những bản ghi bạn xem được. Xem phần "Phạm vi phân quyền" trong [Xác thực](https://support.toolingmetrics.com/vi/api/authentication/). ## Xác thực Mọi yêu cầu đều cần một Bearer token trong header `Authorization`: ``` Authorization: Bearer ``` Khóa API là của cá nhân — tạo và thu hồi tại tab **Khóa API** trong cài đặt tài khoản (ảnh đại diện → **Cài đặt**), không phải ở khu vực quản trị tổ chức. Mỗi khóa có đúng quyền truy cập của người dùng đã tạo ra nó. Xem [Xác thực](https://support.toolingmetrics.com/vi/api/authentication/). ## Không phân trang Các endpoint danh sách (`index`, `search`) **không phân trang** — chúng trả về mọi bản ghi khớp trong một phản hồi duy nhất. Không có tham số `page` hay `per_page`. Nếu tổ chức của bạn có rất nhiều bản ghi của một loại, hãy tính đến khả năng thân phản hồi rất lớn; lọc bằng các tham số truy vấn riêng của từng tài nguyên được mô tả trong mỗi trang [tham khảo](https://support.toolingmetrics.com/vi/api/reference/) thay vì trông vào phân trang. Phản hồi danh sách là mảng JSON trần — không có lớp bọc ngoài: ```json [ { "id": 1, "...": "..." }, { "id": 2, "...": "..." } ] ``` `Organizations#show` là ngoại lệ duy nhất — endpoint này trả về một đối tượng JSON ánh xạ tên tổ chức sang ID, không phải một mảng. ## Danh sách và chi tiết Một số tài nguyên có hai dạng biểu diễn: - **Danh sách** (`GET /resources`) — với dự án là bản tóm tắt gọn phù hợp cho trang danh sách; với máy gia công, chi tiết và mô hình dụng cụ là cùng cấu trúc lồng nhau như dạng chi tiết - **Chi tiết** (`GET /resources/:id`) — đối tượng đầy đủ kèm các liên kết lồng nhau Ví dụ: `GET /projects` trả về các bản tóm tắt gọn `{id, name, status, locked}`; `GET /projects/8` trả về dự án đầy đủ, gồm cả nguyên công và bước gia công. Máy gia công và chi tiết trả về cùng cấu trúc đầy đủ ở cả `index` lẫn `show`. ## Tài nguyên chỉ đọc Mô hình dụng cụ chỉ được quản lý trong giao diện Tooling Metrics (tạo và chỉnh sửa ở đó) và là tài nguyên **chỉ đọc** qua API — không có route `POST`, `PATCH` hay `DELETE` cho mô hình dụng cụ. Yêu cầu dùng phương thức ghi trên đường dẫn này không khớp route nào, nên sẽ không trả về lỗi JSON gọn gàng — hãy chờ đợi một lỗi ở tầng định tuyến thay vì một mã trạng thái được mô tả trong tài liệu. Chỉ dùng `GET` cho tài nguyên này. ## Định dạng ngày giờ Mọi mốc thời gian được trả về dưới dạng chuỗi **ISO 8601** theo giờ UTC: ```json "created_at": "2026-06-02T08:30:00Z" ``` Truyền mốc thời gian theo cùng định dạng trong các yêu cầu ghi. ## Tệp đính kèm Tệp tải lên (hình ảnh, bản vẽ, mô hình STEP) được truyền dưới dạng **chuỗi mã hóa Base64** trong thân JSON — không dùng dữ liệu biểu mẫu multipart: ```json { "number": "P-0042", "model": "" } ``` Xem trang tham khảo [Chi tiết](https://support.toolingmetrics.com/vi/api/reference/parts/) để biết tên trường và ví dụ. ## Giới hạn tần suất 60 yêu cầu mỗi phút cho mỗi khóa. Phản hồi không có các header `X-RateLimit-*` — header duy nhất liên quan đến giới hạn tần suất là `Retry-After`, được gửi kèm phản hồi `429`. Xem [Giới hạn tần suất](https://support.toolingmetrics.com/vi/api/rate-limits/). ## Các tích hợp phổ biến | Tích hợp | Chức năng | Bắt đầu tại đây | |---|---|---| | Phần mềm CAM | Đọc mô hình dụng cụ và chế độ cắt, đẩy dự án lên sau khi lập trình | Hướng dẫn tích hợp CAM (sắp ra mắt). Xem [Tham khảo](https://support.toolingmetrics.com/vi/api/reference/) để biết các endpoint hiện có. | | ERP / MRP | Dự kiến: đồng bộ hàng hóa tồn kho và đơn mua hàng. Các endpoint này chưa có | Hướng dẫn đồng bộ ERP (sắp ra mắt). Xem [Chưa có](#chưa-có) để biết phạm vi hiện tại của API. | | Máy đo dao (presetter) | Dự kiến: ghi giá trị bù đã đo trở lại dụng cụ. Endpoint ghi dụng cụ chưa có | Hướng dẫn tự động hóa sản xuất (sắp ra mắt). Xem [Chưa có](#chưa-có) để biết phạm vi hiện tại của API. | | Tự động hóa tùy chỉnh | Dự kiến: tạo phiếu xuất kho và theo dõi ổ tích dao. Endpoint tạo phiếu xuất kho chưa có | Hướng dẫn tự động hóa sản xuất (sắp ra mắt). Xem [Chưa có](#chưa-có) để biết phạm vi hiện tại của API. | ## Chưa có API hiện bao gồm tổ chức, máy gia công, mô hình dụng cụ, chi tiết và dự án. API chưa cung cấp hàng hóa tồn kho, trạng thái/vị trí của dụng cụ thực tế, phiếu xuất kho hay đơn mua hàng — hiện những dữ liệu này chỉ có trên giao diện. Nếu tích hợp của bạn cần mức tồn kho hoặc dữ liệu mua hàng, hiện chưa có đường API nào cho việc đó. Các hướng dẫn tích hợp chưa được phát hành; xem [Tham khảo](https://support.toolingmetrics.com/vi/api/reference/) để biết các endpoint hiện có.