REST API
Lotics API cho bạn quyền truy cập lập trình vào mọi thứ trong workspace. Tạo bản ghi, truy vấn dữ liệu, kích hoạt quy trình, tạo tài liệu và nhận thông báo thời gian thực, tất cả thông qua giao diện REST chuẩn với đặc tả OpenAPI 3.1.0.
Tổng quan
Lotics API tuân theo quy ước REST: tài nguyên là danh từ, phương thức HTTP là động từ và phản hồi sử dụng mã trạng thái chuẩn. Mọi thực thể bạn tương tác trong giao diện Lotics (bảng, bản ghi, chế độ xem, quy trình, mẫu tài liệu, file) đều có sẵn qua API. URL gốc là https://api.lotics.ai/v1.
Đặc tả OpenAPI 3.1.0 được công bố tại https://api.lotics.ai/v1/openapi.json. Bạn có thể nhập đặc tả này vào công cụ như Postman, Insomnia hoặc bất kỳ trình tạo code tương thích OpenAPI nào để có thư viện client có kiểu dữ liệu trong ngôn ngữ bạn thích. Đặc tả đồng bộ với API. Khi endpoint mới ra mắt, đặc tả tự động cập nhật.
Tất cả yêu cầu và phản hồi sử dụng JSON. Ngày là chuỗi ISO 8601 theo UTC. Giá trị trường bản ghi tuân theo cùng các kiểu như giao diện Lotics: văn bản, số, ngày, chọn, chọn nhiều, bản ghi liên kết, file và trường tính toán (công thức, rollup, lookup).
Xác thực
Yêu cầu API được xác thực bằng API key có phạm vi tổ chức. Mỗi key có phạm vi một tổ chức duy nhất và thừa kế quyền của thành viên tạo key. Key sử dụng định dạng ltk_ theo sau bởi 48 ký tự (ví dụ: ltk_vAJZYFb9WrF94Z3OjpdZgxjc...). Chỉ admin mới có thể tạo API key.
Tạo API key trong Cài đặt → API Key. Mỗi key có tên để nhận dạng (ví dụ: "Đồng bộ sản xuất", "CI/CD pipeline"). Key chỉ hiển thị một lần khi tạo. Lưu trữ chúng an toàn. Nếu key bị lộ, vô hiệu hóa ngay từ Cài đặt và tạo key mới.
Thêm key vào header x-api-key: x-api-key: ltk_your_key_here. Yêu cầu không có key hợp lệ nhận phản hồi 401 Unauthorized. Key bị vô hiệu hóa nhận phản hồi 403 Forbidden. Xác thực API key hiện hỗ trợ cho endpoint bảng, bản ghi, trường và chế độ xem. Các endpoint khác (quy trình, mẫu tài liệu, ứng dụng) sử dụng xác thực phiên.
Các endpoint có sẵn
API cung cấp thao tác CRUD đầy đủ cho tất cả thực thể chính, cộng thêm các thao tác chuyên biệt như tổng hợp bản ghi, tạo tài liệu và tìm kiếm toàn cục. Dưới đây là tóm tắt các endpoint tài nguyên có sẵn.
Mỗi endpoint hỗ trợ tham số truy vấn chuẩn để lọc và phân trang. Truy vấn bản ghi hỗ trợ lọc theo trường, sắp xếp theo bất kỳ trường nào và phân trang phía server với điều hướng dựa trên cursor để hiệu suất ổn định ở bất kỳ kích thước bảng nào.
| Tài nguyên | Thao tác | Ghi chú |
|---|---|---|
| Bảng (Tables) | Danh sách, Tạo, Lấy, Cập nhật, Xóa, Sao chép | Bao gồm định nghĩa trường. Sao chép nhân bản cấu trúc và tùy chọn dữ liệu. |
| Trường (Fields) | Tạo, Cập nhật, Xóa | Thêm hoặc sửa trường trên bảng hiện có. Hỗ trợ tất cả loại trường bao gồm trường tính toán. |
| Bản ghi (Records) | Truy vấn, Lấy, Lấy theo ID, Tạo, Cập nhật, Xóa, Tổng hợp | Truy vấn hỗ trợ lọc, sắp xếp, phân trang. Tổng hợp trả về số lượng, tổng, trung bình theo trường. |
| Chế độ xem (Views) | Danh sách, Tạo, Lấy, Cập nhật, Xóa | Chế độ xem lưu cấu hình lọc, sắp xếp, hiển thị trường và quy tắc màu. |
| Quy trình (Workflows) | Danh sách, Tạo, Lấy, Cập nhật, Xóa | Bao gồm cấu hình trigger, định nghĩa bước và lịch sử thực thi. |
| Mẫu tài liệu (Document Templates) | Danh sách, Tạo, Lấy, Cập nhật, Xóa, Tạo tài liệu | Tạo tài liệu tạo file (PDF, Excel) từ mẫu và dữ liệu bản ghi. |
| Ứng dụng (Apps) | Danh sách, Tạo, Lấy, Cập nhật, Xóa | Ứng dụng là giao diện tùy chỉnh xây dựng trên bảng. |
| Bình luận (Comments) | Danh sách, Tạo, Cập nhật, Xóa | Bình luận gắn vào bản ghi. Danh sách hỗ trợ lọc theo bản ghi. |
| File | Tải lên, Đọc, Xóa | Tải file lên để gắn vào bản ghi. Đọc trả về URL tải xuống có chữ ký. |
| Tài khoản kết nối (Connected Accounts) | Danh sách, Yêu cầu, Xóa | Truy vấn tài khoản OAuth đã kết nối. Yêu cầu bắt đầu luồng OAuth mới. |
| Tìm kiếm (Search) | Tìm kiếm toàn cục | Tìm kiếm xuyên bảng và bản ghi trong tổ chức. |
Giới hạn tốc độ và phân trang
API áp dụng giới hạn tốc độ để đảm bảo sử dụng công bằng và hiệu suất ổn định. Giới hạn chuẩn là 100 yêu cầu mỗi giây mỗi API key. Dung lượng burst cho phép tăng đột ngột ngắn hạn trên giới hạn này. Yêu cầu bị giới hạn tốc độ nhận phản hồi 429 Too Many Requests với header Retry-After cho biết khi nào thử lại.
Tất cả endpoint danh sách sử dụng phân trang dựa trên cursor. Phản hồi bao gồm trường next_cursor khi còn kết quả. Truyền giá trị này làm tham số truy vấn cursor trong yêu cầu tiếp theo. Kích thước trang mặc định 100 bản ghi và có thể điều chỉnh lên tới 1.000 với tham số limit. Phân trang cursor đảm bảo kết quả nhất quán ngay cả khi bản ghi được tạo hoặc xóa giữa các yêu cầu.
Truy vấn bản ghi được thực thi phía server với cùng công cụ lọc sử dụng bởi giao diện Lotics. Điều này có nghĩa các bộ lọc phức tạp (điều kiện AND/OR lồng nhau, tra cứu bản ghi liên kết, so sánh ngày) hoạt động giống nhau qua API như trong ứng dụng. Không có chi phí lọc phía client bất kể kích thước bảng.
Sự kiện webhook
Đăng ký endpoint webhook để nhận thông báo thời gian thực khi dữ liệu thay đổi. Lotics gửi HTTP POST đến URL của bạn trong vài giây sau khi thay đổi xảy ra. Sự kiện bao gồm dữ liệu bản ghi đầy đủ trước và sau thay đổi, nên bạn có thể phản ứng với cập nhật trường cụ thể mà không cần polling.
Các loại sự kiện có sẵn bao gồm record.created, record.updated, record.deleted, workflow.completed và workflow.failed. Mỗi đăng ký webhook có thể lọc theo bảng và loại sự kiện để bạn chỉ nhận thông báo liên quan. Payload webhook bao gồm header chữ ký để xác minh.
Gửi thất bại được thử lại với backoff theo hàm mũ trong tối đa 24 giờ. Bạn có thể xem nhật ký gửi và thử lại thủ công các lần gửi thất bại từ Cài đặt, Webhook. Nếu endpoint thất bại liên tục, Lotics vô hiệu hóa nó và gửi thông báo email cho quản trị viên tổ chức.
MCP Server và các trường hợp sử dụng
Lotics cũng cung cấp MCP (Model Context Protocol) server cung cấp cùng khả năng như REST API thông qua chuẩn MCP. Điều này cho phép trợ lý AI và công cụ dựa trên LLM tương tác trực tiếp với dữ liệu Lotics của bạn. Xem trang tài liệu MCP Server riêng để biết hướng dẫn thiết lập và các công cụ có sẵn.
Các trường hợp sử dụng API phổ biến bao gồm đồng bộ dữ liệu giữa Lotics và hệ thống bên ngoài (ERP, CRM, thương mại điện tử), xây dựng dashboard tùy chỉnh lấy dữ liệu trực tiếp từ bảng Lotics, tự động tạo bản ghi từ sự kiện bên ngoài (gửi biểu mẫu, xác nhận thanh toán, cập nhật vận chuyển) và tạo báo cáo bằng cách truy vấn và tổng hợp dữ liệu bản ghi bằng lập trình.
API là cùng giao diện mà ứng dụng web Lotics sử dụng nội bộ, nên mọi tính năng có sẵn trong UI cũng có sẵn qua API. Không có endpoint hạng hai hoặc khả năng bị giới hạn.