> For the complete documentation index, see [llms.txt](https://docs.dos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dos.ai/dosclaw/plugins-and-connectors/ecommerce/kiotviet.md).

# KiotViet Retail POS

Connect KiotViet—Vietnam's leading retail point-of-sale (POS) and inventory management software—to DOSClaw AI agents. Enable unified online-to-offline (O2O) stock management, branch inventory inquiries, price list checks, and offline order tracking.

## Capabilities & MCP Tools

| MCP Tool             | Operation | Description                                                                                |
| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
| `search_products`    | Read      | Search product catalog by barcode, SKU, or name across POS inventory.                      |
| `get_branch_stock`   | Read      | Query real-time inventory levels broken down by specific retail branches/stores.           |
| `get_product_prices` | Read      | Look up retail prices, wholesale tiers, and active promotional discounts.                  |
| `check_order_status` | Read      | Look up customer invoices and delivery tickets by KiotViet invoice code (e.g. `HD000123`). |

***

## Prerequisites

1. An active **KiotViet** account (Retail, F\&B, or Pharmacy edition).
2. KiotViet Open API access enabled for your retailer (`https://developer.kiotviet.vn/`).
3. **Retailer Name**, **Client ID**, and **Client Secret** issued by KiotViet.

***

## Setup Guide

### Step 1: Retrieve KiotViet API Credentials

1. Log in to your KiotViet management portal (`https://manage.kiotviet.vn/`).
2. Go to **Thiết lập** (Settings) $\rightarrow$ **Thiết lập cửa hàng** $\rightarrow$ **Thiết lập tính năng**.
3. Under **Ứng dụng & Tích hợp**, click **Tạo ứng dụng kết nối** (Create connection app) or register on KiotViet Developer Portal.
4. Note your:
   * **Retailer (Tên gian hàng)**: The identifier in your store URL (e.g. `cuahangthoitrang`).
   * **Client ID**: Public application client key.
   * **Client Secret**: Private secret key.

### Step 2: Connect in DOS.AI Dashboard

1. In the **DOS.AI Dashboard**, open **Integrations** $\rightarrow$ **KiotViet Retail POS**.
2. Click **Connect KiotViet**.
3. Fill in:
   * **Retailer Name**
   * **Client ID**
   * **Client Secret**
4. Click **Test & Connect**. DOS.AI verifies connectivity with KiotViet's OAuth Token endpoint (`https://id.kiotviet.vn/connect/token`).

### Step 3: Bind to Your AI Agent

1. Open your agent $\rightarrow$ **Integrations** $\rightarrow$ enable **KiotViet**.
2. (Optional) Set the **Default Branch ID** if your bot represents a specific store location.
3. Save changes.

***

## Example O2O Inquiries

### Branch Stock Check

> **Customer**: "Shop xem giúp em chi nhánh Cầu Giấy còn mẫu giày sneaker trắng size 38 không ạ?"\
> **AI Agent**: Calls `get_branch_stock({ "sku": "GI-SNK-TR-38", "branch": "Cầu Giấy" })`\
> **Response**: "Dạ chào bạn, chi nhánh Cầu Giấy (125 Cầu Giấy) hiện còn 3 đôi size 38 ạ! Bạn có muốn shop giữ hàng trước để bạn qua thử không ạ?"

### Price & Barcode Search

> **Customer**: "Quét mã vạch 8935001234567 xem giá bao nhiêu?"\
> **AI Agent**: Calls `search_products({ "barcode": "8935001234567" })`\
> **Response**: "Mã vạch 8935001234567 là sản phẩm **Nước hoa vùng kín Foellie Eau de Bijou 5ml**, giá niêm yết là 210.000đ ạ."

***

## Troubleshooting

| Issue                             | Cause                         | Solution                                                                                                  |
| --------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| "Invalid retailer or credentials" | Typos in Client ID/Secret     | Copy the exact credentials from KiotViet settings without leading/trailing spaces.                        |
| Stock numbers out of date         | KiotViet inventory sync delay | KiotViet stock caches for up to 60 seconds; verify direct in KiotViet POS if recent transaction occurred. |
| Inactive branch error             | Branch ID closed or archived  | Verify in KiotViet admin that the branch is marked as active.                                             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.dos.ai/dosclaw/plugins-and-connectors/ecommerce/kiotviet.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.