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

# Dùng Custom API trong Nhân sự số

> Gắn REST API connector vào Nhân sự số, đặt quyền Tự động, Hỏi, Chặn cho từng thao tác, chạy thử và gỡ khỏi Nhân sự số.

> [!NOTE]
>
> Trang này hướng dẫn dùng một **REST API connector** đã tạo ở Workspace trong từng Nhân sự số. Nếu chưa có Connector, xem [Kết nối Custom API trên Space](https://docs-eos.fpt.ai/eos/vi/custom-api-connectors.md) để tạo trước.

## Lối vào

**Nhân sự số của tôi** → mở Nhân sự số → **Dựng Nhân sự số** → panel **Cấu hình** → mục **Kết nối** → dấu **+**.

## Gắn Connector vào Nhân sự số

**1. Mở mục Kết nối của Nhân sự số**

Mở Nhân sự số, ở màn hình **Dựng Nhân sự số** chọn panel **Cấu hình**, nhấn dấu **+** ở mục **Kết nối**.

**2. Chọn kiểu tài khoản**

Chọn **Dùng chung** (một tài khoản của Workspace) hoặc **Theo người dùng** (tài khoản riêng của mỗi người).

![Menu chọn Dùng chung hoặc Theo người dùng](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_connector_add_menu.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=1eefe2281aee6c1d86fdc29e8e57f1f7)

**3. Tích Connector rồi nhấn Xong**

Custom Connector nằm chung danh sách với Connector có sẵn. Tích Connector cần dùng rồi nhấn **Xong**. Nút **Tạo connector mới** ở góc dưới mở cùng hộp thoại tạo REST API như trên trang Kết nối.

![Hộp chọn Connector dùng chung với Demo Orders API đã được chọn](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_connector_picker.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=dee232bd5744bc0ab0e8d2e136fefacf)

**4. Mở rộng Connector để xem các thao tác**

Connector xuất hiện trong mục **Kết nối** kèm kiểu tài khoản và số ngoại lệ. Nhấn vào dòng Connector để xem tài khoản đang dùng và quyền của từng thao tác.

![Connector đã gắn với quyền mặc định của từng thao tác](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_connector_permissions.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=78130089c3c04930770405357691c8eb)

| Kiểu tài khoản | Khi Nhân sự số chạy | Nên dùng khi |
| - | - | - |
| **Dùng chung** | Nhân sự số luôn dùng cùng một tài khoản của Workspace, bất kể ai hỏi | API nghiệp vụ chung, khoá do quản trị viên cấp |
| **Theo người dùng** | Mỗi người tự kết nối và dùng tài khoản của mình. Trong mục Kết nối, tab này hiện tên **Riêng người** | Mỗi người có khoá hoặc quyền khác nhau trên API |

Với **Dùng chung**, phần **Tài khoản** cho biết Nhân sự số đang dùng tài khoản nào. Nhấn biểu tượng đổi tài khoản để chọn tài khoản khác, **Thêm tài khoản** hoặc **Quản lý tài khoản**.

![Menu chọn tài khoản cho Connector dùng chung](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_connector_account.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=cbea82df6de2db7b8758b0890fade180)

Với **Theo người dùng**, mục Connector không có phần Tài khoản. Người dùng chưa kết nối tài khoản của mình thì Nhân sự số sẽ báo cần kết nối trước khi gọi thao tác.

![Connector gắn theo kiểu Theo người dùng](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_connector_peruser.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=f11483e6c33e2b74f76a20bc72bfa8ec)

> [!NOTE]
>
> Trên một Nhân sự số, mỗi Connector chỉ gắn được theo một kiểu. Connector đã gắn kiểu Dùng chung sẽ hiện nhãn **Đã thêm** trong hộp chọn Theo người dùng. Muốn đổi kiểu, gỡ Connector rồi gắn lại.

## Đặt quyền cho từng thao tác

Mỗi thao tác có ba mức quyền:

| Mức | Nhân sự số làm gì | Mặc định cho |
| - | - | - |
| **Tự động** | Gọi API ngay, không hỏi | Thao tác **Chỉ đọc** |
| **Hỏi** | Dừng lại xin người dùng duyệt trước khi gọi | Thao tác **Ghi dữ liệu** và **Có thể xoá dữ liệu** |
| **Chặn** | Không được gọi thao tác này | Không có mặc định, bạn tự đặt |

Số **ngoại lệ** cạnh tên Connector cho biết có bao nhiêu thao tác đang khác mức mặc định. Ví dụ dưới đây đặt **Huỷ đơn hàng** về **Chặn** để Nhân sự số không thể huỷ đơn.

![Thao tác Huỷ đơn hàng được đặt về Chặn](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_connector_block.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=f9ec3804bb5c8e49a6346b90a52dfe24)

> [!TIP]
>
> Gỡ rồi gắn lại Connector sẽ đưa quyền của mọi thao tác về mặc định. Ghi lại các ngoại lệ trước khi gỡ.

## Chạy thử Nhân sự số với Connector

**1. Gửi yêu cầu ở tab Chạy thử**

Mở tab **Chạy thử** và gửi một yêu cầu cần đến API, ví dụ: Tạo đơn hàng cho khách Trần Thị B, tổng tiền 250000.

**2. Duyệt hoặc từ chối thao tác**

Với thao tác ở mức **Hỏi**, thẻ **Cần bạn phê duyệt hành động** hiện tên thao tác và các tham số Nhân sự số định gửi. Nhấn **Duyệt** để gọi API. Nhấn **Từ chối** để không gọi, có thể nhập **Lý do từ chối** để Nhân sự số điều chỉnh.

![Thẻ Cần bạn phê duyệt hành động cho thao tác create\_order](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_approval_card.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=073cae9326161df92f7ac5ba0e0ed909)

**3. Xem tham số và kết quả**

Sau khi Nhân sự số trả lời, mở **Đã gọi N công cụ** rồi mở tên công cụ để xem **Tham số** đã gửi và **Kết quả** API trả về.

![Chi tiết lần gọi create\_order với tham số và kết quả](https://mintcdn.com/fpt-15dbd015/ZZ_AlSQhekpFaExV/images/eos/agent_tool_result.jpg?fit=max\&auto=format\&n=ZZ_AlSQhekpFaExV\&q=85\&s=b29d9792453ec5d3e2c79599cd900358)

> [!WARNING]
>
> Chạy thử gọi API thật và dùng token thật của Workspace. Khi thử các thao tác ghi hoặc xoá, hãy trỏ Connector tới môi trường thử nghiệm của API.

> [!NOTE]
>
> Thay đổi Connector trong Nhân sự số được tự động lưu vào bản nháp. Người dùng cuối chỉ thấy thay đổi sau khi bạn Publish phiên bản mới của Nhân sự số.

## Gỡ Connector khỏi Nhân sự số

Nhấn biểu tượng **thùng rác** ở dòng Connector trong mục **Kết nối**. Connector được gỡ ngay, không có hộp thoại xác nhận. Connector vẫn còn trong Workspace và có thể gắn lại bất cứ lúc nào.

> [!NOTE]
>
> Khi Connector được import lại ở Space, thao tác bị xoá hoặc đổi tên trong tài liệu mới không còn trong Nhân sự số. Mở lại mục **Kết nối** của Nhân sự số để kiểm tra quyền và chạy thử lại.

## Lỗi thường gặp

| Hiện tượng | Nguyên nhân | Cách xử lý |
| - | - | - |
| Nhân sự số báo cần kết nối tài khoản | Connector gắn kiểu **Theo người dùng** và người dùng chưa kết nối | Người dùng kết nối tài khoản của mình trước khi dùng |

## Xem thêm

> **[Kết nối Custom API trên Space](https://docs-eos.fpt.ai/eos/vi/custom-api-connectors.md)**
>
> Tạo, sửa, import lại và xoá Connector.

> **[Kết nối (Connectors)](https://docs-eos.fpt.ai/eos/vi/connections.md)**
>
> Cách gắn Connector có sẵn và các mức quyền cho công cụ.


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