Chuyển từ thế hệ 5

Trang này dành cho mã đang dùng vnstock thế hệ 5. Các bước dưới đây giúp bạn xác định phần nào tiếp tục chạy, phần nào cần sửa và cách giữ tên cột cũ trong thời gian chuyển đổi.

Thứ tự nên làm

1. Cài thế hệ 6 vào môi trường Python riêng, cạnh môi trường đang chạy.
2. Đăng ký khoá ở nguồn bạn định dùng, kiểm bằng vnstock doctor và vnstock keys check (Cài đặt).
3. Chọn nguồn: thêm source= vào lời gọi, hoặc đặt một lần bằng vnstock.sources.use(...).
4. Chạy mã cũ. Hồ sơ mặc định v5 giữ tên cột, thứ tự cột, đơn vị, mốc giờ như thế hệ 5.
5. Đọc các cảnh báo SchemaChangeWarning và df.attrs["schema_changes"] để biết bảng nào khác thế hệ 5.
6. Đối chiếu vài bảng giữa hai thế hệ.

Phần giữ nguyên

• Tên lớp, tên nhóm, tên hàm thế hệ 5: Market().equity("FPT").ohlcv(...), Reference().equity.list(), các tên khác như history, price_board, intraday; các hàm gọi thẳng trên Market() (Market().quote(...)), nhóm Market().future(...), chỉ số quốc tế Market().index(..., scope="global"), lớp Retail.
• Tên, thứ tự cột, đơn vị giá (đồng ở bảng giá, nghìn đồng ở nến), tỷ lệ phần trăm, match_type, kiểu số.
• Mốc giờ nến ngày 07:00+07:00; tài sản quốc tế theo UTC; ở hồ sơ v5, luồng tiền xếp mới nhất trước.
• length, count_back, limit, floating của nến, ở mọi nhóm có nến: cổ phiếu, chỉ số, phái sinh, chứng quyền, tiền mã hoá, ngoại hối, hàng hoá, chỉ số quốc tế.
• resolution, count của nến vẫn chạy, kèm CompatibilityWarning; đổi sang interval, count_back.
• Tham số theo vị trí và tên tham số của thế hệ 5 (mục dưới).
• Các khoá df.attrs của thế hệ 5: symbols, limit, exchange, group, language (None khi lời gọi không đặt).
• Các lệnh vnstock trong terminal: login, status, doctor, version, update, language, telemetry; gõ vnstock không kèm lệnh vẫn mở giao diện tương tác (Dòng lệnh).

Những gì khác thế hệ 5

Tên gọi theo cách khác của thế hệ 5

Mọi tên của thế hệ 5 vẫn gọi được. Hàm có dữ liệu thì chạy; hàm chưa có dữ liệu báo UnsupportedError có mã, không báo AttributeError. Vài tên chạy qua hàm của nhóm, bảng trả về là bảng của hàm đó:

Tên đã báo ngừng ở thế hệ 5 (Market().pe(), Macro().cpi(), Reference().derivatives()…) báo lỗi có mã, kèm lời gọi thay thế mà thế hệ 5 đã ghi trong exc.action.

Tham số của thế hệ 5

Lời gọi viết cho thế hệ 5 được đọc theo cách của thế hệ 5. Không lời gọi nào ra kết quả khác mà không báo: hoặc chạy như thế hệ 5, hoặc báo VNSTOCK_INPUT_PARAM nói rõ vì sao.

• Theo vị trí. Ở chỗ thế hệ 5 đặt tham số khác, giá trị đọc theo thứ tự thế hệ 5: trades(1000) là limit=1000, foreign_flow(30) là limit=30, Reference().fund.profile("DCDS") là symbol="DCDS", Reference().index.members("VN30") là rổ VN30. Giá trị là ngày (trades("2026-10-01")) vẫn là start.
• Tên cũ. page_size của intraday() là limit; symbols_list là symbols.
• Làm tại máy khi nguồn không làm được. Kết quả ghi ở df.attrs["filtered_locally"]:
  • lọc theo cột: event_type của events.calendar(), fund_type của fund.list(), icb_code của list_by_industry(), side của trades(), mã của put_through("FPT,VNM");
  • cắt khoảng thời gian: start, end của events.market();
  • giới hạn số dòng: limit của block_trades(), put_through(), insider_deal() (giữ các dòng mới nhất).
• Chỉ nhận giá trị mặc định. Tham số không có tương đương ở thế hệ 6 (lang, mode, locale, last_id, last_time, page, window_size, bond_type, resolution của trade_history()) nhận giá trị mặc định của thế hệ 5 hoặc None. Giá trị khác, ví dụ lang="en", báo VNSTOCK_INPUT_PARAM kèm các tham số hàm nhận.

help(), gợi ý của IDE và vnstock doc <hàm> chỉ hiện tham số của thế hệ 6. Mã mới nên viết theo đó.

Cột không còn

Open API chính thức không gửi một số trường mà thế hệ 5 lấy từ nguồn khác, nên các cột đó không có trong bảng (SCH-A01). Mã đọc các cột này báo KeyError.

Báo cáo tài chính

Ba hàm balance_sheet(), income_statement(), cash_flow() giữ tên, giữ hai cách gọi và giữ mã chỉ tiêu của thế hệ 5. Phần lớn mã cũ chỉ cần thêm nguồn:

from vnstock import Fundamental

# Thế hệ 5
Fundamental().equity("FPT").income_statement(period="year")

# Thế hệ 6: thêm nguồn, phần còn lại giữ nguyên
Fundamental().equity("FPT").income_statement(period="year", source="fhsc")
Fundamental().equity.balance_sheet("VCB", period="year", source="fhsc")

Đặt nguồn một lần cho cả nhóm thì không phải sửa từng lời gọi:

import vnstock
vnstock.sources.use("fhsc", route="fundamental.equity.*")
vnstock.sources.save()

Phần giữ nguyên

• Tham số period, lang, drop_empty, format và các cách viết cũ của chúng ("yearly", "Q"…). com_type vẫn nhận, tên mới là company_type, cùng các giá trị "bank", "tctd", "ctck", "dnpnt"…
• period=None lấy cả năm và quý trong một bảng.
• Mã chỉ tiêu (BS_TOTAL_ASSETS, IS_NET_REVENUE, CF_NET_CASH_FLOWS_FROM_OPERATING_ACTIVITIES…), cấp chỉ tiêu, thứ tự trình bày.
• Ở hồ sơ v5: tên cột period, id, name, order, level, off_balance, unit, value; đơn vị "VNĐ"; dạng rộng có cột item.
• Chi phí mang dấu âm.
• Quy tắc bộ chỉ tiêu: khoá có Gói quyền sử dụng còn hiệu lực nhận bộ đầy đủ, các trường hợp khác nhận bộ rút gọn chỉ gồm chỉ tiêu cấp 1.

Những gì khác thế hệ 5

Mã chỉ tiêu đổi

Một số mã chỉ tiêu chỉ có ở thế hệ 5, vì thế hệ 6 chỉ giữ các dòng có trên mẫu biểu mà nguồn gửi số:

• Chỉ tiêu ngoài bảng của ngân hàng và công ty chứng khoán (bảo lãnh, cam kết ngoại tệ, thư tín dụng, tài sản tài chính nhận giữ hộ…): nguồn chưa gửi.
• Lưu chuyển tiền của khách hàng ở báo cáo công ty chứng khoán (CF_CUSTOMER_*, CF_BROKER*, CF_CLEARING_*): nguồn chưa gửi.
• Mã có hậu tố _LEGACY và các dòng tổng trung gian riêng của cách trình bày cũ: thế hệ 6 dùng mã theo mẫu biểu.
• Hai dòng ánh xạ lại theo mẫu biểu, đã đối chiếu với báo cáo tài chính đã kiểm toán:

Muốn biết mã nào có trong bảng, xem cột id của chính bảng trả về, hoặc gọi với drop_empty=False để thấy đủ cây chỉ tiêu của mẫu biểu.

Đối chiếu giữa hai thế hệ

Hai thế hệ đọc từ hai nguồn khác nhau. Mỗi nguồn có cách xếp một số khoản vào dòng chỉ tiêu riêng, và có lúc dùng số đã trình bày lại, có lúc dùng số gốc. Vì vậy cùng một kỳ, cùng một mã chỉ tiêu có thể ra số khác nhau. Khi đối chiếu:

1. Ghép hai bảng theo period và id, chỉ so những ô hai bên đều có số.
2. Bắt đầu từ các dòng tổng: tổng cộng tài sản, doanh thu thuần, lợi nhuận sau thuế, lưu chuyển tiền thuần.
3. Chỗ nào lệch thì mở báo cáo gốc mà doanh nghiệp đã công bố để xem dòng đó thuộc mã số nào.

Thay ratio() bằng vnstock_quant

Thế hệ 5 đã báo ratio() sắp ngừng (tới 15/01/2027): mỗi nguồn tự tính bảng chỉ số theo công thức riêng mà bạn không kiểm được. Ở thế hệ 6, bạn tính các chỉ số đó trên máy bằng vnstock_quant.fa, từ ba báo cáo đã chuẩn hoá, với công thức tra được bằng fa.describe("<mã>"). Mã chỉ số giữ như cũ: 52 trong 55 mã của bảng ratio() có trong fa.catalog().

# Thế hệ 5
Fundamental().equity("FPT").ratio(period="year")

# Thế hệ 6 + vnstock_quant
from vnstock import Fundamental
from vnstock_quant import fa

eq = Fundamental().equity("FPT")
frames = [
    getattr(eq, report)(period=period, source="fhsc", compat="v5")
    for report in ("income_statement", "balance_sheet", "cash_flow")
    for period in ("year", "quarter")
]
ds = fa.Dataset.from_frames({"FPT": frames})
fa.ratios(ds, period="year")                      # dạng long: symbol, period, id, value, unit, reason
fa.ratios(ds, period="year", format="wide")       # mỗi kỳ một cột, gần dạng rộng của ratio()

Cách cài, các điểm cần lưu ý (bộ chỉ tiêu đầy đủ, công ty chứng khoán, chỉ số định giá) xem ở Tính chỉ số tài chính.

Đối chiếu với thế hệ 5. Phép so dưới đây đặt ratio(period="year") của thế hệ 5 cạnh fa.ratios(period="year") tính từ báo cáo thế hệ 6 (nguồn fhsc, bộ chỉ tiêu đầy đủ) trên FPT, HPG (doanh nghiệp), VCB (ngân hàng), SSI (công ty chứng khoán), các năm 2023 tới 2025, ngày 06/11/2026. Ở 32 mã chỉ số mà hai bên cùng có số và cùng định nghĩa, 173 trên 177 ô lệch không quá 0,1%. Ví dụ năm 2025:

Những chỗ khác nhau, và việc bạn cần làm:

Ở kỳ quý, chênh lệch đến từ số liệu đầu vào, không đến từ công thức. Ví dụ lợi nhuận của cổ đông công ty mẹ SSI quý 4/2024 là 296,9 tỷ đồng ở nguồn thế hệ 5 và 427,7 tỷ đồng ở fhsc, trong khi lợi nhuận sau thuế hai bên cùng là 438,4 tỷ đồng. Lệch như vậy làm ROE theo 12 tháng gần nhất của SSI chênh tới 11% ở vài quý. Khi gặp, hãy mở báo cáo gốc để đối chiếu.

Cảnh báo thay đổi

Khi một bảng khác thế hệ 5 theo cách làm hỏng mã cũ hoặc đổi nghĩa con số, thư viện cảnh báo một lần bằng SchemaChangeWarning. Cảnh báo ghi mã thay đổi (SCH-A03…), mức độ và hàm. Mọi bảng còn ghi:

df.attrs["profile"]          # 'v5' hoặc 'v6'
df.attrs["schema_changes"]   # mã các thay đổi so với thế hệ 5 mà bảng này mang

Trợ lý AI và mã kiểm tra đọc hai trường này để biết bảng nào cần đối chiếu.

Chuyển sang chuẩn v6

Hồ sơ v6 đặt một tên, một đơn vị cho mỗi đại lượng trên mọi bảng (Bộ cột và chuẩn hoá):

import vnstock
vnstock.compat.use("v6")                              # mọi kết quả trong tiến trình
Market("<nguồn>").equity("FPT").quote(compat="v6")       # hoặc một lời gọi
# hoặc biến môi trường VNSTOCK_COMPAT=v6 trước khi import

Hai dòng cuối áp dụng từ bản sau 6.0.0rc3.

Danh sách kiểm

• Mọi lời gọi có nguồn, hoặc đã đặt sources.use(...) và lưu bằng sources.save().
• Tham số truyền theo tên ở các hàm trong mục Tham số của thế hệ 5.
• Không còn resolution, count.
• Đã xem các SchemaChangeWarning và bỏ những cột không còn.
• Không dùng id khớp lệnh để ghép giữa hai lần lấy.
• Đã đối chiếu vài bảng giữa hai thế hệ.
• Bỏ mọi đoạn tự hoán đổi total_buy_trade, total_buy_trade_volume và cặp bán của trade_history() (nguồn ssi).
• Báo cáo tài chính: có nguồn fhsc, không còn orient=, đã xem các mã chỉ tiêu đổi.
• ratio() đã đổi sang vnstock_quant.fa.ratios(), đã xem các chỉ số khác định nghĩa ở mục trên.