> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taho.com.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# API / Swagger

> Điểm bắt đầu cho hợp đồng HTTP, xác thực và đặc tả OpenAPI của Mini App và trợ lý AI.

Trang này giúp bạn đọc request, response và điều kiện truy cập trước khi gọi API. Các trang endpoint bên trái hiển thị hợp đồng OpenAPI cho Mini App và trợ lý AI đã được đối chiếu với handler hiện tại.

## Swagger nằm ở đâu?

Đặc tả `openapi.json` nằm trong repository docs và dùng để hiển thị các trang API. Đây là tài liệu bổ sung từ source hiện tại. Swagger UI hoặc endpoint phục vụ OpenAPI trong application: **Not Found**. Not confirmed by current source code.

Mở file `openapi.json` ở thư mục gốc repository docs bằng công cụ hỗ trợ OpenAPI. Các trang endpoint sử dụng cơ chế [OpenAPI của Mintlify](https://www.mintlify.com/docs/api-playground/openapi-setup).

Không giả định application có `/swagger`, `/api-docs` hoặc `/openapi.json`. Danh sách đầy đủ route và method nằm tại [Danh mục route](https://docs.taho.com.vn/reference/route-catalog.md).

Đặc tả chưa đặt `servers` vì docs không có URL gốc application được xác nhận dùng chung cho mọi môi trường. Các trang dùng chế độ đọc hợp đồng, không có nút gửi request. Nếu mẫu cURL hiện `https://api.example.com`, đó là URL minh họa của trình hiển thị; thay bằng URL backend của môi trường kiểm thử trước khi chạy.

## Chọn nhóm API

| Bạn đang làm gì? | Hợp đồng cần đọc |
| - | - |
| Đăng nhập Mini App bằng Zalo | [Xác minh danh tính](https://docs.taho.com.vn/api-reference/resident-auth.md) |
| Đọc dữ liệu căn hộ | [Đọc portal](https://docs.taho.com.vn/api-reference/resident-portal.md) |
| Gửi liên kết hoặc ý kiến | [Gửi thao tác cư dân](https://docs.taho.com.vn/api-reference/resident-actions.md) |
| BQL duyệt, từ chối hoặc thu hồi | [Duyệt quyền căn hộ](https://docs.taho.com.vn/api-reference/resident-access-review.md) |
| Hỏi trợ lý và mở lịch sử | [Gửi câu hỏi](https://docs.taho.com.vn/api-reference/ai-chat.md), [Đọc lịch sử](https://docs.taho.com.vn/api-reference/ai-history.md) |
| Thêm hoặc lưu trữ tài liệu | [Tải tài liệu](https://docs.taho.com.vn/api-reference/ai-knowledge-upload.md), [Lưu trữ tài liệu](https://docs.taho.com.vn/api-reference/ai-knowledge-archive.md) |
| Gọi công cụ MCP | [Phạm vi MCP](https://docs.taho.com.vn/ai/index.md#kết-nối-mcp); endpoint dùng giao thức MCP, không dùng body chat của AI |
| Workflow tài chính, import hoặc export | [Route handlers](https://docs.taho.com.vn/engineering/route-handlers.md), [Nhập và xuất dữ liệu](https://docs.taho.com.vn/engineering/import-export.md), [Danh mục route](https://docs.taho.com.vn/reference/route-catalog.md) |

## Hai loại phiên khác nhau

| Kênh | Cách xác thực và phạm vi |
| - | - |
| Admin và AI | Phiên quản trị; backend đọc quyền route/action và tòa nhà đang chọn. Hỗ trợ token admin qua header hoặc cookie phiên. |
| Mini App | `Authorization: Bearer <RESIDENT_SESSION_TOKEN>` sau khi backend xác minh Zalo. Quyền căn hộ được đọc từ liên kết của định danh cư dân. |

`accessToken` gửi tới endpoint xác minh Zalo khác với token phiên Taho trả về. Token cư dân không thay thế phiên admin. Header preview chỉ dành cho nhánh ngoài production được mô tả tại [Chạy Mini App local](https://docs.taho.com.vn/mini-app/local-development.md).

Mutation quản trị còn kiểm tra nguồn request, quyền route/action và dữ liệu đầu vào. Chỉ có token chưa bảo đảm yêu cầu được chấp nhận.

## Đọc response

Các endpoint trong đặc tả dùng một trong hai cấu trúc sau:

```json theme={null}
{
  "success": true,
  "data": {}
}
```

```json theme={null}
{
  "success": false,
  "error": {
    "code": "<ERROR_CODE>",
    "message": "<PUBLIC_MESSAGE>"
  }
}
```

`data` phụ thuộc endpoint; `error.details` chỉ xuất hiện khi handler cung cấp. Workflow admin có thể trả `redirectTo` trong JSON, còn file export/attachment và MCP có hợp đồng riêng. Không áp dụng mẫu JSON này cho mọi route.

Đọc [Cấu hình môi trường](https://docs.taho.com.vn/engineering/environment-setup.md) và [Chỉ mục testcase](https://docs.taho.com.vn/reference/manual-testcases.md) để nối cấu hình, request và mục tiêu nghiệp vụ.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.