Insights API

Quick Reference

• Base URL: https://insights.omisell.com/api/v1
• Auth: Authorization: Omi <token>
• Content-Type: application/json

Endpoints Overview

Method	Endpoint	Mô tả	Auth
GET	/api/v1/insights/	Danh sách insights	Yes
GET	/api/v1/insights/{queryCode}	Chi tiết insight	Yes
POST	/api/v1/insights/{queryCode}/execute	Execute insight	Yes
POST	/api/v1/insights/{queryCode}/rate	Đánh giá insight	Yes
GET	/api/v1/search/?q={query}	Tìm kiếm insights	Yes
POST	/api/v1/notifications/insight-requests	Yêu cầu insight mới	Yes

---

GET /api/v1/insights/

Lấy danh sách tất cả insights có sẵn.

Response (200 OK): InsightRead[]

Field	Type	Mô tả
query_code	string	Mã insight (VD: "O1-01")
name	string	Tên insight
description	string	Mô tả chi tiết
category	string	Phân loại (revenue, fulfillment, shipping...)
seller_type	SellerType	boxme_only, omisell_only, boxme_and_omisell
granularities	string[]	Mức thời gian hỗ trợ
filter_config	FilterConfig[]	Cấu hình bộ lọc
chart_hint	ChartHint?	Gợi ý visualization mặc định
sort_config	SortConfig[]?	Cấu hình sắp xếp
average_rating	number?	Rating trung bình
rating_count	number?	Số lượt đánh giá
when_to_use	string?	Khi nào nên dùng insight này
outcome	string?	Kết quả mong đợi
tags	string[]?	Nhãn phân loại

Source: (api.service.ts:47-49, api.models.ts — InsightRead)

---

GET /api/v1/insights/:queryCode

Lấy chi tiết một insight.

Parameters

Name	Location	Type	Required	Mô tả
queryCode	path	string	Yes	Mã insight (VD: "O1-01")

Response (200 OK): InsightRead

Cùng schema với item trong danh sách.

Source: (api.service.ts:51-53)

---

POST /api/v1/insights/:queryCode/execute

Execute insight với các tham số.

Parameters

Name	Location	Type	Required	Mô tả
queryCode	path	string	Yes	Mã insight

Request Body: ExecuteRequest

Field	Type	Required	Default	Mô tả
granularity	string	Yes	—	day, week, month, quarter, year
end_date	string?	No	today	Ngày kết thúc (YYYY-MM-DD)
year_month	string?	No	—	Tháng/năm (YYYY-MM)
country	string?	No	—	Mã quốc gia (VN, TH, ID)
sort_by	string?	No	—	Cột sắp xếp
sort_order	'asc' | 'desc'	No	desc	Thứ tự sắp xếp
filters	Record<string, unknown>	No	—	Bộ lọc tùy chỉnh
limit	number?	No	—	Giới hạn số dòng

Response (200 OK): ExecuteResponse

Field	Type	Mô tả
data	DataRow[]	Dữ liệu kết quả
chart_hint	ChartHint?	Gợi ý visualization
alerts	Alert[]?	Cảnh báo
total_rows	number	Tổng số dòng
execution_time_ms	number	Thời gian thực thi (ms)

Source: (api.service.ts:55-60)

Request Example

{
  "granularity": "day",
  "end_date": "2026-04-14",
  "country": "VN",
  "sort_by": "revenue",
  "sort_order": "desc",
  "limit": 10
}

---

POST /api/v1/insights/:queryCode/rate

Đánh giá chất lượng insight.

Request Body: RateRequest

Field	Type	Required	Mô tả
rating	number	Yes	Đánh giá 1-5
comment	string?	No	Nhận xét

Response: 204 No Content

Source: (api.service.ts:62-67)

---

GET /api/v1/search/?q=:query

Tìm kiếm insights theo keyword.

Parameters

Name	Location	Type	Required	Mô tả
q	query	string	Yes	Từ khóa tìm kiếm

Response (200 OK): SearchResult[]

Field	Type	Mô tả
query_code	string	Mã insight
name	string	Tên insight
description	string	Mô tả
score	number	Điểm relevance

Source: (api.service.ts:70-73)

---

POST /api/v1/notifications/insight-requests

Gửi yêu cầu tạo insight mới.

Request Body: InsightRequest

Field	Type	Required	Mô tả
title	string	Yes	Tiêu đề yêu cầu
description	string	Yes	Mô tả chi tiết
desired_data	string	Yes	Dữ liệu mong muốn

Response: 204 No Content

Source: (api.service.ts:152-157)

Liên kết

• API Index — Tổng quan API
• AI Chat API — Chat AI tự do
• SOP: Insight Catalog — Hướng dẫn sử dụng