# Tham chiếu API REST Procurize.AI

**Truy cập cơ sở tri thức của bạn một cách lập trình – tài liệu, bảng câu hỏi, RAG và báo cáo – bằng token API của bạn.**

> **Áp dụng cho:** API Procurize.AI v1  
> **Xác thực:** Khóa API qua header `X-API-Key` (xem [API Tokens](/api-tokens/) để quản lý token)  
> **URL cơ sở:** `https://api.procurize.com`

## Tổng quan

API REST của Procurize.AI cung cấp quyền truy cập lập trình vào các tính năng chính của nền tảng. Nó cho phép bạn tích hợp Procurize.AI với hệ thống nội bộ, tự động hoá quản lý cơ sở tri thức và xây dựng quy trình làm việc tùy chỉnh.

**Các mô-đun được hỗ trợ (xác thực bằng token):**

- [**RagArticle**](#ragarticle) – quản lý tài liệu
- [**RagFaq**](#ragfaq) – quản lý mục FAQ
- [**RagQuery**](#ragquery) – thực hiện truy vấn RAG

## Xác thực

Tất cả các endpoint yêu cầu xác thực đều cần một token API được truyền trong header của yêu cầu.

| Header | Giá trị |
|--------|---------|
| `X-API-Key` | `<YOUR_API_TOKEN>` |

**Ví dụ:**
```bash
curl -X GET "https://api.procurize.com/v1/..." \
  -H "X-API-Key: your-api-token-here"
```

> 💡 Token được gắn với tổ chức của bạn – bạn không cần chỉ định ID tổ chức trong yêu cầu .

## URL cơ sở

Tất cả các endpoint API REST được phục vụ dưới:
```
https://api.procurize.com
```

## Xử lý lỗi

API sử dụng các mã trạng thái HTTP tiêu chuẩn.

| Mã | Ý nghĩa |
|------|---------|
| `200 OK` | Yêu cầu thành công |
| `201 Created` | Tài nguyên được tạo thành công |
| `204 No Content` | Yêu cầu thành công, không có nội dung phản hồi |
| `400 Bad Request` | Tham số không hợp lệ hoặc yêu cầu sai định dạng |
| `401 Unauthorized` | Thiếu hoặc token API không hợp lệ |
| `403 Forbidden` | Token không có quyền thực hiện hành động này |
| `404 Not Found` | Tài nguyên không tồn tại |
| `500 Internal Server Error` | Lỗi máy chủ không mong muốn |

Phản hồi lỗi bao gồm mã lỗi có thể đọc được bởi máy và thông báo có thể đọc được bởi con người.

## Tham chiếu mô-đun

### RagArticle

#### GET /questionnaire/rag/articles/summary

**Tóm tắt:** Tóm tắt cho trang Chủ

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| proj | query | string (uuid) | Không | ID dự án. |

**Phản hồi (200):**
```json
{
  "active": 5
}
```

---

#### GET /questionnaire/rag/articles/total

**Tóm tắt:** Số lượng bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| q | query | string | Không | Lọc theo tên hoặc mã bài viết. |
| state | query | array | Không | Lọc theo trạng thái. |
| project | query | array | Không | Lọc theo dự án. |
| type | query | array | Không | Lọc theo loại tài liệu. |

**Phản hồi (200):**
```json
42
```

---

#### GET /questionnaire/rag/articles/list

**Tóm tắt:** Lấy danh sách bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| q | query | string | Không | Lọc theo tên hoặc mã bài viết. |
| state | query | array | Không | Lọc theo trạng thái. |
| project | query | array | Không | Lọc theo dự án. |
| type | query | array | Không | Lọc theo loại tài liệu. |
| s | query | string | Không | Trường sắp xếp. |
| asc | query | boolean | Không | Sắp xếp tăng dần. |
| ps | query | integer (int32) | Không | Kích thước trang. |
| p | query | integer (int32) | Không | Số trang bắt đầu từ 1. |

**Phản hồi (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 42,
    "totalPages": 5
  },
  "items": [
    {
      "code": "ART-001",
      "org": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Article Title",
      "description": "Article description",
      "documentTypes": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "Type Name",
          "plural": "Type Names",
          "count": 5
        }
      ],
      "size": 150,
      "revision": {
        "id": "00000000-0000-0000-0000-000000000000",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "rev": 3,
        "date": "2025-01-15T10:30:00Z",
        "author": {
          "id": "user123",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "login": "johndoe",
          "ra": true
        },
        "authorName": "John Doe",
        "analysisSummary": {
          "id": "00000000-0000-0000-0000-000000000000",
          "initiator": {
            "id": "user123",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "login": "johndoe",
            "ra": true
          },
          "created": "2025-01-15T10:30:00Z",
          "state": "Completed",
          "stateDate": "2025-01-15T10:35:00Z",
          "stateDetails": "Analysis completed successfully",
          "operationId": "op-12345"
        }
      },
      "type": "Article",
      "state": "Active",
      "projects": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "items": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "isShared": false
    }
  ]
}
```

---

#### POST /questionnaire/rag/file-to-md

**Tóm tắt:** Trả về nội dung Markdown từ tệp

**Yêu cầu (multipart/form-data):**
```json
{
  "url": "https://example.com/file.pdf",
  "file": "binary"
}
```

**Phản hồi (200):**
```json
"Markdown content from file"
```

---

#### POST /questionnaire/rag/article/create

**Tóm tắt:** Tạo một bài viết

**Yêu cầu (multipart/form-data):**
```json
{
  "code": "ART-001",
  "name": "Article Title",
  "description": "Article description",
  "content": "# Article Content\n\nThis is the article content.",
  "url": "https://example.com/file.pdf",
  "file": "binary"
}
```

**Phản hồi (200):**
```json
{
  "code": "ART-001",
  "org": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Article Title",
  "description": "Article description",
  "documentTypes": null,
  "size": 150,
  "revision": null,
  "type": "Article",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### GET /questionnaire/rag/article/check

**Tóm tắt:** Kiểm tra sự tồn tại của bài viết.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |

**Phản hồi (200):**
```json
true
```

---

#### GET /questionnaire/rag/article-info

**Tóm tắt:** Lấy thông tin bài viết theo mã.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |

**Phản hồi (200):**
```json
{
  "code": "ART-001",
  "org": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Article Title",
  "description": "Article description",
  "documentTypes": null,
  "size": 150,
  "revision": null,
  "type": "Article",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### GET /questionnaire/rag/article

**Tóm tắt:** Lấy nội dung bài viết theo mã

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |
| format | query | string | Không | Nếu true, trả về nội dung HTML trong body phản hồi. Ngược lại trả về nội dung Markdown. |
| split | query | boolean | Không | Nếu true, trả về nội dung được tách theo các phần tử RAG. |
| css | query | boolean | Không | Nếu true, trả về nội dung HTML/PDF kèm CSS. |

**Phản hồi (200):**
```json
"# Article Title\n\nThis is the article content in Markdown format."
```

#### POST /questionnaire/rag/article

**Tóm tắt:** Cập nhật siêu dữ liệu bài viết

**Yêu cầu:**
```json
{
  "code": "ART-001",
  "name": "Updated Article Title",
  "description": "Updated description",
  "projects": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "documentTypes": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Type Name",
      "plural": "Type Names"
    }
  ],
  "isShared": true,
  "state": "Active"
}
```

**Phản hồi (200):**
```json
{}
```

#### DELETE /questionnaire/rag/article

**Tóm tắt:** Xóa bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |

---

#### GET /questionnaire/rag/article/pdf

**Tóm tắt:** Lấy bài viết dưới dạng PDF theo mã

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |

**Phản hồi (200):**
```json
(pdf binary)
```

---

#### GET /questionnaire/rag/article/content

**Tóm tắt:** Lấy nội dung bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |

**Phản hồi (200):**
```json
{
  "content": "# Article Title\n\nContent here."
}
```

---

#### POST /questionnaire/rag/article/content

**Tóm tắt:** Cập nhật nội dung bài viết

**Yêu cầu (multipart/form-data):**
```json
{
  "code": "ART-001",
  "content": "# Updated Content",
  "file": "binary"
}
```

---

#### POST /questionnaire/rag/plural

**Tóm tắt:** Lấy dạng số nhiều của danh từ

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| noun | query | string | Không | Danh từ cần chuyển sang số nhiều. |

**Phản hồi (200):**
```json
{
  "plural": "Articles"
}
```

---

#### POST /questionnaire/rag/article/find-types

**Tóm tắt:** Phân tích bài viết bằng AI và trả về các loại của chúng

**Yêu cầu (multipart/form-data):**
```json
{
  "code": "ART-001",
  "content": "# Article Content"
}
```

**Phản hồi (200):**
```json
[
  {
    "plural": "Types"
  }
]
```

---

#### POST /questionnaire/rag/article/format-with-ai

**Tóm tắt:** Định dạng nội dung bài viết bằng AI

**Yêu cầu (multipart/form-data):**
```json
{
  "code": "ART-001",
  "content": "# Article Content"
}
```

**Phản hồi (200):**
```json
{
  "formattedContent": "# Formatted Article Content"
}
```

---

#### POST /questionnaire/rag/article/improve-on-suggestions

**Tóm tắt:** Cải thiện tài liệu dựa trên đề xuất

**Yêu cầu (multipart/form-data):**
```json
{
  "suggestions": [
    {
      "sectionTitle": "Introduction",
      "suggestion": "Add more details here."
    }
  ],
  "code": "ART-001",
  "content": "# Article Content"
}
```

**Phản hồi (200):**
```json
{
  "improvedContent": "# Improved Content"
}
```

---

#### GET /questionnaire/rag/article/parts

**Tóm tắt:** Trả về danh sách các phần của bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | query | array | Có | Danh sách các phần của bài viết. |

**Phản hồi (200):**
```json
[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "code": "part-1",
    "title": "Introduction",
    "orderNumber": 1,
    "content": "Introduction content."
  }
]
```

---

#### GET /questionnaire/rag/article/revisions

**Tóm tắt:** Trả về danh sách các phiên bản bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |

**Phản hồi (200):**
```json
[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "collectionId": "00000000-0000-0000-0000-000000000000",
    "rev": 1,
    "date": "2025-01-15T10:30:00Z",
    "author": {
      "id": "user123",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "login": "johndoe",
      "ra": true
    },
    "authorName": "John Doe",
    "analysisSummary": {
      "id": "00000000-0000-0000-0000-000000000000",
      "initiator": {
        "id": "user123",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "login": "johndoe",
        "ra": true
      },
      "created": "2025-01-15T10:30:00Z",
      "state": "Completed",
      "stateDate": "2025-01-15T10:35:00Z",
      "stateDetails": "Analysis completed",
      "operationId": "op-12345"
    }
  }
]
```

---

#### GET /questionnaire/rag/article/revisions/info/{id}

**Tóm tắt:** Lấy thông tin phiên bản bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | path | string (uuid) | Có | ID của phiên bản. |

**Phản hồi (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "collectionId": "00000000-0000-0000-0000-000000000000",
  "rev": 1,
  "date": "2025-01-15T10:30:00Z",
  "author": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "authorName": "John Doe",
  "analysisSummary": {
    "id": "00000000-0000-0000-0000-000000000000",
    "initiator": {
      "id": "user123",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "login": "johndoe",
      "ra": true
    },
    "created": "2025-01-15T10:30:00Z",
    "state": "Completed",
    "stateDate": "2025-01-15T10:35:00Z",
    "stateDetails": "Analysis completed",
    "operationId": "op-12345"
  }
}
```

---

#### GET /questionnaire/rag/article/revisions/{id}

**Tóm tắt:** Lấy nội dung phiên bản bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | path | string (uuid) | Có | ID của phiên bản. |

**Phản hồi (200):**
```json
"# Article Revision Content\n\nPrevious version."
```

---

#### GET /questionnaire/rag/article/analyze

**Tóm tắt:** Phân tích nội dung bài viết bằng AI

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bài viết. |
| rev | query | integer (int32) | Không | Số phiên bản. |
| force | query | boolean | Không | Buộc tạo phân tích mới và xóa kết quả phân tích chưa hoàn thành nếu có. |

**Phản hồi (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "initiator": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "created": "2025-01-15T10:30:00Z",
  "state": "Completed",
  "stateDate": "2025-01-15T10:35:00Z",
  "stateDetails": "Analysis completed",
  "operationId": "op-12345"
}
```

---

#### GET /questionnaire/rag/article/analyze/{id}

**Tóm tắt:** Lấy kết quả phân tích bài viết

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | path | string (uuid) | Có | ID của phân tích. |

**Phản hồi (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "initiator": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "created": "2025-01-15T10:30:00Z",
  "state": "Completed",
  "stateDate": "2025-01-15T10:35:00Z",
  "stateDetails": "Analysis completed",
  "operationId": "op-12345",
  "fragments": [
    "fragment-1",
    "fragment-2"
  ],
  "ownInconcies": "Own inconsistencies found",
  "ragInconcies": "RAG inconsistencies found",
  "proposals": "Improvement proposals"
}
```

---

#### GET /questionnaire/rag/messages/list

**Tóm tắt:** Liệt kê tất cả tin nhắn

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | query | string (uuid) | Có | ID của Bộ sưu tập RAG. |
| item | query | string (uuid) | Không | ID của mục RAG. |
| message | query | string (uuid) | Không | ID của tin nhắn. |
| asc | query | boolean | Không | Sắp xếp tăng dần. |
| ps | query | integer (int32) | Không | Kích thước trang. |
| p | query | integer (int32) | Không | Số trang bắt đầu từ 1. |

**Phản hồi (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 5,
    "totalPages": 1
  },
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "replyTo": null,
      "questionnaire": null,
      "section": null,
      "question": null,
      "ragCollection": "00000000-0000-0000-0000-000000000000",
      "ragItem": "00000000-0000-0000-0000-000000000000",
      "targetId": "00000000-0000-0000-0000-000000000000",
      "targetType": "Question",
      "targetNum": 1,
      "author": {
        "id": "user123",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "login": "johndoe",
        "ra": true
      },
      "text": "Message content",
      "created": "2025-01-15T10:30:00Z",
      "updated": "2025-01-15T10:30:00Z",
      "replies": 0
    }
  ]
}
```

---

#### POST /questionnaire/rag/messages/add

**Tóm tắt:** Thêm tin nhắn mới

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | query | string (uuid) | Có | ID của Bộ sưu tập RAG. |
| item | query | string (uuid) | Không | ID của mục RAG. |
| message | query | string (uuid) | Không | ID của tin nhắn để trả lời. |

**Yêu cầu:**
```json
{
  "text": "New message content"
}
```

**Phản hồi (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "replyTo": null,
  "questionnaire": null,
  "section": null,
  "question": null,
  "ragCollection": "00000000-0000-0000-0000-000000000000",
  "ragItem": "00000000-0000-0000-0000-000000000000",
  "targetId": "00000000-0000-0000-0000-000000000000",
  "targetType": "Question",
  "targetNum": 1,
  "author": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "text": "New message content",
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:30:00Z",
  "replies": 0
}
```

---

#### POST /questionnaire/rag/message

**Tóm tắt:** Cập nhật tin nhắn hiện có

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| c | query | string (uuid) | Có | ID của Bộ sưu tập RAG. |
| id | query | string (uuid) | Có | ID của tin nhắn. |

**Yêu cầu:**
```json
{
  "text": "Updated message content"
}
```

**Phản hồi (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "replyTo": null,
  "questionnaire": null,
  "section": null,
  "question": null,
  "ragCollection": "00000000-0000-0000-0000-000000000000",
  "ragItem": "00000000-0000-0000-0000-000000000000",
  "targetId": "00000000-0000-0000-0000-000000000000",
  "targetType": "Question",
  "targetNum": 1,
  "author": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "text": "Updated message content",
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:45:00Z",
  "replies": 0
}
```

#### DELETE /questionnaire/rag/message

**Tóm tắt:** Xóa tin nhắn hiện có

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| id | query | string (uuid) | Có | ID của tin nhắn. |

**Phản hồi (200):**
```json
{}
```

---

### RagFaq

#### GET /questionnaire/rag/faq-collections/summary

**Tóm tắt:** Tóm tắt cho trang Chủ

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| proj | query | string (uuid) | Không | ID dự án. |

**Phản hồi (200):**
```json
{
  "active": 3
}
```

---

#### GET /questionnaire/rag/faq-collections/total

**Tóm tắt:** Số lượng bộ sưu tập FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| q | query | string | Không | Lọc theo tên hoặc mã bộ sưu tập. |
| state | query | array | Không | Lọc theo trạng thái. |
| project | query | array | Không | Lọc theo dự án. |

**Phản hồi (200):**
```json
3
```

---

#### GET /questionnaire/rag/faq-collections/list

**Tóm tắt:** Lấy danh sách bộ sưu tập FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| q | query | string | Không | Lọc theo tên hoặc mã bộ sưu tập. |
| state | query | array | Không | Lọc theo trạng thái. |
| project | query | array | Không | Lọc theo dự án. |
| s | query | string | Không | Trường sắp xếp. |
| asc | query | boolean | Không | Sắp xếp tăng dần. |
| ps | query | integer (int32) | Không | Kích thước trang. |
| p | query | integer (int32) | Không | Số trang bắt đầu từ 1. |

**Phản hồi (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 3,
    "totalPages": 1
  },
  "items": [
    {
      "code": "FAQ-001",
      "org": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "FAQ Collection",
      "description": "FAQ collection description",
      "documentTypes": null,
      "size": 5,
      "revision": null,
      "type": "Faq",
      "state": "Active",
      "projects": null,
      "items": null,
      "isShared": false
    }
  ]
}
```

---

#### GET /questionnaire/rag/faq-collections/find-items

**Tóm tắt:** Tìm mục FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| q | query | string | Có | Lọc theo câu hỏi. |
| project | query | string (uuid) | Không | Lọc theo dự án. |
| ps | query | integer (int32) | Không | Kích thước trang. |
| p | query | integer (int32) | Không | Số trang bắt đầu từ 1. |

**Phản hồi (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 5,
    "totalPages": 1
  },
  "items": [
    {
      "index": 0,
      "question": "What is this product?",
      "answer": "This is a great product.",
      "comment": "Product FAQ",
      "state": "Active"
    }
  ]
}
```

---

#### POST /questionnaire/rag/faq-collection/create

**Tóm tắt:** Tạo bộ sưu tập FAQ mới.

**Yêu cầu (multipart/form-data):**
```json
{
  "code": "FAQ-001",
  "name": "FAQ Collection",
  "description": "FAQ collection description",
  "content": "Content here",
  "file": "binary"
}
```

**Phản hồi (200):**
```json
{
  "code": "FAQ-001",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "FAQ Collection",
  "description": "FAQ collection description",
  "documentTypes": null,
  "size": 5,
  "revision": null,
  "type": "Faq",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### POST /questionnaire/rag/faq-collection

**Tóm tắt:** Cập nhật siêu dữ liệu bộ sưu tập FAQ.

**Yêu cầu:**
```json
{
  "code": "FAQ-001",
  "name": "Updated FAQ Collection",
  "description": "Updated description",
  "projects": null,
  "documentTypes": null,
  "isShared": false,
  "state": "Active"
}
```

#### DELETE /questionnaire/rag/faq-collection

**Tóm tắt:** Xóa bộ sưu tập FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |

#### GET /questionnaire/rag/faq-collection

**Tóm tắt:** Lấy bộ sưu tập FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |

**Phản hồi (200):**
```json
{
  "code": "FAQ-001",
  "org": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "FAQ Collection",
  "description": "FAQ collection description",
  "documentTypes": null,
  "size": 5,
  "revision": null,
  "type": "Faq",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### GET /questionnaire/rag/faq-collection/check

**Tóm tắt:** Kiểm tra tồn tại của bộ sưu tập FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |

**Phản hồi (200):**
```json
true
```

---

#### GET /questionnaire/rag/faq-collection/items-total

**Tóm tắt:** Số lượng mục FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |
| q | query | string | Không | Lọc theo nội dung mục FAQ. |

**Yêu cầu:**
```json
["Active", "Default"]
```

**Phản hồi (200):**
```json
5
```

---

#### GET /questionnaire/rag/faq-collection/items

**Tóm tắt:** Lấy danh sách mục FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |
| q | query | string | Không | Lọc theo nội dung mục FAQ. |
| state | query | array | Không | Lọc theo trạng thái. |
| s | query | string | Không | Trường sắp xếp. |
| asc | query | boolean | Không | Sắp xếp tăng dần. |
| ps | query | integer (int32) | Không | Kích thước trang. |
| p | query | integer (int32) | Không | Số trang bắt đầu từ 1. |

**Phản hồi (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 5,
    "totalPages": 1
  },
  "items": [
    {
      "index": 0,
      "question": "What is this product?",
      "answer": "This is a great product.",
      "comment": "Product FAQ",
      "state": "Active"
    }
  ]
}
```

---

#### POST /questionnaire/rag/faq-collection/item/create

**Tóm tắt:** Tạo mục FAQ mới.

**Yêu cầu:**
```json
{
  "code": "FAQ-001",
  "index": 0,
  "question": "What is this product?",
  "answer": "This is a great product.",
  "comment": "Product FAQ",
  "state": "Active"
}
```

**Phản hồi (200):**
```json
{
  "index": 0,
  "question": "What is this product?",
  "answer": "This is a great product.",
  "comment": "Product FAQ",
  "state": "Active"
}
```

---

#### GET /questionnaire/rag/faq-collection/item

**Tóm tắt:** Lấy mục FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |
| index | query | integer (int32) | Có | Chỉ mục (bắt đầu từ 0) của mục FAQ trong bộ sưu tập. |

**Phản hồi (200):**
```json
{
  "index": 0,
  "question": "What is this product?",
  "answer": "This is a great product.",
  "comment": "Product FAQ",
  "state": "Active"
}
```

#### POST /questionnaire/rag/faq-collection/item

**Tóm tắt:** Cập nhật mục FAQ.

**Yêu cầu:**
```json
{
  "code": "FAQ-001",
  "index": 0,
  "newIndex": 1,
  "question": "Updated question?",
  "answer": "Updated answer.",
  "comment": "Updated comment",
  "state": "Active"
}
```

#### DELETE /questionnaire/rag/faq-collection/item

**Tóm tắt:** Xóa mục FAQ.

**Tham số:**
| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
|------|-------|------|----------|-------|
| code | query | string | Có | Mã của bộ sưu tập. |
| index | query | integer (int32) | Có | Chỉ mục (bắt đầu từ 0) của mục FAQ trong bộ sưu tập. |

---

### RagQuery

#### POST /questionnaire/rag/query

**Tóm tắt:** Thực hiện truy vấn trong Cơ sở Kiến thức RAG

**Yêu cầu:**
```json
{
  "project": "00000000-0000-0000-0000-000000000000",
  "excludeCollections": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "question": "What is this product?",
  "yourCompanyName": "Acme Corp",
  "yourCompanyAlias": "Acme",
  "customerName": "John Doe",
  "options": [
    "option1",
    "option2"
  ],
  "multiselect": false,
  "nArticles": 5,
  "nFaqs": 3,
  "threshold": 0.5,
  "debug": false,
  "withJustification": true,
  "withConfidenceLevel": true,
  "withFragments": true,
  "nAttempts": 3
}
```

**Phản hồi (200):**
```json
{
  "attempt": 1,
  "preparedQuery": {
    "original": "What is this product?",
    "enhanced": "What is this product and its features?"
  },
  "ragItems": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "distance": 0.25
    }
  ],
  "question": "What is this product?",
  "generalInstructions": "Based on the knowledge base, here is the answer:",
  "text": "This product is a great solution for your needs.",
  "explanation": "The answer was found in multiple sources with high confidence."
}
```

---

#### POST /questionnaire/rag/query-stream

**Tóm tắt:** Thực hiện truy vấn trong Cơ sở Kiến thức RAG

**Yêu cầu:**
```json
{
  "project": "00000000-0000-0000-0000-000000000000",
  "excludeCollections": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "question": "What is this product?",
  "yourCompanyName": "Acme Corp",
  "yourCompanyAlias": "Acme",
  "customerName": "John Doe",
  "options": [
    "option1",
    "option2"
  ],
  "multiselect": false,
  "nArticles": 5,
  "nFaqs": 3,
  "threshold": 0.5,
  "debug": false,
  "withJustification": true,
  "withConfidenceLevel": true,
  "withFragments": true,
  "nAttempts": 3
}
```

**Phản hồi (200):**
```json
[
  {
    "text": "This product is a great solution",
    "fragments": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "part": 1,
        "distance": 0.25,
        "type": "Article",
        "code": "ART-001",
        "title": "Product Title",
        "fragment": "Product content fragment"
      }
    ]
  },
  {
    "text": " for your needs.",
    "fragments": []
  }
]
```

---

#### POST /questionnaire/rag/query-fragments

**Tóm tắt:** Thực hiện truy vấn trong Cơ sở Kiến thức RAG

**Yêu cầu:**
```json
{
  "project": "00000000-0000-0000-0000-000000000000",
  "exclude_documents": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "query": "What is this product?",
  "top_k": 5,
  "similarity_threshold": 0.5,
  "prepare_query": true
}
```

**Phản hồi (200):**
```json
{
  "results": [
    {
      "document_id": "00000000-0000-0000-0000-000000000000",
      "document_code": "ART-001",
      "document_title": "Product Title",
      "revision": 3,
      "chunk_index": 0,
      "content": "Product content fragment",
      "metadata": {
        "author": "John Doe",
        "created_at": "2025-01-15T10:30:00Z",
        "last_updated_at": "2025-01-15T10:35:00Z",
        "doc_categories": [
          "Product",
          "Information"
        ]
      },
      "similarity_score": 0.85
    }
  ]
}
```

## Bài viết liên quan

- [API Tokens – Tạo & Quản lý](/api-tokens/) – cách tạo và quản lý token  
- [Hỏi AI với cơ sở tri thức của bạn](/ask-ai-with-your-knowledge-base/) – sử dụng truy vấn RAG