REST API

Lotics API cho bạn quyền truy cập lập trình vào mọi thứ trong không gian làm việc. Tạo bản ghi, truy vấn dữ liệu, kích hoạt quy trình, tạo chứng từ 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

• Giao thức: REST chuẩn. Tài nguyên là danh từ, phương thức HTTP là động từ, phản hồi sử dụng mã trạng thái HTTP chuẩn.
• Đặc tả: OpenAPI 3.1.0, công bố tại https://api.lotics.ai/v1/openapi.json.
• URL gốc: https://api.lotics.ai/v1
• Kiểu nội dung: Tất cả yêu cầu và phản hồi sử dụng application/json.
• Định dạng ngày: Chuỗi ISO 8601 theo UTC (ví dụ: 2026-04-04T12:00:00.000Z).
• Giá trị trường bản ghi: Tuân theo cùng kiểu dữ liệ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).

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 chứng từ, ứng dụng, file) đều có sẵn qua API. 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.

Xác thực

Yêu cầu API được xác thực bằng khóa API có phạm vi tổ chức.

Gửi khóa

Thêm khóa vào header Authorization trong mỗi yêu cầu:

Authorization: Bearer ltk_your_key_here

Phản hồi lỗi

Thực hành bảo mật tốt nhất

• Khóa chỉ hiển thị một lần khi tạo. Sao chép và lưu trữ an toàn (ví dụ: biến môi trường, trình quản lý bí mật).
• Đặt tên mô tả cho mỗi khóa (ví dụ: "Đồng bộ sản xuất", "CI/CD pipeline") để dễ nhận dạng.
• Nếu khóa bị lộ, vô hiệu hóa ngay từ Cài đặt -> Khóa API và tạo khóa mới.
• Sử dụng khóa riêng cho từng môi trường (sản xuất, staging, phát triể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 chứng từ và tìm kiếm toàn cục.

Truy vấn bản ghi

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. 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 và trong ứng dụng. Không có chi phí lọc phía client bất kể kích thước bảng.

Phân trang

Tất cả endpoint danh sách sử dụng phân trang dựa trên con trỏ để đảm bảo kết quả nhất quán ngay cả khi có ghi đồng thời.

Cách hoạt động

1. Gửi yêu cầu đầu tiên không có tham số cursor.
2. Nếu còn kết quả, phản hồi bao gồm trường next_cursor.
3. Truyền giá trị next_cursor làm tham số query cursor trong yêu cầu tiếp theo.
4. Lặp lại cho đến khi next_cursor không còn, nghĩa là bạn đã đến trang cuối.

Phân trang dựa trên con trỏ đảm bảo thứ tự ổn định ngay cả khi bản ghi được tạo hoặc xóa giữa các trang.

Giới hạn tốc độ

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.

Khi bạn vượt giới hạn tốc độ, bạn 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ính bằng giây). Triển khai exponential backoff trong client để đạt kết quả tốt nhất. Liên hệ hỗ trợ nếu trường hợp sử dụng của bạn cần giới hạn cao hơn.

Phản hồi lỗi

Tất cả phản hồi lỗi tuân theo cấu trúc JSON nhất quán:

{
  "error": {
    "code": "not_found",
    "message": "Record not found"
  }
}

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.

Các loại sự kiện có sẵn

Hành vi webhook

• Lọc: 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: 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.
• Chữ ký: Payload bao gồm header chữ ký để xác minh. Xác nhận chữ ký để đảm bảo webhook đến từ Lotics.
• Thử lại: Gửi thất bại được thử lại với exponential backoff trong tối đa 24 giờ.
• Giám sát: 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.
• Tự động vô hiệu hóa: Nếu endpoint liên tục thất bại, 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

Lotics 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 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.

CLI và SDK

Lotics cung cấp giao diện dòng lệnh và SDK Node.js cho scripting, tự động hóa và tích hợp.

Cài đặt

npm install -g @lotics/cli

SDK Node.js

import { LoticsClient } from "@lotics/cli";

const client = new LoticsClient({
  apiKey: "ltk_your_key_here",
});

// List tables
const tables = await client.tables.list();

// Query records with filters
const records = await client.records.query("table_id", {
  filters: { field: "status", operator: "eq", value: "active" },
  limit: 50,
});

// Create a record
const record = await client.records.create("table_id", {
  values: { name: "New item", status: "draft" },
});

Xem tài liệu CLI để biết đầy đủ tài liệu dòng lệnh.

Đặc tả OpenAPI

Đặc tả OpenAPI 3.1.0 được công bố tại:

https://api.lotics.ai/v1/openapi.json

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.

Sử dụng openapi-generator để tạo SDK có kiểu dữ liệu trong TypeScript, Python, Go, Java và các ngôn ngữ khác:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.lotics.ai/v1/openapi.json \
  -g typescript-fetch \
  -o ./lotics-client

Các trường hợp sử dụng phổ biến

• Đồng bộ hệ thống: Giữ Lotics đồng bộ với hệ thống bên ngoài (ERP, CRM, thương mại điện tử) bằng cách đẩy và lấy bản ghi qua API.
• Dashboard tùy chỉnh: Xây dựng dashboard lấy dữ liệu trực tiếp từ bảng Lotics sử dụng endpoint truy vấn và tổng hợp.
• Tạo bản ghi 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.
• Tạo báo cáo: Truy vấn và tổng hợp dữ liệu bản ghi bằng lập trình để tạo báo cáo.
• Tự động hóa chứng từ: Điền mẫu chứng từ bằng dữ liệu bản ghi để xuất PDF và file Excel theo yêu cầu.
• Tích hợp CI/CD: Sử dụng khóa API trong pipeline để tạo bản ghi, cập nhật trạng thái hoặc kích hoạt quy trình như một phần của quy trình triển khai.

Câu hỏi thường gặp

API có giới hạn tốc độ không?

Có. Giới hạn tốc độ chuẩn là 100 yêu cầu mỗi giây mỗi khóa API với dung lượng burst cho tăng đột ngột ngắn hạn. Yêu cầu bị giới hạn nhận phản hồi 429 với header Retry-After. Liên hệ hỗ trợ nếu trường hợp sử dụng của bạn cần giới hạn cao hơn.

Tôi có thể dùng API để tạo quy trình bằng lập trình không?

Có. Endpoint quy trình hỗ trợ CRUD đầy đủ. Bạn có thể tạo kích hoạt, định nghĩa các bước (bao gồm điều kiện, vòng lặp và hành động AI) và triển khai quy trình hoàn toàn qua API. Lịch sử thực thi quy trình cũng có sẵn qua API.

Làm thế nào để xử lý tải file lên qua API?

Sử dụng endpoint tải lên File với yêu cầu multipart/form-data. Phản hồi trả về ID file mà bạn có thể gán vào trường file khi tạo hoặc cập nhật bản ghi. URL tải xuống file có chữ ký và giới hạn thời gian để bảo mật.

Tôi có thể thử nghiệm API mà không ảnh hưởng dữ liệu sản xuất không?

Tạo tổ chức riêng cho phát triển và thử nghiệm. Khóa API có phạm vi tổ chức, nên khóa thử nghiệm chỉ truy cập dữ liệu thử nghiệm. Không có chi phí thêm cho tổ chức phát triển.

Đặc tả OpenAPI có sẵn để tạo code không?

Có. Đặc tả OpenAPI 3.1.0 tại https://api.lotics.ai/v1/openapi.json có thể nhập vào công cụ như openapi-generator, Postman hoặc bất kỳ client tương thích OpenAPI nào để tạo SDK có kiểu dữ liệu trong TypeScript, Python, Go, Java và các ngôn ngữ khác.

Phân trang dựa trên con trỏ khác gì với phân trang dựa trên offset?

Phân trang dựa trên con trỏ sử dụng token không trong suốt (next_cursor) thay vì số trang. Điều này đả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. Với phân trang offset, thêm và xóa có thể khiến bạn bỏ sót bản ghi hoặc thấy trùng lặp. Phân trang dựa trên con trỏ tránh hoàn toàn các vấn đề này.

Điều gì xảy ra nếu endpoint webhook của tôi không hoạt động?

Lotics thử lại gửi webhook thất bại với exponential backoff trong tối đa 24 giờ. Nếu endpoint liên tục thất bại, Lotics vô hiệu hóa webhook và thông báo cho quản trị viên tổ chức qua email. Bạn có thể xem nhật ký gửi và thử lại thủ công từ Cài đặt -> Webhook.

Trợ lý AI có thể tương tác với API không?

Có. MCP Server cung cấp cùng khả năng như REST API thông qua chuẩn Model Context Protocol. Trợ lý AI và công cụ dựa trên LLM có thể truy vấn dữ liệu, tạo bản ghi, kích hoạt quy trình và tạo chứng từ. Xem tài liệu MCP Server để biết cách thiết lập.

Làm thế nào để lọc bản ghi theo nhiều điều kiện?

Endpoint truy vấn hỗ trợ nhóm bộ lọc AND/OR lồng nhau. Mỗi bộ lọc chỉ định trường, toán tử và giá trị. Bạn có thể kết hợp bộ lọc thành nhóm với logic and/or. Công cụ lọc là cùng công cụ sử dụng trong giao diện Lotics, nên bất kỳ bộ lọc nào bạn xây dựng trong UI đều có thể tái tạo qua API.

Những loại trường nào được hỗ trợ?

Tất cả loại trường có sẵn trong giao diện Lotics đều được hỗ trợ qua API: văn bản, số, ngày, chọn, chọn nhiều, checkbox, bản ghi liên kết, file, công thức, rollup và lookup. Trường tính toán (công thức, rollup, lookup) chỉ đọc -- giá trị của chúng được tính tự động dựa trên cấu hình.