Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.cleeksy.com/llms.txt

Use this file to discover all available pages before exploring further.

API portal (cổng API) là một loại Data source cho phép hệ thống ngoài đọc dữ liệu ra (pull) và/hoặc ghi dữ liệu vào (push) theo các endpoint được cấu hình. Liên quan:

​
Authentication/token (khái niệm cơ bản)

API thường cần token để xác thực và giới hạn quyền truy cập. Khuyến nghị:
  • Token theo môi trường (dev/test/prod)
  • Xoay token định kỳ (rotation)
  • Không hardcode token trong client public (frontend)

​
Endpoint patterns (mẫu endpoint thường dùng)

​
Read (GET)

  • Lọc theo trạng thái/thời gian/owner
  • Phân trang khi dữ liệu lớn

​
Create (POST)

  • Map payload vào field cho phép
  • Trả về ID/mã record để theo dõi

​
Update (PUT/PATCH)

  • Cập nhật theo record ID hoặc External ID
  • Chỉ mở field cần thiết, tránh cập nhật vượt ownership

​
Upload (tệp đính kèm)

  • Giới hạn loại file/dung lượng
  • Chỉ định record đích rõ ràng

​
Ví dụ

​
Ví dụ 1 — Hệ thống ngoài tạo ticket vào app

  • POST tạo record Ticket
  • Workflow phân công người xử lý và gửi thông báo

​
Ví dụ 2 — Hệ thống ngoài pull danh sách record theo filter

  • GET trả về record theo trạng thái và thời gian
  • Client lưu External ID để đối chiếu

​
Error handling (xử lý lỗi)

  • Chuẩn hoá lỗi: thiếu field, sai định dạng, không đủ quyền
  • Retry có kiểm soát để tránh tạo trùng (dựa trên External ID hoặc idempotency key)
  • Log requestId/correlationId để truy vết (nếu có)

​
Guardrails

  • Chỉ mở endpoint và field cần thiết
  • Thiết lập filter để giới hạn phạm vi dữ liệu được đọc
  • Tách token read-only và write