Truy xuất thông tin quỹ mở

Nhóm hàm này giúp bạn tự truy xuất thông tin quỹ mở (chứng chỉ quỹ) tại Việt Nam: danh mục quỹ kèm NAV mới nhất, lịch sử NAV, mười khoản nắm giữ lớn nhất, tỷ trọng theo ngành và loại tài sản, biểu phí, tài liệu quỹ, lợi nhuận theo kỳ và cổ tức tiền mặt.

Hàm nằm ở hai chỗ, theo đúng cách chia của thư viện:

• Reference().fund: thông tin ít thay đổi. Danh mục quỹ, hồ sơ, biểu phí, tài liệu.
• Market().fund(symbol): số liệu biến động của một quỹ. NAV, lợi nhuận, cổ tức, danh mục nắm giữ.

Hai nguồn được hỗ trợ. Không truyền source thì thư viện dùng CafeF. DigiInvest có thêm tên quỹ, phí quản lý, ngày thành lập trong danh mục, lịch sử NAV dài hơn, và là nguồn duy nhất có cổ tức quỹ.

1. Khởi tạo

from vnstock import Market, Reference

ref = Reference()
mkt = Market()

Mã quỹ là mã chứng chỉ quỹ, ví dụ DCDS, VESAF, SSISCA. Thư viện không phân biệt chữ hoa, chữ thường.

2. Danh mục quỹ — Reference().fund.list()

ref.fund.list(fund_type=None, symbol=None, *, source=None)

funds = ref.fund.list()                          # mọi quỹ
bond_funds = ref.fund.list("bond_fund")          # chỉ quỹ trái phiếu
dc_funds = ref.fund.list(symbol="DC", source="digiinvest")

Trả về một dòng cho mỗi quỹ: ticker, organ_name, organ_short_name, fund_type, management_fee, inception_date, nav, nav_update_at.

Dữ liệu mẫu (source="digiinvest", chạy ngày 06/10/2026):

Hai nguồn khác nhau ở mấy chỗ đáng biết:

3. Thông tin một quỹ — Reference().fund(symbol)

Gắn mã quỹ một lần rồi gọi các hàm bên dưới, hoặc truyền mã vào từng hàm:

dcds = ref.fund("DCDS")
dcds.profile()
ref.fund.profile("DCDS")   # cùng kết quả

profile() — hồ sơ quỹ

Một dòng gồm: công ty quản lý, mô tả chiến lược, ngày thành lập, tổng tài sản (đồng), số tiền đầu tư tối thiểu (đồng), ngày giao dịch, đại lý chuyển nhượng, chỉ số tham chiếu, NAV mới nhất và trang web của quỹ.

p = ref.fund("DCDS").profile()
p[["ticker", "total_assets", "min_investment", "trading_frequency", "benchmark", "nav"]]

fee_structure() — biểu phí

Phí mua, bán, chuyển đổi, mỗi bậc một dòng. Cột range giữ nguyên nhãn bậc như quỹ công bố, vì cùng một loại bậc có quỹ tính theo tháng, có quỹ tính theo năm.

ref.fund("DCDS").fee_structure()

reports() — tài liệu quỹ

Bản cáo bạch, điều lệ, báo cáo định kỳ, kèm đường dẫn tới tệp.

ref.fund("DCDS").reports()

Ba hàm profile(), fee_structure(), reports() chỉ có từ CafeF.

4. NAV, lợi nhuận và cổ tức — Market().fund(symbol)

history() — lịch sử NAV

mkt.fund("DCDS").history(source=None)

Trả về NAV trên một chứng chỉ quỹ theo từng kỳ quỹ công bố, cũ nhất trước: time, nav. Không có tham số start, end: hàm trả toàn bộ lịch sử nguồn có, bạn tự cắt theo ngày.

nav = mkt.fund("DCDS").history()
nav[nav["time"] >= "2026-01-01"]

ohlcv() là tên khác của history(). Quỹ mở chỉ công bố NAV, không có giá mở, cao, thấp, đóng.

performance() — lợi nhuận theo kỳ

Lợi nhuận từ đầu năm, 3 năm và 5 năm, đúng ba kỳ mà trang quỹ công bố. Kỳ 3 năm và 5 năm là lợi nhuận kép bình quân mỗi năm, cột annualized cho biết dòng nào như vậy.

mkt.fund("DCDS").performance()

dividends() — cổ tức tiền mặt

Số tiền chia trên mỗi chứng chỉ quỹ (đồng), mới nhất trước. Chỉ DigiInvest có dữ liệu này, nên thư viện tự dùng DigiInvest. Quỹ chưa từng chia cổ tức trả về bảng rỗng.

mkt.fund("DCDE").dividends()

5. Danh mục nắm giữ — Market().fund(symbol)

Ba hàm đọc từ báo cáo danh mục hằng tháng gần nhất của quỹ, chỉ có từ CafeF.

holdings() — mười khoản nắm giữ lớn nhất

mkt.fund("DCDS").holdings()

• update_at là ngày cuối của tháng báo cáo. Nguồn chỉ ghi "theo báo cáo tháng 12/2025", không ghi ngày cụ thể.
• asset_type là equity (cổ phiếu) hoặc bond (trái phiếu). Quỹ trái phiếu liệt kê trái phiếu trong cùng bảng.
• Quỹ không công bố danh mục, hoặc chưa có báo cáo, trả về bảng rỗng có đủ cột, không báo lỗi.

industry_allocation() — tỷ trọng theo ngành

mkt.fund("DCDS").industry_allocation()

asset_allocation() — tỷ trọng theo loại tài sản

mkt.fund("DCDS").asset_allocation()

Tổng các dòng có thể nhỏ hơn 100 khi quỹ có loại tài sản mà báo cáo không tách riêng.

6. Bảng hàm và nguồn

Gọi một hàm với nguồn không có ô ✅ nhận lỗi UnsupportedError mã VNSTOCK_CAPABILITY_UNAVAILABLE.

7. Chuyển từ Fund() và Fmarket

Bản 4.x và vnstock_data lấy dữ liệu quỹ từ Fmarket. Fmarket đã gỡ khỏi thư viện; các tên hàm cũ nay trả dữ liệu từ CafeF.

Mã cũ vẫn chạy tới hết ngày 06/04/2027. Mỗi lần gọi tên cũ, thư viện phát một FutureWarning nêu tên thay thế. Tên cũ trả đúng bộ cột và thứ tự cột như trước, ngày vẫn là chuỗi YYYY-MM-DD, nên mã đang đọc df["nav_per_unit"] hay df["stock_code"] không phải sửa ngay. Sau ngày 06/04/2027, tên cũ ngừng hoạt động.

Market().fund(symbol).nav() không bị ngừng, và vẫn trả bộ cột cũ date, nav_per_unit, short_name như ở vnstock_data. Cần cột chuẩn thì dùng history().

Tên mới khác tên cũ ở đâu

Tên mới trả bộ cột chuẩn của thế hệ 5. Khi chuyển, đổi tên cột theo bảng này; bộ cột đầy đủ của cả hai bên nằm ở mục Cấu trúc dữ liệu chi tiết từng bảng.

Trước và sau:

# Trước (vnstock 4.x, vnstock_data)
from vnstock import Fund
fund = Fund()
fund_id = fund.filter("SSISCA")["id"].iloc[0]
nav = fund.nav_report(fundId=fund_id)
nav["date"] = pd.to_datetime(nav["date"])
latest = nav["nav_per_unit"].iloc[-1]

# Sau (thế hệ 5)
from vnstock import Market
nav = Market().fund("SSISCA").history()   # cột time đã là datetime
latest = nav["nav"].iloc[-1]

Những chỗ không giữ được như cũ

• fundId dạng số không còn dùng được. Đó là mã nội bộ của Fmarket. Truyền mã quỹ thay vào: Fund().nav_report("SSISCA"). Truyền số thì nhận lỗi InputError mã VNSTOCK_INPUT_SYMBOL. Fund().filter() nay trả cột id chính là mã quỹ, nên mã cũ lấy id từ filter() rồi truyền vào fundId= vẫn chạy.
• Gọi tên cũ mà không truyền mã quỹ thì báo lỗi. Bản cũ tự lấy quỹ có mã nội bộ 23.
• source="fmarket" báo lỗi UnsupportedError mã VNSTOCK_FEATURE_REMOVED, kèm gợi ý dùng source="cafef".
• Cột không còn nguồn nào có thì để trống. Fund().listing() vẫn đủ 21 cột, nhưng mười cột nav_change_*, fund_id_fmarket, fund_code, vsd_fee_id không có giá trị. Lợi nhuận theo kỳ nay ở Market().fund(sym).performance(), hoặc tự tính từ history(). Cột fundId của bảng nắm giữ cũng để trống.
• Ít quỹ hơn. Fmarket từng liệt kê 68 quỹ. Đếm ngày 06/10/2026, CafeF có 43 quỹ, DigiInvest có 33.
• Fund().details và thuộc tính Fund().fund_list của bản 4.x không còn. Dùng các hàm ở bảng trên.

Muốn tắt cảnh báo trong lúc chưa kịp sửa mã:

import warnings
# Chỉ tắt cảnh báo của các tên quỹ cũ, các cảnh báo khác vẫn hiện
warnings.filterwarnings("ignore", category=FutureWarning, message=".*06/04/2027")

8. Lỗi thường gặp

Riêng Fund().listing() giữ cách cũ: loại quỹ lạ chỉ phát UserWarning rồi trả về mọi quỹ.

9. Ví dụ: so sánh NAV một năm của các quỹ cổ phiếu

import pandas as pd
from vnstock import Market, Reference

funds = Reference().fund.list("equity_fund")
cutoff = pd.Timestamp.now(tz="Asia/Ho_Chi_Minh") - pd.DateOffset(years=1)

rows = []
for ticker in funds["ticker"].head(10):
    nav = Market().fund(ticker).history()
    past = nav[nav["time"] <= cutoff]
    if past.empty:
        continue  # quỹ mới thành lập chưa đủ một năm
    start, end = past["nav"].iloc[-1], nav["nav"].iloc[-1]
    rows.append({"ticker": ticker, "nav_1y_change_percent": round((end / start - 1) * 100, 2)})

pd.DataFrame(rows).sort_values("nav_1y_change_percent", ascending=False)

Vòng lặp gọi một lần cho mỗi quỹ. Giữ danh sách ngắn và để khoảng nghỉ giữa các lần chạy, để không dồn lượt truy vấn lên nguồn.

10. Lưu ý về dữ liệu

• Số liệu là những gì CafeF và DigiInvest công bố tại thời điểm bạn chạy. Thư viện không sửa giá trị. Gặp chỗ lạ thì đối chiếu với nguồn còn lại, hoặc với tài liệu của chính quỹ ở reports(). Ví dụ ngày 06/10/2026, profile() của DCDS ghi ngày thành lập 20/05/2024 theo CafeF, còn danh mục DigiInvest ghi 20/05/2004.
• Mọi cột ngày giờ ở tên mới là datetime64 múi giờ Asia/Ho_Chi_Minh. So sánh với chuỗi "2026-01-01" vẫn chạy như ví dụ ở mục 4.
• Mỗi bảng mang df.attrs cho biết nguồn (source), mã quỹ (symbol) và số dòng (length).
• Thông tin ở đây phục vụ việc tự nghiên cứu, không phải khuyến nghị mua, bán hay nắm giữ chứng chỉ quỹ nào.

11. Cấu trúc dữ liệu chi tiết từng bảng

Quy ước chung

• Thứ tự cột cố định như bảng dưới. Index là RangeIndex bắt đầu từ 0.
• Bảng rỗng vẫn có đủ cột và đúng kiểu. Mã của bạn không cần kiểm tra cột có tồn tại không.
• Cột phần trăm ghi theo thang 0–100: 11.46 nghĩa là 11,46%.
• Mọi số tiền tính bằng đồng.
• Cột "Bắt buộc" luôn có giá trị ở mọi dòng.
• Mỗi bảng mang df.attrs gồm ít nhất source (nguồn trả lời) và length (số dòng); bảng của một quỹ có thêm symbol.

Reference().fund.list()

Một dòng cho mỗi quỹ. Tuyến: reference.fund.list.

Reference().fund.profile()

Đúng một dòng. Nguồn CafeF.

Reference().fund.fee_structure()

Mỗi bậc phí một dòng. Nguồn CafeF.

Reference().fund.reports()

Mỗi tài liệu một dòng. Nguồn CafeF.

Market().fund(symbol).history(), .ohlcv()

Mỗi kỳ công bố NAV một dòng, cũ nhất trước.

Market().fund(symbol).performance()

Ba dòng: ytd, 3y, 5y. Nguồn CafeF.

Market().fund(symbol).dividends()

Mỗi lần chia một dòng, mới nhất trước. Nguồn DigiInvest.

Market().fund(symbol).holdings()

Tối đa mười dòng theo báo cáo danh mục tháng gần nhất. Nguồn CafeF.

Market().fund(symbol).industry_allocation()

Mỗi ngành một dòng. Nguồn CafeF.

Market().fund(symbol).asset_allocation()

Mỗi loại tài sản một dòng. Nguồn CafeF.