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

> Kết nối KiotViet với AgentBase để đồng bộ sản phẩm, kiểm tra tồn kho theo thời gian thực, tra cứu đơn hàng, và hiển thị hình ảnh sản phẩm trong chat.

Tích hợp KiotViet cho phép AI agent truy cập trực tiếp vào hệ thống quản lý bán hàng KiotViet của doanh nghiệp. Sau khi kết nối, agent có thể trả lời chính xác về sản phẩm, giá cả, tồn kho, và trạng thái đơn hàng — tất cả từ dữ liệu thực, không phải thông tin cũ.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/integrations/kiotviet-overview.png" alt="Trang tích hợp KiotViet" />
</Frame>

## Yêu cầu

* Gói **Pro** trở lên trên AgentBase.
* Tài khoản KiotViet có quyền truy cập **Public API** (Client ID và Client Secret).

<Info>
  Nếu bạn chưa có thông tin API, đăng nhập KiotViet → **Thiết lập** → **Kết nối API** để tạo ứng dụng và lấy Client ID / Client Secret. Xem [hướng dẫn API của KiotViet](https://www.kiotviet.vn/huong-dan-su-dung-kiotviet/retail-ket-noi-api/public-api/) để biết thêm chi tiết.
</Info>

## Kết nối KiotViet

<Steps>
  <Step title="Mở trang Tích hợp">
    Trên sidebar, chọn **Tích hợp** → nhấn vào card **KiotViet**.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/integrations/kiotviet-card.png" alt="Card KiotViet trên trang Tích hợp" />
    </Frame>
  </Step>

  <Step title="Nhấn Kết nối">
    Nhấn nút **"Kết nối"** để mở dialog nhập thông tin.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/integrations/kiotviet-connect-dialog.png" alt="Dialog kết nối KiotViet" />
    </Frame>
  </Step>

  <Step title="Nhập thông tin API">
    Điền 3 trường bắt buộc:

    | Trường                      | Mô tả                                            | Ví dụ               |
    | --------------------------- | ------------------------------------------------ | ------------------- |
    | **Tên cửa hàng (Retailer)** | Tên đăng nhập KiotViet (không phải tên hiển thị) | `cuahangtoi`        |
    | **Client ID**               | Mã ứng dụng từ trang API KiotViet                | `abc123-def456-...` |
    | **Client Secret**           | Khóa bí mật từ trang API KiotViet                | `xxxxxxxxxx`        |

    <Warning>
      **Tên cửa hàng** là tên đăng nhập KiotViet (ví dụ: `cuahangtoi`), không phải tên hiển thị của cửa hàng. Bạn có thể tìm tên này ở URL khi đăng nhập KiotViet: `https://cuahangtoi.kiotviet.vn`.
    </Warning>
  </Step>

  <Step title="Kiểm tra kết nối">
    AgentBase sẽ tự động kiểm tra kết nối bằng cách xác thực với API KiotViet. Nếu thành công, trạng thái chuyển sang **"Đã kết nối"** (chấm xanh).

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/integrations/kiotviet-connected.png" alt="Trạng thái đã kết nối" />
    </Frame>
  </Step>
</Steps>

## Đồng bộ sản phẩm

Sau khi kết nối, bước tiếp theo là đồng bộ danh mục sản phẩm từ KiotViet vào kiến thức của agent.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/integrations/kiotviet-manage-dialog.png" alt="Dialog quản lý KiotViet" />
</Frame>

<Steps>
  <Step title="Mở dialog quản lý">
    Nhấn **"Quản lý"** trên card KiotViet đã kết nối.
  </Step>

  <Step title="Nhấn Đồng bộ sản phẩm">
    Nhấn nút **"Đồng bộ ngay"** để bắt đầu kéo danh mục sản phẩm từ KiotViet.
  </Step>

  <Step title="Chờ đồng bộ hoàn tất">
    Quá trình đồng bộ thường mất 10–30 giây tùy thuộc vào số lượng sản phẩm. Trạng thái hiển thị trực tiếp trong dialog.
  </Step>

  <Step title="Huấn luyện lại agent">
    Sau khi đồng bộ xong, nhấn **"Huấn luyện lại agent"** để agent học kiến thức mới từ danh mục sản phẩm.

    <Info>
      Nếu bạn không huấn luyện lại, agent sẽ không biết về sản phẩm mới được đồng bộ.
    </Info>
  </Step>
</Steps>

### Dữ liệu được đồng bộ

Mỗi sản phẩm từ KiotViet được đưa vào kiến thức của agent bao gồm:

| Thông tin        | Mô tả                      |
| ---------------- | -------------------------- |
| **Tên sản phẩm** | Tên hiển thị trên KiotViet |
| **Mã sản phẩm**  | Mã SKU / barcode           |
| **Giá bán**      | Giá bán lẻ (VND)           |
| **Phân loại**    | Nhóm hàng / danh mục       |
| **Mô tả**        | Mô tả sản phẩm (nếu có)    |

<Info>
  **Tồn kho không được đồng bộ vào kiến thức tĩnh.** Số lượng tồn kho thay đổi liên tục, nên agent sử dụng tính năng [kiểm tra tồn kho thời gian thực](/docs/user-guides/agent/actions/kiotviet#kiểm-tra-tồn-kho) thay vì dữ liệu cũ từ lần đồng bộ.
</Info>

### Đồng bộ lại

Khi bạn thêm sản phẩm mới, thay đổi giá, hoặc cập nhật mô tả trên KiotViet, hãy:

1. Nhấn **"Đồng bộ ngay"** để kéo dữ liệu mới.
2. Nhấn **"Huấn luyện lại agent"** để áp dụng thay đổi.

<Tip>
  Gói Pro bao gồm tính năng **Tự động đồng bộ hàng tuần** — agent tự động cập nhật danh mục sản phẩm mà không cần thao tác thủ công.
</Tip>

## Tính năng sau khi kết nối

Sau khi kết nối và đồng bộ, agent tự động có các khả năng sau:

<CardGroup cols={2}>
  <Card title="Trả lời về sản phẩm" icon="tag">
    Agent trả lời câu hỏi về tên, giá, mô tả sản phẩm dựa trên danh mục đã đồng bộ từ KiotViet.
  </Card>

  <Card title="Kiểm tra tồn kho" icon="warehouse">
    Khi khách hỏi "Còn hàng không?", agent gọi API KiotViet để trả lời với số lượng tồn kho chính xác tại thời điểm hỏi.
  </Card>

  <Card title="Hiển thị hình ảnh sản phẩm" icon="image">
    Khi kiểm tra tồn kho, agent hiển thị hình ảnh sản phẩm từ KiotViet ngay trong cửa sổ chat — giúp khách hàng nhận diện đúng sản phẩm.
  </Card>

  <Card title="Tra cứu đơn hàng" icon="truck">
    Khách hàng có thể hỏi trạng thái đơn hàng bằng mã đơn hàng, mã hóa đơn, hoặc số điện thoại. Agent trả lời ngay với thông tin từ KiotViet.
  </Card>
</CardGroup>

Xem chi tiết về cách các tính năng này hoạt động trong cuộc trò chuyện tại trang [Hành động KiotViet](/docs/user-guides/agent/actions/kiotviet).

## Nâng cấp gói KiotViet

Tích hợp KiotViet có 2 cấp độ:

| Gói                               | Tính năng                                                     |
| --------------------------------- | ------------------------------------------------------------- |
| **Cơ bản** (mặc định khi kết nối) | Đồng bộ sản phẩm thủ công, kiểm tra tồn kho, tra cứu đơn hàng |
| **Nâng cao**                      | Tự động đồng bộ hàng tuần, ưu tiên hỗ trợ kỹ thuật            |

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/integrations/kiotviet-upgrade.png" alt="Dialog nâng cấp KiotViet" />
</Frame>

## Ngắt kết nối

<Steps>
  <Step title="Mở quản lý">
    Nhấn **"Quản lý"** trên card KiotViet.
  </Step>

  <Step title="Nhấn Ngắt kết nối">
    Cuộn xuống cuối dialog và nhấn **"Ngắt kết nối"**.
  </Step>

  <Step title="Xác nhận">
    Xác nhận ngắt kết nối. Dữ liệu sản phẩm đã đồng bộ sẽ bị xóa khỏi nguồn dữ liệu.
  </Step>
</Steps>

<Warning>
  Sau khi ngắt kết nối, agent sẽ không còn khả năng kiểm tra tồn kho hoặc tra cứu đơn hàng. Bạn cần huấn luyện lại agent để xóa kiến thức sản phẩm cũ.
</Warning>

## Xử lý sự cố

| Vấn đề                            | Giải pháp                                                                                                       |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Kết nối thất bại                  | Kiểm tra lại **Tên cửa hàng**, **Client ID** và **Client Secret**. Đảm bảo API đã được kích hoạt trên KiotViet. |
| Đồng bộ không có sản phẩm         | Đảm bảo cửa hàng KiotViet có sản phẩm đang hoạt động (không bị ẩn).                                             |
| Tồn kho không chính xác           | Kiểm tra KiotViet có cập nhật tồn kho cho chi nhánh đúng. Agent lấy tổng tồn kho từ tất cả chi nhánh.           |
| Agent không dùng dữ liệu KiotViet | Đảm bảo bạn đã nhấn **"Huấn luyện lại agent"** sau khi đồng bộ.                                                 |

<Tip>
  Nếu gặp lỗi liên tục, thử ngắt kết nối và kết nối lại. Điều này sẽ tạo lại token xác thực từ đầu.
</Tip>