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://lotics.ai/openapi.json (và 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ộ.

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.

Cập nhật trường nhiều giá trị

Một lệnh cập nhật bản ghi chỉ gửi những trường bạn nêu tên, và với trường nhiều giá trị — tệp đính kèm, danh sách chọn nhiều, bản ghi liên kết, người phụ trách — bạn có thể nêu tên từng MỤC thay vì cả danh sách. add_to thêm các mục bạn đưa vào, remove_from bỏ chúng ra, và cả hai đều được tính trên bản ghi tại đúng thời điểm lệnh ghi diễn ra.

Điều đó quan trọng khi có nhiều nơi cùng ghi vào một trường. Nếu bạn đọc danh sách, thêm mục của mình rồi gửi lại cả mảng, những gì được thêm vào giữa lúc bạn đọc và lúc bạn ghi sẽ mất — và phản hồi vẫn báo cập nhật thành công, vì với máy chủ bạn đã yêu cầu đúng danh sách đó. Gửi add_to thì hai bên cùng đính kèm chứng từ trong một khoảnh khắc đều giữ được phần của mình.

{
  "records": [
    { "id": "rec_...", "data": {}, "add_to": { "fld_attachments": ["fil_..."] } }
  ]
}

Dùng dạng data thông thường khi bạn thực sự muốn nói "danh sách bây giờ là như thế này" — sắp xếp lại, hoặc xóa trống. Một trường chỉ được xuất hiện trong data hoặc trong add_to/remove_from, không được cả hai.

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.

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.

Giới hạn tốc độ

Giới hạn được tính theo cửa sổ 60 giây, tách riêng theo địa chỉ IP và theo thành viên. Hạn mức phụ thuộc vào việc yêu cầu làm gì, không phụ thuộc endpoint nào:

Mọi phản hồi đều có X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Khi vượt giới hạn bạn nhận 429 Too Many Requests với Retry-After là số giây còn lại tới khi cửa sổ đặt lại — hãy đọc header đó thay vì đoán, và lùi theo cấp số nhân nếu 429 lặp lại. Liên hệ với chúng tôi nếu bạn cần hạn mức cao hơn.

Phản hồi lỗi

Mọi phản hồi không phải 2xx — kể cả một đường dẫn không khớp route nào — đều là JSON với cùng ba trường:

{
  "code": "not_found",
  "message": "Resource with key=rec_9tK2 not found",
  "hint": "The record may have been deleted. List the table's records to confirm."
}

• code ổn định, và là trường duy nhất nên rẽ nhánh theo.
• message là văn bản cho người đọc. Câu chữ có thể được viết lại; đừng so khớp theo nó.
• hint chỉ xuất hiện khi có bước xử lý tiếp theo cụ thể, còn lại thì vắng mặt.

Một số lỗi kèm thêm trường riêng bên cạnh ba trường trên — 409 do xung đột phiên bản mang current_version_id, một lần ghi bản ghi bị từ chối mang field_errors.

Đúng những hình dạng này được công bố trong tài liệu OpenAPI dưới tên schema Error, và mọi thao tác đều tham chiếu tới nó.

Webhook

Webhook chạy theo chiều đi vào: hệ thống của bạn gọi Lotics, và cuộc gọi đó khởi động một quy trình tự động. Tạo một quy trình với trigger Nhận webhook, Lotics sẽ cấp một URL với đường dẫn ngẫu nhiên 64 ký tự:

https://api.lotics.ai/v1/webhooks/triggers/{webhook_path}

POST một body JSON tới URL đó là quy trình chạy, với body sẵn sàng cho mọi bước — nên một webhook có thể tạo bản ghi, cập nhật trạng thái, sinh chứng từ hoặc gửi thông báo, mà không cần phần logic đó nằm ở bên gọi.

Bảo vệ endpoint

Đường dẫn không thể đoán, và bạn có thể yêu cầu thêm chữ ký. Đặt một khóa bí mật chung trên trigger, rồi gửi X-Webhook-Signature là HMAC-SHA256 dạng hex của đúng phần body:

X-Webhook-Signature: hmac_sha256_hex(secret, raw_request_body)

Hãy ký trên đúng chuỗi byte bạn gửi, không ký trên bản đã parse rồi tuần tự hóa lại — một body được mã hóa lại sẽ cho chữ ký khác. Yêu cầu có chữ ký sai hoặc thiếu chữ ký sẽ bị từ chối và không quy trình nào chạy.

Phản ứng với thay đổi trong Lotics

Không có cơ chế đăng ký sự kiện đi ra: Lotics không tự POST tới URL của bạn khi một bản ghi thay đổi. Hãy làm việc đó bằng quy trình tự động — một quy trình bảng chạy trên after_create / after_update với bước gửi HTTP request sẽ gọi endpoint của bạn, và khác với một danh mục sự kiện cố định, ở đó bạn tự quyết định bản ghi nào đủ điều kiện và payload chứa gì.

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

curl -fsSL https://lotics.ai/install.sh | bash

Trên Windows, mở PowerShell rồi chạy: irm https://lotics.ai/install.ps1 | iex. Lệnh tải về đúng một tệp chạy đã biên dịch sẵn — không cần Node.js, không cần trình quản lý gói.

Từ dòng lệnh

CLI là cách nhanh nhất để một tác nhân AI lập trình làm việc trên workspace — xác thực một lần và mở ra đúng các khả năng của API:

lotics auth signup [email protected]
lotics run query_tables '{}'
lotics run create_records '{"table_id":"tbl_...","records":[{"fld_...":["opt_..."]}]}'

lotics tools liệt kê mọi công cụ mà lệnh run gọi tới được, còn lotics tools <name> in ra schema đầu vào của một công cụ. lotics docs cli_reference in ra tài liệu từng lệnh.

Sinh client có kiểu dữ liệu

Với một chương trình chứ không phải tác nhân, hãy sinh client từ tài liệu OpenAPI — mỗi thao tác có operationId riêng, tham số và schema phản hồi đầy đủ, nên các phương thức sinh ra có tên và có kiểu thay vì phải gọi bằng chuỗi:

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

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://lotics.ai/openapi.json
https://api.lotics.ai/v1/openapi.json

Cả hai phục vụ cùng một tài liệu; địa chỉ đầu là bí danh, dành cho công cụ dò trên tên miền chính. Tài liệu được sinh từ schema của các route ở mỗi lần yêu cầu nên không thể lệch khỏi API: mỗi thao tác có operationId riêng, phần mô tả, tham số có kiểu, schema phản hồi và schema Error dùng chung cho các trường hợp lỗi.

Nhập nó vào Postman, Insomnia, bất kỳ trình sinh code tương thích OpenAPI nào, hoặc một framework tác nhân biết dựng tool function-calling từ đặc tả.

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ó — tính theo cửa sổ 60 giây và theo nhóm route, không phải theo giây. Đọc được 1.200 lần mỗi phút, ghi 600, tải lên 200. Mọi phản hồi đều có X-RateLimit-Remaining; một 429 mang Retry-After là số giây còn lại tới khi cửa sổ đặt lại. Xem phần Giới hạn tốc độ ở trên để có bảng đầy đủ.

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.

Làm sao để được thông báo khi một bản ghi thay đổi?

Hãy dựng một quy trình tự động. Quy trình bảng chạy trên after_create hoặc after_update có thể gọi endpoint của bạn bằng bước gửi HTTP request, và bạn quyết định ngay trong quy trình đó bản ghi nào đủ điều kiện và payload trông ra sao. Lotics không có cơ chế đăng ký sự kiện đi ra để bạn khai báo — webhook của Lotics đi theo chiều ngược lại, từ hệ thống của bạn vào một quy trình.

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.