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

API là cùng giao diện mà ứng dụng web Lotics dùng bên trong. Điều một khóa với tới qua đó là dữ liệu của bạn và những thứ định hình nó – bảng, trường, bản ghi, chế độ xem, quy trình, ứng dụng, mẫu chứng từ, file, bình luận và tìm kiếm. Việc điều hành tổ chức thì không: những đường dẫn quản lý người, chia sẻ, không gian làm việc, thanh toán và nhật ký truy cập đều trả 403 cho khóa có quyền truy cập riêng dù khóa được đặt thế nào, và cần một quản trị viên đã đăng nhập. Xem Khóa được phép làm gì.

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.

Khóa do quản trị viên tạo trong phần Cài đặt có tên riêng và quyền truy cập riêng. Khóa không thuộc về ai: nó vẫn chạy tiếp khi người quản trị đã tạo ra nó rời tổ chức, và mọi thao tác ghi do khóa thực hiện đều được ghi nhận dưới tên khóa chứ không phải dưới tên người đó.

Khóa cũng có thể được tạo cho một người, khi đó khóa mang quyền truy cập của người ấy — danh sách khóa ghi Thay mặt kèm tên họ — và ngừng chạy khi người ấy bị loại khỏi tổ chức.

Bốn mục bạn đặt khi tạo khóa

Cho khóa “chỉ những thứ được chọn” quyền truy cập

Bạn chọn ứng dụng và bảng ngay trên khóa. Chọn Chỉ những thứ được chọn và một danh sách hiện ra: mọi ứng dụng và bảng trong tổ chức, thuộc không gian làm việc nào cũng có. Chọn những thứ mà tích hợp động tới và đặt mức cho từng thứ — Được xem hay Được chỉnh sửa với một bảng, Người dùng hay Quản lý với một ứng dụng.

Danh sách đó vẫn nằm trên màn hình của khóa sau này, nên bạn thêm một mục, thu lại một mục hay đổi mức bất cứ lúc nào. Biểu mẫu đòi ít nhất một mục, vì khóa không với tới gì vẫn xác thực được rồi bị từ chối ở mọi nơi. Khóa vẫn có thể rơi vào tình trạng đó — bảng cuối cùng của nó bị lưu trữ, hay bị thu lại ngay trong hộp thoại Chia sẻ của bảng ấy — và khi đó màn hình của khóa nói rõ; hãy thêm một ứng dụng hoặc một bảng, hoặc xóa khóa.

Dưới danh sách, mục Sở hữu liệt kê những gì chính khóa đã tạo ra. Khóa với tới được những thứ đó dù danh sách ghi gì, và cách duy nhất để lấy lại là chuyển giao ngay trong hộp thoại Chia sẻ của ứng dụng hoặc bảng đó. Chuyển khóa sang Mọi ứng dụng và bảng thì danh sách bị bỏ; chuyển lại thì bắt đầu từ danh sách trống.

Hộp thoại Chia sẻ của một ứng dụng hay một bảng có HIỆN khóa nào đang với tới nó, và cho bạn thu quyền đó lại từ đây. Nó không thêm khóa và không đổi mức — khóa với tới được những gì là một quyết định, làm ở một chỗ, nơi bạn nhìn được toàn bộ.

Mọi ứng dụng và bảng thì không cần danh sách: khóa với tới mọi thứ trong tổ chức.

Khóa tạo ra gì thì sở hữu thứ đó

Ứng dụng, bảng hay bản ghi tạo qua khóa thuộc về khóa, không thuộc về quản trị viên đã tạo khóa — nhờ vậy một tích hợp sống lâu hơn người dựng ra nó. Quản trị viên vẫn thấy và quản lý mọi thứ khóa sở hữu — trừ nội dung bên trong tài liệu kiến thức và mẫu tài liệu của khóa, thứ quản trị viên chỉ mở được khi đã được chia sẻ — và có thể chuyển bất kỳ thứ nào trong đó cho một người bất cứ lúc nào.

Ứng dụng chạy bằng quyền của chủ sở hữu, nên ứng dụng do khóa Chỉ những thứ được chọn dựng lên cũng chỉ với tới đúng những gì khóa đó với tới.

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

Một yêu cầu đầy đủ, chạy được ngay khi bạn thay khóa và mã bảng của mình vào — đọc bản ghi của một bảng, là POST vì bộ lọc, sắp xếp và phân trang đi trong thân yêu cầu:

curl -X POST https://api.lotics.ai/v1/tables/tbl_7Qm2xR9kLpTd/records/query \
  -H "Authorization: Bearer ltk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

Thêm -H "x-workspace-id: wsp_3nKpQ8vTzRdW" khi tổ chức có nhiều hơn một không gian làm việc; với một không gian duy nhất thì hệ thống tự suy ra.

Khóa được phép làm gì

Mục Được phép của khóa nói khóa được làm gì, tách khỏi việc khóa với tới được những gì. Đặt khi tạo khóa, sửa sau ở Cài đặt -> Khóa API; mọi thay đổi đều được ghi vào nhật ký truy cập.

Chọn Chỉ những gì tôi chọn để ghép bốn mục trên. Khóa không được làm gì cả không phải là một lựa chọn — hãy vô hiệu hóa khóa, việc đó đảo ngược được và hiện trong nhật ký truy cập.

Những mục này chỉ thu hẹp. Khóa không bao giờ làm được nhiều hơn quyền truy cập của nó, nên khóa chỉ được cho một bảng vẫn bị giới hạn trong bảng đó dù bạn tích gì, và siết một khóa có hiệu lực ngay.

Không khóa nào có quyền truy cập riêng mà điều hành được tổ chức. Dù quyền truy cập là gì và mục Được phép đặt thế nào, khóa như vậy vẫn không quản lý được người (thành viên, lời mời, nhóm, mật khẩu), không đổi được những gì đang chia sẻ hay ai sở hữu, không tạo hay xóa được không gian làm việc, không đổi được cài đặt không gian làm việc, không đặt được hạn mức tín dụng, không đọc được nhật ký truy cập, và không công bố được API của ứng dụng. Những việc đó cần một quản trị viên đã đăng nhập — trong Lotics, trong cửa sổ dòng lệnh đã đăng nhập bằng lotics auth login, hoặc qua một kết nối. Khóa nào thử làm sẽ nhận 403 kèm thông báo nói rõ điều này. Khóa tạo cho một người thì chính là người đó: nó làm được đúng những gì người đó được làm.

Thay khóa, và kết thúc khóa

Ba nút trên màn hình của chính khóa đó, từ nhẹ nhất đến dứt điểm.

Tắt một khóa không làm đổi khóa bí mật của nó, nên ai đang giữ khóa bí mật cũ sẽ vào lại được ngay khi khóa được bật lên. Khi chính khóa bí mật mới là vấn đề, hãy cấp lại khóa — hoặc xóa khóa đi.

Cấp lại khóa chỉ có ở khóa bí mật hiện hành: khóa mang quyền truy cập của chính nó, đang bật và chưa hết hạn. Khóa đã tắt hoặc đã hết hạn thì không cấp lại được — hãy tạo khóa mới. Khóa cũ mà một lần cấp lại để lại cũng không còn khóa bí mật nào để thay, nên dòng của nó ghi rõ nó đã được thay và lúc nào thì ngừng, còn khóa nên cấp lại là khóa mới nhất. Khóa tạo cho một người thì mang quyền của người đó, nên không có khóa bí mật thứ hai để cấp — hãy tạo khóa mới với quyền truy cập bạn muốn, rồi tắt khóa cũ.

Thông tin đăng nhập mà một người dùng để đăng nhập thì chỉ đi một chiều. Một lần đăng nhập từ dòng lệnh, và khóa tạo ra để mang quyền của một người, đều tắt được hoặc xóa được nhưng không bật lại được — bật lại sẽ là một lần đăng nhập mà không ai thực hiện. Khi đã tắt, màn hình của nó ghi rõ điều đó và không còn công tắc: hãy đăng nhập lại bằng lotics auth login, hoặc tạo khóa API mới.

Đăng nhập từ dòng lệnh

CLI lotics nhận cả hai loại thông tin đăng nhập, và bạn đang giữ loại nào sẽ quyết định việc đăng xuất làm gì.

Dùng đăng nhập cho cửa sổ dòng lệnh của riêng bạn. Dùng khóa cho máy chủ, việc chạy theo lịch, hay bất cứ thứ gì phải chạy tiếp khi bạn không có mặt.

Phản hồi lỗi

Khóa và cửa sổ dòng lệnh

Cài đặt -> Bảo mật liệt kê mọi thông tin đăng nhập đang thay mặt bạn — những lần đăng nhập từ dòng lệnh và mọi khóa được tạo cho bạn — kèm tên và lần dùng gần nhất. Hãy kết thúc thứ nào bạn không nhận ra: thứ đang dùng nó ngừng chạy ngay, nó không bao giờ chạy lại được, và nó rời khỏi danh sách. lotics auth logout cũng làm đúng như vậy với cửa sổ dòng lệnh bạn đang dùng. Không có gì bị xóa sạch — việc mà thông tin đăng nhập đó đã làm vẫn nằm trong nhật ký truy cập, nơi đọc được lịch sử ai từng có quyền.

Quản trị viên xem mọi khóa của tổ chức ở Cài đặt -> Khóa API, kèm người đã tạo ra từng khóa.

Khi một người rời tổ chức, mọi thông tin đăng nhập hoạt động thay mặt họ kết thúc theo — những lần đăng nhập của riêng họ và mọi khóa hoạt động thay mặt họ — và khôi phục họ sau đó cũng không đưa những thứ đó trở lại: họ đăng nhập lại. Khóa mang quyền truy cập của chính nó thì không nằm trong số đó: nó không phải người đó, nên các tích hợp đang chạy trên nó vẫn chạy tiếp.

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”, “Chạy CI”) để dễ nhận dạng.
• Chỉ cho mỗi khóa quyền truy cập mà nó cần — Chỉ những thứ được chọn, chỉ giữ đúng các ứng dụng và bảng mà tích hợp đó chạm tới, là thứ giới hạn thiệt hại khi khóa bị lộ.
• Chỉ cho mỗi khóa mục Được phép mà nó cần — khóa chỉ đọc thì không thể bị bắt ghi.
• Thay khóa định kỳ bằng Cấp lại khóa: khóa bí mật mới dùng được ngay và khóa cũ còn chạy thêm 24 giờ, nên không có gì gián đoạn trong lúc bạn triển khai.
• Nếu khóa bị lộ, hãy mở khóa đó ở Cài đặt -> Khóa API, gạt tắt Đã bật rồi nhấn Lưu – khóa ngừng ngay – sau đó tạo khóa mới và xóa khóa cũ.
• 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ách một số hiển thị: notation

Trường số, và công thức trả về số, nêu cách con số hiển thị bằng một notation: { "style": "decimal" }, tiền { "style": "currency", "currency": "USD" }, hoặc số lượng { "style": "unit", "unit": "kg" } — "percent" cũng là một đơn vị, và 10 hiển thị 10%. Tiền tệ hoặc đơn vị đọc theo từng dòng từ một trường chọn đơn của chính dòng đó được ghi là { "per_row": "fld_…" } ở vị trí tương ứng. notation của rollup và lookup do hệ thống suy ra, và được trả về trên trường.

Các khóa mà notation đã thay thế — format, currency, unit, unit_field và currency_field, cùng format: "link" của công thức (nay là link: true) — không còn được đọc. Lệnh ghi nêu các khóa này theo một cách hiển thị khác với cách nó để lại cho trường sẽ bị từ chối, và lỗi trả về nêu rõ notation cần gửi: "format": "currency", "currency": "USD" trên trường mới bị từ chối, còn "format": "number" trên trường mới, hoặc các khóa gửi lại đúng như trường đang lưu, vẫn được nhận. Muốn đổi cách một trường hiển thị, hãy gửi notation; gửi lại trường đúng như bạn đã đọc, chỉ đổi notation, vẫn chạy. Các khóa cũ tạm thời vẫn được trả về bên cạnh notation — hãy đọc notation. Đơn vị tiền phải là mã ISO 4217 ở mọi lệnh ghi đổi nó; trường đang giữ một cách viết khác vẫn giữ nguyên qua lệnh sửa không đụng đến notation.

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, còn một lần ghi bản ghi bị từ chối hay một nội dung gửi lên ứng dụng bị từ chối thì 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ó.

Mọi phản hồi đều mang header x-request-id — của bạn nếu bạn gửi lên (chữ, số, ., _, : hoặc -, tối đa 128 ký tự), không thì là một mã chúng tôi sinh ra. Hãy ghi lại nó bên cạnh mỗi lỗi và gửi cho chúng tôi: đó là mã tìm ra đúng yêu cầu đó. Phản hồi 401 còn mang WWW-Authenticate: Bearer, kèm error="invalid_token" khi chính khóa bạn gửi lên là thứ bị từ chối — đó là chỗ phân biệt “hãy xác thực” với “đừng thử lại khóa đang cầm”.

Gọi một ứng dụng từ trang web hoặc máy chủ của bạn

Ứng dụng khai báo trước những gì nó làm được — các truy vấn để đọc, các quy trình để ghi, và các tác nhân để làm trọn một việc (xem Ứng dụng). Những khai báo đó chính là các endpoint có địa chỉ, nên trang web của bạn dùng được Lotics làm nơi lưu giữ dữ liệu.

Gọi chúng từ máy chủ của bạn, kèm khóa API. Tạo khóa ở Cài đặt → Khóa API, chọn Chỉ những thứ được chọn, và chỉ cấp cho khóa đúng ứng dụng mà trang web dùng: khóa khi đó chạm tới ứng dụng đó và không gì khác. Trình duyệt của khách nói chuyện với máy chủ của bạn, máy chủ của bạn nói chuyện với Lotics — khóa không bao giờ nằm trong trang.

Ứng dụng không có màn hình (chỉ có truy vấn và quy trình) luôn ở chế độ riêng tư: đây là cách gọi nó. Chia sẻ công khai là dành cho màn hình của chính ứng dụng, để ai có liên kết cũng mở được.

Ba endpoint

POST /v1/apps/{app_id}/queries/{alias}              # chạy một truy vấn đã khai báo
POST /v1/apps/{app_id}/workflows/{alias}/execute    # chạy một quy trình đã khai báo
POST /v1/apps/{app_id}/agents/{alias}/runs          # khởi động một tác nhân đã khai báo

Lời gọi truy vấn điền các tham số mà mẫu truy vấn khai báo, và có thể thu hẹp thêm trong phạm vi những gì truy vấn đó đã trả về:

const res = await fetch(
  "https://api.lotics.ai/v1/apps/app_7Qm2xR/queries/open_orders",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.LOTICS_API_KEY}`,
    },
    body: JSON.stringify({ params: { branch: "north" }, limit: 50 }),
  },
);
const { rows } = await res.json();

Phản hồi mang rows (mỗi dòng một đối tượng, khóa là tên cột mà truy vấn khai báo), columns mô tả các cột đó, và — khi bạn yêu cầu — total, next_cursor cùng truncated.

Lời gọi quy trình gửi các đầu vào có kiểu mà bí danh đó khai báo:

const res = await fetch(
  "https://api.lotics.ai/v1/apps/app_7Qm2xR/workflows/submit_enquiry/execute",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.LOTICS_API_KEY}`,
    },
    body: JSON.stringify({ inputs: { company: "Acme", email: "buyer@acme.example" } }),
  },
);
const result = await res.json();

Phản hồi gồm status (success hoặc error), message khi có, data khi quy trình trả về dữ liệu, files cho những file nó sinh ra, và field_errors theo tên đầu vào khi nó từ chối một giá trị — đây là thứ để biểu mẫu hiện lỗi ngay tại ô nhập sai.

Bên gọi thuộc chính tổ chức sở hữu ứng dụng còn nhận thêm side_effects, bản ghi nhận của chính lần chạy về những gì nó đã thay đổi: các bản ghi nó tạo ra xếp theo bảng, các file nó sinh ra, và những bước không hoàn tác được. Kèm theo là số bản ghi lần chạy đã tạo, cập nhật, xóa, khôi phục, khóa hoặc mở khóa, cùng refused: true khi error là do quy trình từ chối chứ không phải do lỗi — lần ghi bị từ chối không hề diễn ra, nhưng những gì một bước trước đó đã ghi thì vẫn còn, và các con số cho thấy điều đó. Mọi bên gọi khác, kể cả khách truy cập không có khóa, chỉ nhận câu trả lời của quy trình, vì các mã đó chỉ tới những dòng nằm trong một không gian làm việc mà bên gọi ấy không đọc, không xóa và không soát lại được.

Khi chính lần chạy bị lỗi, chứ không phải quy trình từ chối, bên gọi ở ngoài tổ chức sở hữu ứng dụng chỉ nhận một câu message chung, bằng ngôn ngữ mà Accept-Language của yêu cầu chỉ định, kèm execution_id — mã của lần chạy, theo đó chủ ứng dụng đọc được điều gì đã hỏng.

Mọi lời gọi đều kèm Authorization: Bearer ltk_…. Bên gọi duy nhất không có khóa là khách mở màn hình của một ứng dụng công khai.

Gửi file

Đầu vào kiểu file của quy trình hoặc tác nhân nhận mã file, không nhận nội dung file. Đổi mỗi file thành một mã bằng hai lời gọi tới chính ứng dụng đó, và giữa hai lời gọi thì PUT nội dung file thẳng vào kho lưu trữ. Làm việc này từ máy chủ của bạn, kèm khóa của bạn: kho lưu trữ chỉ nhận PUT từ trình duyệt trên chính các trang của ứng dụng, nên trang web của bạn gửi file về máy chủ của bạn và máy chủ tải file lên.

// Trên máy chủ của bạn. `photo` là { name, type, bytes } từ route tải lên của chính bạn.
const app = "https://api.lotics.ai/v1/apps/app_7Qm2xR";
const post = (path, body) =>
  fetch(`${app}/${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.LOTICS_API_KEY}`,
    },
    body: JSON.stringify(body),
  }).then((res) => res.json());

const { file_id, file_storage_key, upload_url } = await post("files/upload-url", {
  filename: photo.name,
  mime_type: photo.type,
  file_size: photo.bytes.byteLength,
});
await fetch(upload_url, { method: "PUT", headers: { "Content-Type": photo.type }, body: photo.bytes });
await post("files/complete", { file_id, file_storage_key, filename: photo.name });

await post("workflows/request_quote/execute", { inputs: { photos: [file_id] } });

upload_url được ký cho đúng loại và dung lượng bạn khai báo, và hết hạn sau 10 phút. files/complete đối chiếu file đã lưu với dung lượng đó, và chỉ sau đó các đầu vào của ứng dụng mới nhận file_id. Mỗi file tối đa 25 MB, loại nào cũng được. Gửi khóa ở cả hai lời gọi; bên gọi không có khóa được tải lên 500 MB mỗi giờ từ một địa chỉ, và mọi khách truy cập đi qua máy chủ của bạn dùng chung địa chỉ đó.

File được lưu trong không gian làm việc của ứng dụng dù ai tải lên, và đầu vào file của ứng dụng chỉ nhận file thuộc không gian làm việc đó. Ứng dụng nào có API đã xuất bản nhận file thì tài liệu OpenAPI của nó cũng liệt kê hai lời gọi này.

Chạy một tác nhân

Lời gọi tác nhân khởi động một lần chạy và trả về diễn biến của lần chạy đó. Nó gửi một session_id do bạn tự đặt — chuỗi bất kỳ khác rỗng — kèm input mà bí danh đó khai báo:

const res = await fetch(
  "https://api.lotics.ai/v1/apps/app_7Qm2xR/agents/triage_enquiry/runs",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.LOTICS_API_KEY}`,
    },
    body: JSON.stringify({ session_id: "web-42", input: { enquiry_id: "rec_9tK2" } }),
  },
);
const runId = res.headers.get("x-app-agent-run-id");
const runToken = res.headers.get("x-app-agent-run-token");

Lần chạy gửi kèm khóa sẽ đọc những lần chạy trước mang cùng session_id làm ngữ cảnh — đó là cách một lượt sau nối tiếp lượt trước. Lần chạy không mang khóa thì không đọc gì cả: mạch việc mà một người lạ xin được cũng là mạch việc họ đoán ra được — nên với ứng dụng công khai, mã đó chỉ gom các lần chạy của chính bạn, không hơn; hãy gửi đủ mọi thứ lần chạy ấy cần ngay trong input.

Phản hồi là một luồng sự kiện do máy chủ đẩy về, mang những gì tác nhân nói và làm trong lúc nó chạy. Kết quả không nằm trong luồng đó — hãy đọc kết quả tại lần chạy:

GET /v1/apps/{app_id}/agent-runs/{run_id}

run.status nhận một trong các giá trị running, awaiting_input, completed, error, aborted; còn run.output là rỗng cho tới khi lần chạy ngã ngũ. Ở completed, đó là đối tượng mà bí danh khai báo, hoặc là đoạn văn tác nhân kết lại khi bí danh không khai báo đầu ra nào. awaiting_input nghĩa là tác nhân đang hỏi lại bên gọi: chính lần đọc đó mang câu hỏi trong pending_interactive, câu trả lời gửi tới POST /v1/apps/{app_id}/agent-runs/{run_id}/continue, còn POST /v1/apps/{app_id}/agent-runs/{run_id}/cancel thì dừng hẳn lần chạy.

Lần chạy đi tới cùng ở phía chúng tôi dù bạn còn nghe luồng hay không, nên đứt luồng cũng không mất gì — cứ đọc lại lần chạy. Lời gọi không mang khóa sẽ nhận thêm x-app-agent-run-token bên cạnh mã lần chạy; gửi lại nó đúng header ấy khi đọc, và nó chỉ chạm tới đúng lần chạy đó, không hơn.

Một lần chạy tác nhân tiêu credit của tổ chức bạn, và người quyết định lúc nào chạy là bên gọi. Với ứng dụng chia sẻ công khai thì bên gọi ấy là người lạ. Thứ giới hạn họ là cửa sổ tính theo địa chỉ ở bảng dưới, mức trần số lần chạy mà một ứng dụng được giữ cùng lúc cho người ngoài, và hạn mức credit của chính tổ chức bạn — nên chỉ đặt tác nhân vào ứng dụng công khai khi bạn thật sự muốn người lạ chạy nó.

Khi có lỗi

Vì sao lời gọi đi từ máy chủ của bạn

API chỉ trả lời trình duyệt trên chính các trang của Lotics, nên JavaScript trên trang của bạn không gọi thẳng được — và cũng không nên: mọi thứ một trang tải xuống đều đọc được bởi bất kỳ ai mở trang, và khóa nằm trong trang là khóa ai cũng sao chép được. Máy chủ của bạn giữ khóa, kiểm tra những gì biểu mẫu gửi lên, rồi gọi ứng dụng. Mọi nền tảng dựng trang web đều có route phía máy chủ cho việc này (API route của Next.js, function của Netlify và Vercel, một handler Express).

Trang web không có máy chủ riêng thì dẫn liên kết tới, hoặc nhúng, chính màn hình của ứng dụng: khi chia sẻ công khai, ai có liên kết cũng dùng được.

Xuất bản API của một ứng dụng

Khai báo của ứng dụng thay đổi theo thời gian khi ứng dụng được cải tiến. Xuất bản API biến những khai báo đó thành một bản cam kết — bản chụp được đánh số, ghi chính xác mỗi bí danh nhận gì và trả về gì — để mã nguồn của bạn, thứ mà không ai ở đây triển khai lại được, không bị vỡ vì một thay đổi trong không gian làm việc.

lotics run publish_app_api '{"app_id":"app_..."}'     # chụp bản cam kết; in ra số phiên bản và các cảnh báo
lotics run unpublish_app_api '{"app_id":"app_..."}'   # kết thúc cam kết

Tài liệu OpenAPI 3.1 của bản chụp được phục vụ trực tiếp, dành cho công cụ sinh mã tự tải về:

GET https://api.lotics.ai/v1/apps/{app_id}/openapi.json

Nó mô tả mỗi truy vấn, mỗi quy trình và mỗi tác nhân thành một thao tác riêng, với mã ứng dụng thật nằm sẵn trong đường dẫn, nên openapi-generator biến từng bí danh thành một phương thức riêng có tên và có kiểu — cộng thêm một lần đọc duy nhất, nơi gom kết quả của mọi lần chạy tác nhân, bất kể bí danh nào sinh ra nó. Tài liệu dựng từ bản chụp đã xuất bản, không phải từ trạng thái hiện tại của ứng dụng — client sinh ra từ nó khớp đúng những gì ứng dụng đã cam kết.

Thế nào là một thay đổi phá vỡ cam kết

Từ lúc xuất bản, mỗi thay đổi trên ứng dụng là một lần phát hành. Thay đổi chỉ THÊM vào thì được áp dụng và chụp lại ở phiên bản kế tiếp, bạn không phải làm gì. Thay đổi làm vỡ bên gọi thì bị từ chối, và lời từ chối nêu đích danh từng chỗ:

• một truy vấn, quy trình hoặc tác nhân không còn nữa, hoặc một cột, một đầu ra đã biến mất;
• một cột hoặc đầu ra đổi kiểu, hoặc có thể rỗng ở chỗ trước đây luôn có giá trị;
• thêm một đầu vào bắt buộc, bỏ một đầu vào, hoặc thu hẹp tập giá trị mà một đầu vào chấp nhận;
• khai báo hình dạng đầu vào cho một tác nhân vốn chưa khai báo gì, vì từ đó những khóa riêng của bên gọi bị từ chối;
• kết quả của một tác nhân đổi kiểu, theo cả hai chiều — thành đối tượng ở chỗ vốn là văn bản tự do, hoặc thành văn bản tự do ở chỗ vốn là đối tượng.

Chiều ngược lại thì luôn an toàn, và điều này đáng nhớ vì nó không đối xứng: thêm một đầu vào không bắt buộc, thêm một cột, bớt một giá trị mà đầu ra có thể mang, bỏ hình dạng đầu vào của một tác nhân để nó nhận lại mọi đối tượng — không cái nào làm vỡ bên đang đọc hay đang gọi.

Lối đi qua một lời từ chối là một bí danh mới. Khai báo hình dạng mới bên cạnh cái cũ, chuyển dần bên gọi sang, rồi gỡ bí danh cũ khi không còn ai gọi — bên dùng chuyển khi họ sẵn sàng, chứ không phải khi bạn triển khai. Khi bạn thật sự muốn phá vỡ cam kết — bạn nắm cả hai đầu, hoặc chưa ai gọi tới — hãy thêm "acknowledge_breaking_api_change": true vào lệnh ghi (set_app_queries, set_app_workflow, set_app_agent, remove_app_binding, apply_model, rollback_app), nó sẽ thực hiện và chụp lại bản cam kết mới. Chỉ có hiệu lực khi đến từ quản trị viên của tổ chức.

Thay đổi trên bảng dữ liệu bên dưới cũng bị từ chối theo đúng cách đó, và ở đó không có tùy chọn xác nhận: một cam kết được thay đổi từ phía ứng dụng, nơi phiên bản mới được chụp.

Nếu bạn viết mã để xử lý thay vì đọc trên màn hình dòng lệnh: cả hai lời từ chối đều là 409, mỗi loại có mã riêng kèm danh sách có cấu trúc về những gì sẽ vỡ — breaking_api_change cho thay đổi trên ứng dụng, và published_api_contract cho thay đổi trên bảng, loại này mang theo app_id của từng ứng dụng bị ảnh hưởng. Hãy rẽ nhánh theo code rồi đọc breaking_changes, trường này nằm ngay cùng cấp với code và message trong phản hồi; câu thông báo chỉ liệt kê tối đa năm thay đổi cho mỗi ứng dụng, còn trường dữ liệu mang đủ tất cả. CLI chỉ in câu của máy chủ, không in danh sách — hãy đọc danh sách từ phản hồi.

Việc xuất bản từ chối thẳng một trường hợp: truy vấn không tự đặt tên cho các cột nó trả về. Những tên đó lấy từ bảng, và sẽ đổi dưới chân bên gọi mỗi khi bảng đổi, nên chúng không phải là thứ ứng dụng có quyền cam kết. Lời từ chối nêu tên từng truy vấn và chỉ ra cách sửa.

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 thân yêu cầu JSON tới URL đó là quy trình chạy, với thân yêu cầu 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.

Mỗi đường dẫn webhook nhận 600 lượt gửi mỗi phút và body tối đa 5 MB. Nhịp gửi được tính cho chính đường dẫn đó chứ không theo từng bên gửi, vì một nền tảng biểu mẫu hay một cầu nối ERP dùng địa chỉ của chính nó cho mọi nơi nó chuyển tiếp. Vượt một trong hai, phản hồi là 429 kèm Retry-After — bên gửi có thử lại theo header đó thì không mất gì.

Nhận dữ liệu biểu mẫu từ nền tảng biểu mẫu

Typeform, Jotform, Google Forms qua một cầu nối, khối biểu mẫu của trình dựng website — thứ gì POST được tới một URL đều có thể đổ vào một quy trình tự động. Ba điều quyết định việc đó chạy được hay không, và cả ba đều hỏng trong im lặng:

• Gửi JSON. Phần body không phải JSON hợp lệ sẽ đến dưới dạng văn bản thô, nên kiểu form-urlencoded mà phần lớn nền tảng đặt mặc định chỉ đưa cho quy trình một chuỗi thay vì các trường. Hãy đổi payload sang JSON trong phần cài đặt webhook của nền tảng đó.
• Đọc body có phòng vệ. Body là đúng những gì bên gửi đã POST, nên quy trình phải kiểm tra hình dạng trước khi đọc một trường — if (isObject(trigger.body)), rồi toString(trigger.body.email) cho từng trường. Viết thẳng trigger.body.email sẽ bị từ chối ngay khi lưu quy trình.
• Quy trình lỗi thì bên gửi nhận về lỗi. Phản hồi HTTP chính là kết quả của quy trình, nên một bước không hoàn tất được sẽ thành lỗi gửi tin ở phía nền tảng biểu mẫu — đúng cho một hệ thống biết gửi lại, và sai cho bất cứ việc gì có người đang ngồi chờ. Với biểu mẫu mà người dùng điền ngay trên trang web của bạn, hãy đặt một ứng dụng ở phía trước (xem Gọi một ứng dụng từ trang web hoặc máy chủ của bạn): quy trình đã khai báo sẽ kiểm tra các đầu vào có kiểu và báo lại cho người gửi biết ô nào sai.

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 ban@congty.com
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 tự dựng giao diện riêng trên Lotics được không?

Được. Các truy vấn, quy trình và tác nhân mà ứng dụng khai báo chính là những endpoint có địa chỉ, nên trang web hoặc máy chủ của bạn đọc, ghi và giao việc qua đó, còn Lotics vẫn là nơi lưu giữ dữ liệu. Xuất bản API của ứng dụng thì bạn có một bản cam kết được đánh số cùng tài liệu OpenAPI để sinh client, và từ đó một thay đổi trong không gian làm việc không còn làm vỡ mã nguồn của bạn mà không ai hay biết. Xem Gọi một ứng dụng từ trang web hoặc máy chủ của bạ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.

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.