Hướng Dẫn Chuyển Đổi Sang API Unified UI v3.2.0

Bản cập nhật v3.2.0 (24/5/2026) mở rộng khả năng của vnstock_data bằng việc bổ sung kết nối tới nguồn ASEAN Securities vào kiến trúc Unified UI. Tài liệu này hướng dẫn cách thay đổi cú pháp mã nguồn (code) từ các cấu trúc cũ (Legacy) sang kiến trúc định tuyến mới để khai thác các hàm mới.

📌 1. Tổng Quan Những Thay Đổi Lớn

Cảnh báo

Breaking Changes: Các tính năng lấy dữ liệu Macro/Commodity đã được quy hoạch lại. Tương tự, cấu trúc shareholders() đã có những thay đổi để trả về cấu trúc phân cấp.

Kinh tế Vĩ mô (Macro): Cấu trúc truy xuất Vĩ mô cũ là "phẳng". Cấu trúc mới nhóm hàm theo 3 Domain (economy, currency, global).
Giá Hàng hoá (Commodity): Chuyển sang lớp Macro().commodity(). Lược bỏ hậu tố _global trong tên hàm.
Insights & Analytics (Layer 7): Các tính năng phân tích tâm lý, khối ngoại và tìm kiếm cổ phiếu nằm rải rác ở lớp TopStock và một phần Market đã được quy hoạch chuẩn chỉnh về Insights().

🔄 2. Bảng Chuyển Đổi API (Mapping)

Insights & Analytics (Layer 7)

Trước bản 3.2.0, các tính năng phân tích tâm lý, khối ngoại và tìm kiếm cổ phiếu nằm rải rác ở lớp TopStock và một phần Market. Nay chúng được quy hoạch chuẩn chỉnh về Insights().

Legacy API (Bản < 3.2.0)	Unified UI API (Bản >= 3.2.0)	Tình trạng
`TopStock().gainer()`	`Insights().sentiment.contribution()` (Gợi ý thay thế)	Legacy (Vẫn hoạt động)
`TopStock().foreign_buy()`	`Insights().flow.foreign()`	Legacy (Vẫn hoạt động)
`Market().pe()`	`Insights().equity("MÃ").peer_compare()` hoặc `Insights().sector("MÃ").valuation()`	Cũ (Bị loại bỏ hoặc điều hướng)
Không có	`Insights().sentiment.breadth()`	MỚI
Không có	`Insights().flow.active()`	MỚI
Không có	`Insights().sector("bank").rrg()`	MỚI

Kinh tế Vĩ mô (Layer 6 - Macro)

Cấu trúc truy xuất Vĩ mô cũ là "phẳng" (gọi trực tiếp hàm từ class). Cấu trúc mới nhóm hàm theo 3 Domain (economy, currency, global).

Legacy API (Bản < 3.2.0)	Unified UI API (Bản >= 3.2.0)	Tình trạng
`Macro().gdp()`	`Macro().economy().gdp()`	Legacy (Vẫn hoạt động)
`Macro().cpi()`	`Macro().economy().cpi()`	Legacy (Vẫn hoạt động)
`Macro().interest_rate()`	`Macro().currency().interbank_rate()` hoặc `Macro().currency().deposit_rate()`	Đã gỡ, dùng hàm thay thế
`Macro().exchange_rate()`	`Macro().currency().exchange_rate()`	Legacy (Vẫn hoạt động)
Không có	`Macro().global.bond_yield()`	MỚI
Không có	`Macro().global.fed_rate()`	MỚI

Giá Hàng hoá (Commodity)

Cấu trúc mới Macro().commodity() truy xuất giá hàng hoá quốc tế từ nguồn ASEAN.

Legacy API (Bản < 3.2.0)	Unified UI API (Bản >= 3.2.0)
`CommodityPrice().gold_global()`	`Macro().commodity().gold(market="GLOBAL")` hoặc `Macro().commodity().gold()`
`CommodityPrice().steel_hrc()`	`Macro().commodity().steel()`
`CommodityPrice().oil_crude()`	`Macro().commodity().oil_crude()`

Nguyên tắc chuyển đổi:

Thay chữ CommodityPrice() bằng Macro().commodity().
Lược bỏ hậu tố _global trong tên hàm (VD: gold_global() chuyển thành gold(market="GLOBAL")).

📋 3. Chi Tiết Cập Nhật (Kèm Code Mẫu)

Thay đổi: Chuẩn hoá Cơ cấu Cổ đông & Cổ đông lớn (v3.2.1)

Kể từ phiên bản v3.2.1, phương thức shareholders() được chuẩn hoá nhất quán trên cả API Adapter thường và Unified UI, hỗ trợ tham số mode để gom nhóm các API liên quan đến sở hữu/cơ cấu:

detailed (mặc định): Trả về danh sách chi tiết cổ đông lớn kèm trường phân loại shareholder_type (Individual / Organization).
summary: Trả về cơ cấu sở hữu tổng hợp (tỷ lệ sở hữu nhà nước, nước ngoài, ban lãnh đạo...).

Legacy API (Bản < 3.2.1)	Unified UI/API API (Bản >= 3.2.1)	Nguồn hỗ trợ
`Company(source="KBS").ownership()`	`Company(source="KBS").shareholders(mode="summary")`	KBS (Bị thay thế)
Không hỗ trợ	`Company(source="VCI").shareholders(mode="summary")`	VCI (Mới)
`ref.company("TCB").shareholders()`	`ref.company("TCB").shareholders(mode="summary")` (hoặc `mode="detailed"`)	Unified UI (VCI/KBS)

Ghi chú

Nguồn ASEAN chỉ hỗ trợ mode=detailed. Nếu gọi mode=summary với nguồn ASEAN sẽ ném ra ngoại lệ ValueError tiếng Việt trực quan.
Tất cả các cột dữ liệu của nguồn VCI đã được chuẩn hoá ngắn gọn sang dạng chữ thường (lowercase) chuẩn database (ví dụ: state_percentage, foreign_percentage, v.v.).

Thay đổi: Chuẩn hoá Data Model Tin Tức (company.news)

Kể từ phiên bản v3.2.3, phương thức news() truy xuất tin tức công ty đã được chuẩn hoá (Unified) hoàn toàn giữa các nguồn (VCI, KBS, CAFEF) với cùng một cấu trúc tham số đầu vào và một Data Model đầu ra duy nhất, thay vì schema phân mảnh như trước đây.

1. Tham số hỗ trợ được đồng bộ: Hàm news() hiện hỗ trợ bộ tham số tuỳ chỉnh mạnh mẽ bao gồm: start, end, length (mặc định 90 ngày), limit (mặc định 10000), và mode (list hoặc detail). Tham số **kwargs cũng được chuyển tiếp trực tiếp xuống hàm đích nếu nguồn dữ liệu hỗ trợ.

2. Data Model chuẩn hoá: Tất cả các nguồn sẽ trả về chung một schema 10 cột nhất quán, giúp dễ dàng nối (concat) dữ liệu phân tích: id, symbol, title, summary, content, publish_time, source, url, category, image_url

Tính năng	Legacy API (Bản < 3.2.x)	Unified API (Bản >= 3.2.x)
Cấu trúc trả về	Tuỳ thuộc vào nguồn (khác biệt tên cột)	Schema 10 cột đồng nhất cho mọi nguồn
Lấy nội dung chi tiết bài báo	Chỉ KBS, schema khác biệt	Hỗ trợ `mode=detail` cho mọi nguồn (VCI, KBS, CAFEF)
Khung thời gian	VCI không hỗ trợ	Hỗ trợ `start`, `end`, `length` cho toàn bộ nguồn qua lớp Abstract

Lưu ý Phân Biệt

Phân biệt vnstock_data và vnstock_news:

Hàm news() trong vnstock_data tập trung vào tin tức đã được phân loại cho một doanh nghiệp cụ thể (Bao gồm: thông báo nội bộ, công bố thông tin, tin từ sở giao dịch, tin tức trực tiếp về mã cổ phiếu).
Thư viện vnstock_news chuyên dùng để truy xuất tin tức đại chúng chưa dán nhãn từ các trang báo, trong phạm vi điều kiện sử dụng của từng trang. Bản quyền bài viết thuộc toà soạn.

Khám Phá: Tổng Quan API Tree Mới

Để khám phá trực quan toàn bộ các hàm được hỗ trợ trong hệ thống mới (kèm theo nhãn đánh dấu [Experimental]), bạn chỉ cần gọi 2 lệnh đơn giản:

Python

from vnstock_data import show_api
from vnstock_data.ui import Insights, Macro

# Xem sơ đồ phân tích tâm lý, dòng tiền
show_api(Insights())

# Xem sơ đồ vĩ mô và hàng hoá
show_api(Macro())

Nâng cấp lên bản 3.2

Mục lục