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

# KiotViet

> Kiểm tra tồn kho, tra cứu đơn hàng, hiển thị hình ảnh sản phẩm — tất cả từ dữ liệu KiotViet thời gian thực, ngay trong cuộc trò chuyện.

Hành động KiotViet cho phép AI agent truy cập trực tiếp vào hệ thống KiotViet để trả lời khách hàng bằng dữ liệu thời gian thực — không phải thông tin cũ. Khi khách hỏi "Còn hàng không?" hoặc "Đơn hàng của tôi ở đâu?", agent tự động gọi API KiotViet và trả lời ngay.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/actions/kiotviet-overview.png" alt="Trang hành động KiotViet" />
</Frame>

<Info>
  Hành động KiotViet được kích hoạt tự động khi bạn [kết nối KiotViet](/docs/user-guides/integrations/kiotviet) trong phần Tích hợp. Không cần cấu hình riêng — tất cả quản lý tại trang Tích hợp.
</Info>

## Tính năng

### Kiểm tra tồn kho

Khi khách hàng hỏi về sản phẩm có còn hàng hay không, agent tự động gọi API KiotViet để kiểm tra số lượng tồn kho tại thời điểm hỏi.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/actions/kiotviet-stock-check.png" alt="Kiểm tra tồn kho trong chat" />
</Frame>

**Cách hoạt động:**

1. Khách hỏi: *"Áo thun trắng còn hàng không?"*
2. Agent gọi API `/products` của KiotViet với tên sản phẩm.
3. KiotViet trả về số lượng tồn kho từ tất cả chi nhánh.
4. Agent trả lời: *"Áo thun trắng: còn 15 cái."* kèm hình ảnh sản phẩm.

**Tìm kiếm thông minh:**

* Tìm theo **tên sản phẩm** hoặc **mã sản phẩm (SKU)**.
* Hỗ trợ tìm kiếm **không dấu** — khách gõ "ao thun" vẫn tìm được "Áo thun".
* Tìm trên **toàn bộ danh mục**, không giới hạn 100 sản phẩm đầu tiên.

<Tip>
  Agent hiển thị tồn kho theo từng chi nhánh nếu cửa hàng có nhiều chi nhánh, giúp khách biết chính xác nơi có hàng.
</Tip>

### Hiển thị hình ảnh sản phẩm

Khi kiểm tra tồn kho, agent tự động hiển thị hình ảnh sản phẩm từ KiotViet ngay trong cửa sổ chat. Điều này giúp khách hàng xác nhận đúng sản phẩm mình đang tìm.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/actions/kiotviet-product-image.png" alt="Hình ảnh sản phẩm trong chat" />
</Frame>

**Lưu ý:**

* Hình ảnh lấy từ thư viện ảnh sản phẩm trên KiotViet — nếu sản phẩm chưa có ảnh, agent chỉ hiển thị thông tin dạng văn bản.
* Chỉ hiển thị ảnh đầu tiên (ảnh chính) của mỗi sản phẩm.

### Tra cứu đơn hàng

Khách hàng có thể hỏi về trạng thái đơn hàng bằng nhiều cách khác nhau.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/actions/kiotviet-order-lookup.png" alt="Tra cứu đơn hàng trong chat" />
</Frame>

**Các cách tra cứu:**

| Phương thức       | Ví dụ khách hỏi               | Cách hoạt động                             |
| ----------------- | ----------------------------- | ------------------------------------------ |
| **Mã đơn hàng**   | "Đơn DH001234 đang ở đâu?"    | Agent tìm trực tiếp bằng mã                |
| **Mã hóa đơn**    | "Kiểm tra hóa đơn HD005678"   | Agent tìm trong danh sách hóa đơn          |
| **Số điện thoại** | "Tôi đặt bằng SĐT 0901234567" | Agent tìm khách hàng, rồi lấy đơn gần nhất |

**Thông tin trả về:**

* Mã đơn hàng / hóa đơn
* Trạng thái (ví dụ: *"Đang giao hàng"*, *"Hoàn thành"*)
* Tên khách hàng
* Tổng tiền
* Danh sách sản phẩm trong đơn (tên, số lượng, giá)

<Info>
  Nếu khách không cung cấp mã đơn hàng hoặc số điện thoại, agent sẽ tự động hỏi trước khi tra cứu — đảm bảo tìm đúng đơn.
</Info>

### Đồng bộ sản phẩm vào kiến thức

Ngoài tra cứu thời gian thực, tích hợp KiotViet cũng đồng bộ toàn bộ danh mục sản phẩm (tên, mã, giá, phân loại, mô tả) vào kiến thức của agent. Nhờ đó agent có thể trả lời câu hỏi chung về sản phẩm mà không cần gọi API mỗi lần.

**Ví dụ:**

* *"Có những loại áo nào?"* → Agent trả lời từ kiến thức đã đồng bộ.
* *"Áo thun trắng giá bao nhiêu?"* → Agent trả lời từ kiến thức đã đồng bộ.
* *"Áo thun trắng còn bao nhiêu?"* → Agent gọi API KiotViet (dữ liệu thời gian thực).

<Info>
  Xem cách đồng bộ sản phẩm tại trang [Tích hợp KiotViet](/docs/user-guides/integrations/kiotviet#đồng-bộ-sản-phẩm).
</Info>

## Cấu hình

Hành động KiotViet **không cần cấu hình riêng** — nó được kích hoạt tự động khi bạn kết nối KiotViet trong phần Tích hợp. Để thay đổi hoặc quản lý, hãy vào trang [Tích hợp](/docs/user-guides/integrations/kiotviet).

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/actions/kiotviet-link-to-integrations.png" alt="Liên kết đến trang Tích hợp" />
</Frame>

## Kiểm tra trong Playground

Sau khi kết nối KiotViet và đồng bộ sản phẩm, vào [Playground](/docs/user-guides/agent/playground) để thử nghiệm:

<Steps>
  <Step title="Thử kiểm tra tồn kho">
    Hỏi: *"Sản phẩm X còn hàng không?"* — agent phải trả lời với số lượng chính xác và hình ảnh sản phẩm (nếu có).
  </Step>

  <Step title="Thử tra cứu đơn hàng">
    Hỏi: *"Kiểm tra đơn hàng DH001234"* — agent phải trả lời với trạng thái và chi tiết đơn.
  </Step>

  <Step title="Thử tìm kiếm không dấu">
    Hỏi: *"ao thun con khong?"* — agent phải tìm đúng sản phẩm dù khách không gõ dấu tiếng Việt.
  </Step>

  <Step title="Thử câu hỏi chung về sản phẩm">
    Hỏi: *"Có những sản phẩm nào?"* — agent phải trả lời từ kiến thức đã đồng bộ.
  </Step>
</Steps>

## Mẹo sử dụng hiệu quả

<CardGroup cols={2}>
  <Card title="Đồng bộ thường xuyên" icon="rotate">
    Khi thêm sản phẩm mới hoặc thay đổi giá trên KiotViet, nhớ đồng bộ lại và huấn luyện lại agent để kiến thức luôn cập nhật.
  </Card>

  <Card title="Thêm ảnh sản phẩm trên KiotViet" icon="image">
    Agent chỉ hiển thị hình ảnh nếu sản phẩm có ảnh trên KiotViet. Thêm ảnh chất lượng tốt để khách hàng có trải nghiệm tốt hơn.
  </Card>

  <Card title="Hướng dẫn trong system prompt" icon="message-circle-dashed">
    Thêm vào system prompt: "Khi khách hỏi về sản phẩm cụ thể có còn hàng hay không, luôn kiểm tra tồn kho thời gian thực thay vì trả lời từ kiến thức cũ."
  </Card>

  <Card title="Đào tạo nhân viên" icon="users">
    Hướng dẫn nhân viên cửa hàng cách khách hàng có thể tra cứu đơn hàng qua chat — để nhân viên có thể hướng dẫn khách khi cần.
  </Card>
</CardGroup>