Vnstock Logo

V3.2

Cập nhật lần cuối:

Thảo luận

Mục lục

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 tích hợp toàn diện nguồn dữ liệu chuyên sâu của 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 tối đa hệ thống dữ liệu.

📌 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ố _vn hoặc _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() (Nguồn mới) hoặc Macro().currency().deposit_rate()Legacy (Vẫn hoạt động)
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)

Lớp CommodityPrice() cũ truy xuất từ hệ thống SPL. Cấu trúc mới Macro().commodity() sử dụng dữ liệu quốc tế của ASEAN làm mặc định, và tích hợp cơ chế Fallback (tự động chuyển nguồn) khi người dùng truy vấn hàng hoá nội địa.

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().gold_vn()Macro().commodity().gold(market="VN")
CommodityPrice().steel_hrc()Macro().commodity().steel()
CommodityPrice().steel_d10()Macro().commodity().steel(market="VN")
CommodityPrice().pork_north_vn()Macro().commodity().pork(market="VN")
CommodityPrice().oil_crude()Macro().commodity().oil_crude()

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

  1. Thay chữ CommodityPrice() bằng Macro().commodity().
  2. Lược bỏ hậu tố _vn hoặc _global trong tên hàm (VD: gold_vn() chuyển thành gold()).
  3. Truyền thêm tham số market="VN" nếu muốn lấy dữ liệu nội địa Việt Nam.

📋 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 proxy 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ăngLegacy 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
Cào nội dung báoChỉ KBS, schema khác biệtHỗ trợ mode=detail cho mọi nguồn (VCI, KBS, CAFEF)
Khung thời gianVCI 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).
  • Gói vnstock_news chuyên dùng để cào tin tức đại chúng chưa dán nhãn trực tiếp từ các trang báo (thích hợp làm nguyên liệu thô cho mô hình ML/AI hoặc sử dụng AI Agent để gán nhã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())

Thảo luận

Đang tải bình luận...