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

> Cung cấp API để đọc/ghi dữ liệu có kiểm soát.

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:

* [Cổng dữ liệu (Data source)](/build-apps/integrations/data-sources-overview)
* [Webhook portal (cổng webhook)](/build-apps/integrations/webhook-portal)
* [Bảo mật (Security)](/build-apps/integrations/security-tokens)

***

## 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